Save an export column preset

POST/v1/api/store/{team_slug}/data_export/presets

v1Operation ID v1_public_data_export_presets_store

Saves a named set of columns for one export type. By default it is a personal preset that only you see. The team owner can save it as the team default (is_team_default: true), which is shared with everyone and replaces the previous default for that type.

Presets can't be edited: delete one and save it again.

Permission

Any member for a personal preset. Only the team owner can save a team default.

Business rules

• name is required, up to 120 characters, and not blank. Names don't have to be unique.
• type must be one of the nine export types, and columns a non-empty list of that type's column ids.
• Saving a team default turns off is_team_default on the type's previous default. That preset stays shared.

Path parameters

• team_slugstringrequired

  Your team slug, shown as Team ID next to your API key in Profile.

  • Example your-team

Request body

application/json, required.

• columnsarray of stringsrequired

  Column ids for this type, in file order. Repeats are dropped. See the definitions operation.

  • At least 1 item
• namestringrequired

  Spaces at either end are removed.

  • 1 to 120 characters
• typestringrequired
  • One of: "customer_list", "sales_order_list", "invoice_list", "invoice_item_list", "payment_list", "purchase_order_list", "tax_list", "simple_product_list", "variant_product_list"
• is_team_defaultboolean

  Team owner only. Shares the preset with the team as the default for this type.

  • Default false

Response

201Successful response.

• dataobjectrequired
  Child fields (6)

  • configobjectrequired
    Child fields (2)

    • columnsarray of strings

      Column ids, in file order. Send them as columns when you create an export.

    • schema_versioninteger

      Version of the column list (1).

  • idstringrequired

    The preset id. Use it to delete the preset.

  • is_team_defaultbooleanrequired

    The team's default preset for this type. At most one per type.

  • namestringrequired
  • typestringrequired
    • One of: "customer_list", "sales_order_list", "invoice_list", "invoice_item_list", "payment_list", "purchase_order_list", "tax_list", "simple_product_list", "variant_product_list"
  • user_idstring | nullrequired

    Your user id (a hash id) for a personal preset; null for a shared team preset.

• statusintegerrequired
• successbooleanrequired

Errors

• 401The API key is missing or wrong (unauthenticated).

• 403You are not the team owner and sent is_team_default: true.

  When

  You are not the team owner and sent is_team_default: true (team_default_forbidden, "Only the team owner can set a team default.").

  Fix

  Save it as a personal preset, or ask the team owner.

• 404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.

• 422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.

  When

  name is missing, blank, not a string or over 120 characters; type is missing or not a string; or is_team_default is not a boolean (invalid_export_request, "Enter a valid preset name, export type and default setting.").

  Fix

  Send a name of 1 to 120 characters, a type, and is_team_default as true or false or not at all.

  When

  columns is missing or not a list (invalid_export_request, "The selected export columns are invalid.").

  Fix

  Send columns as a list of column ids.

  When

  type is not one of the nine export types (invalid_export_request, "Unsupported export type.").

  Fix

  Use a type the definitions operation lists.

  When

  A column id is not one of this type's columns, or is not a string (invalid_export_request, "The selected export columns are invalid."), or columns is empty ("Select at least one export column.").

  Fix

  Use column ids the definitions operation lists for this type.

Notes

• Each refusal names the first problem only. The checks run in the order of the errors above: name, type and default setting; columns is a list; type is known; the column ids; and only then the team owner check.
• These 422 answers have no error.fields: the problem is in error.message, for example {"status": 422, "success": false, "error": {"code": "invalid_export_request", "message": "Unsupported export type."}}.

Related

• GETList export column presets/v1/api/store/{team_slug}/data_export/presets
• GETList export types and their columns/v1/api/store/{team_slug}/data_export/definitions

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/data_export/presets' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "columns": [      "invoice_id",      "customer_name",      "total",      "tax"    ],    "is_team_default": false,    "name": "Accounting",    "type": "invoice_list"  }'

Example response 201

Response

{
  "data": {
    "config": {
      "columns": [
        "invoice_id",
        "customer_name",
        "total",
        "tax"
      ],
      "schema_version": 1
    },
    "id": "ZUFZpcm8jcw4J0",
    "is_team_default": false,
    "name": "Accounting",
    "type": "invoice_list",
    "user_id": "VG7s3tFzyQbO2N"
  },
  "status": 201,
  "success": true
}