Breaking Change Log

🚧

Stay informed on breaking changes

Make sure to subscribe to Breaking Change announcements to stay in the loop! We announce breaking changes to impacted API clients as well as all subscribers to this list.

Breaking Change Release: Oct 17, 2022

These changes will be released for all clients, regardless of API version. You can access these changes in advance by including the HTTP Header Enable-New-Errors: true.

Changes:

1. For all API endpoints, the error response body is being updated to a consistent format.
2. In cases where a 400 HTTP status code was returned we will sometimes return a 422 instead.

Current Error Format:

Our error response formats today are inconsistent, but the following is the most common:

{ 
    "error": "a message" 
}

New Error Format:

On October 17, all API endpoints will be updated to use the following error response format:

{ 
    "errors": { 
        "foo": [ 
            "a validation error message for field foo" 
        ], 
        "bar": [
            "a validation error message for field bar"
        ]
    }
}

Notes:

• The error field is renamed from "error" to "errors"
• The error key "general" will be used if the error is not related to a parameter.

Example:

$ curl -s -X PATCH https://api.convictional.com/products/61610c4ee0d92553a43bc13e/variants/618d3b3e3994235378fb3360 \
    -H 'Authorization: xxxxx' \
    -d '{"inventoryQuantity": -1}'

{
    "errors": {
        "inventoryQuantity": [
            "must be greater than 0"
        ]
    }
}

Breaking Change Release: Aug 3, 2022

These changes will be released for all clients, regardless of API version.

For the GET /products and GET /products/:id endpoints we are changing the overall response body to use an envelope pattern to better align with the rest of our API. For GET /products/, the array of data will be found under "data". The responses as follows:

{
  "data": [
    { ...Product object...}
  ]
}

For the GET /products/:id, the response will be:

{
  "data": { ... Product Object ... }
}

All other changes will be updates to fields within the Product resource.

• We are updating the product ID to be located at id instead of _id.
• We are updating the inventory quantity on the variant to be inventoryQuantity instead of inventory_quantity.
• We are updating the created field at the root of the Product to be createdAt instead.
• We are updating the updated field at the root of the Product to be updatedAt instead.

Version 2022-03-03

Removed the following fields from the Order resource. See our migration guide for more details.

• order.addresses
• order.charge
• order.code
• order.companyId
• order.date
• order.email
• order.invoiceId
• order.parentCode
• order.partner
• order.tags

Impacted endpoints:

• List orders - GET /orders
• Get order - GET /orders/{orderId}
• Update order - PATCH /orders/{orderId}
• Cancel order - POST /orders/{orderId}/cancel

🚧

Unlisted Changes

Some unlisted endpoints have had breaking changes. If you use any unlisted endpoints please contact support for details.