API standards

From version 2021-11 onwards, we abide by a set of standards across all resources and API endpoints. This helps provide a consistent and intuitive experience for developers.

In this article some key global standards we abide by.

Global standards

Attribute keys

  • All attribute keys should be lowercase snake case. Example: order_id
  • All attribute keys on a resource are ordered according to the following standards:
    • The primary key (id) appears first in the object body.
    • Secondary keys relating an object to other resources appear next, in alphabetical order.
    • All other attributes of an object appear next, in alphabetical order.

Formats

  • All date and date-time values are formatted in the ISO 8601 standard and in UTC.
  • All records of a list response will be sorted by id descending unless otherwise specified using a sort_by parameter in the request.
  • The list of attributes in any resource doesn’t change based on the e-commerce platform. For example, references to external IDs such as the product ID or customer ID in the e-commerce platform are contained within a standard field name prefixed by the term external. For example, external_product_id instead of shopify_product_id. This ensures that you don’t have to adjust your integration code based on the underlying e-commerce platform.
  • All external IDs are formatted as strings.
  • All amounts, such as product prices, are formatted as strings.
  • Any rate value inside a tax_lines object is displayed to four decimal places to accurately reflect tax rates. For example, a 12.5% tax rate is reflected as 0.1250.
  • All amounts, such as product prices, are formatted as strings.

Errors

From 2021-11, onward we use the following grid of errors codes:

  • 200 : the request was successful, made no modifications, and the resource requested is in the body.
  • 201 : the request was successful, created a new resource, and resource created is in the body.
  • 202 : the request has been accepted and is in processing.
  • 204 : the request has been processed successfully. There is no response body.
  • 400 : the request was not understood.
  • 401 : the request was not able to be authenticated.
  • 403 : the request was authenticated but not authorized for the requested resource (permission scope error.
  • 404 : the requested resource or record was not found.
  • 406 : the request was unacceptable, or requesting a data source which is not allowed although permissions permit the request.
  • 409 : the request is in conflict, or would create a conflict with an existing request or resource (the route is locked).
  • 415 : the request body was not a JSON object.
  • 422 : the request was understood but cannot be processed due to invalid or missing supplemental information.
  • 426 : the request was made using an invalid API version.
  • 429 : the request has been rate limited.
  • 500 : internal server error.
  • 501 : the resource requested has not been implemented in the current version but may be implemented in the future.
  • 503 : A 3rd party service on which the request depends has timed out.

Need Help? Contact Us