Migration from legacy API to 2024-04

The following guide will help you to migrate the API from the legacy version to the 2024-04 version.

Please note that all users of the legacy Commerce API (accessed via https://api.aftership.com/commerce/v1), are required to contact our support team prior to migrating.

Breaking changes

API changes

What's the difference?

CHANGE	BEFORE	AFTER
Base URL	https://api.aftership.com/commerce/v1	https://api.aftership.com/commerce/2024-04
as-api-version header’s value	won’t return	2024-04

What do I need to do?

1. Update your application's code, replacing the base URL from https://api.aftership.com/commerce/v1 to https://api.aftership.com/commerce/2024-04.
2. Parse the header if you want to identify different versions; otherwise, no action is required.

Business logic changes

Overview

UPDATE	IMPACT
The as-store-id header has changed to the id of the store resource	API endpoint: - POST /orders - GET /orders - POST /products
Add new fields to Store resource: source_id and platform	API endpoint: - POST /stores - GET /stores - PATCH /stores/{id} - GET /stores/{id}
Support listing data which imported from the ecommerce platforms	API endpoint: - GET /stores - GET /orders - GET /products
Add a new field to Order and Product resource: store.id	API endpoint: - POST /orders - GET /orders - PATCH /orders/{id} - GET /orders/{id} - POST /products - PATCH /products/{id} - GET /products/{id}

New fields for Store resource

source_id

A unique identifier for the store in your system.

What do I need to do?

1. Update the API request usage and pass this new field when calling POST /stores endpoint to create a store since it is a required field.

platform

The platform to which the store belongs. For example, if the value is shopify, it indicates that the store originates from Shopify. If the value is aftership, it implies that the store comes from AfterShip.

What do I need to do?

1. Parse the new field in the API response body if you want to fetch the field; otherwise, no action is required.

New field for Order and Product resource

store.id

It will return as a new field in the response body of the resources for products and orders. This unique identifier, generated by AfterShip, indicates which store the data belongs to. You can use this ID to retrieve store details using the GET /stores/{id} API in the Stores API.

What do I need to do?

1. Parse the new field in the API response body if you want to fetch the field; otherwise, no action is required.

Updated API fields

Redefine the as-store-id header

What's the difference?

Change	Before	After
The definition of as-store-id has changed.	The identifier of your store. You need to generate it yourself. Note that this value must consist of numbers and letters (A-Z, a-z, 0-9), and special characters can only be hyphens (-) or underscores (_)	The unique store identifier is generated by AfterShip. You can obtain this id by making a GET /stores call to get existing stores or a POST /stores to create a new store.

What do I need to do?

1. Before creating orders or products, you need to call POST /stores to create a store first. And then, you can use the store.id as the value for the as-store-id header when calling POST /orders and POST /products.

What if I don’t migrate?

If you choose not to migrate, the legacy API will remain supported for at least 24 months. However, following the deprecation of the versioned API, API traffic will be redirected to the 2024-04 version.