Migrate from 2025-01 to 2025-04

This migration guide outlines the essential changes required to maintain the same functionality when transitioning from the previous API version. It does not cover any new resources or endpoints, and does not cover any relaxed conditional changes that do not involve breaking changes (such as a required field becoming optional).

For comprehensive details on new features, please refer to the Changelog for a complete overview of all API updates.

1. All Endpoints

• For creating resources (Create an order, create a product, etc.), do not pass source_id in the request body. If you need to provide your own resource ID, put it in id directly.

• For getting resources by ID (Get an order by ID, get a product by ID, etc.), if you need to get the resource created by the API earlier than 2025-04, you need to use the source_id retrieved from the earlier API, and use it as the id field, and put into the API endpoint. Refer to the Changelog (2.3.1) for details.

Header

as-store-id

Please retrieve the store.id with the GET /stores endpoint on the latest 2025-04 Commerce API as the value of as-store-id header.

2. Store Endpoints

Affected Endpoints (Request and Response Body)

• POST /stores

Affected Endpoints (Response Body)

• GET /stores
• GET /stores/{id}
• PATCH /stores/{id}

How to migrate

• For POST /stores endpoint, rename source_id to id in the request body, no action required if this field is not utilized.

• The id can no longer start with the reserved prefix app- when creating a new store, no action required if this field is not utilized or the app- prefix is not used.

• The id must be unique within the organization, no action required if this field is not utilized.

• For GET /stores, rename source_ids to ids in the query parameters, no action required if this field is not utilized.

3. Order Endpoints

Affected Endpoints (Request and Response Body)

• POST /orders
• POST /orders/{id}/items
• PATCH /orders/{id}/items/{item_id}

Affected Endpoints (Response Body)

• GET /orders
• GET /orders/{id}
• GET /orders/{id}/items/{item_id}

How to migrate

• rename source_id to id in the request body or query parameters, no action required if this field is not utilized.

• rename items.*.source_product_id to items.*.product_id in the request body or query parameters, no action required if this field is not utilized.

• rename items.*.source_variant_id to items.*.product_variant_id in the request body or query parameters, no action required if this field is not utilized.

• rename customer.source_id to customer.id in the request body or query parameters, no action required if this field is not utilized.

• For GET /orders, rename source_ids to ids in the query parameters, no action required if this field is not utilized.

• For POST /orders/:id/items, if the error response code is utilized, make sure to support HTTP Status code 409 instead of 422, and response_body.meta.code 40900 instead of 42200 respectively, in case of the error of duplicated order item ID. No action required if this field is not utilized.

4. Product Endpoints

Affected Endpoints (Request and Response Body)

• POST /products
• PATCH /products/{id}

Affected Endpoints (Response Body)

• GET /orders
• GET /orders/{id}

How to migrate

• rename source_id to id in the request body or query parameters, no action required if this field is not utilized.

• rename variants.*.source_id to variants.*.id in the request body or query parameters, no action required if this field is not utilized.

5. Fulfillment Endpoints

Affected Endpoints (Request and Response Body)

• POST /fulfillments

Affected Endpoints (Response Body)

• GET /fulfillments
• GET /fulfillments/{id}
• PATCH /fulfillments/{id}

How to migrate

• rename source_id to id in the request body or query parameters, no action required if this field is not utilized.

• rename source_order_id to order_id in the request body, no action required if this field is not utilized.

• rename line_items.*.source_product_id to line_items.*.product_id in the request body or query parameters, no action required if this field is not utilized.

• rename line_items.*.source_product_variant_id to line_items.*.product_variant_id in the request body or query parameters, no action required if this field is not utilized.

• For GET /fulfillments, rename source_ids to ids in the query parameters, no action required if this field is not utilized.

• For GET /fulfillments, rename source_order_id to order_id in the query parameters, no action required if this field is not utilized.

6. Field Values Limitation

Please refer to the Changelog (7) for details and changes your input values accordingly if it exceeds the limitaiton.

Migrate from legacy API to Versioned API

For all legacy API user (with the API URL https://api.aftership.com/commerce/v1), please visit 2024-04 migration guide for the detail instruction.