Changelog

This page contains the changelog of the current API version. For the past changelog, please refer to this page.

2025-04 (2025-04-10)

1. General

CHANGE	BEFORE	AFTER
Base URL	https://api.aftership.com/commerce/2025-01	https://api.aftership.com/commerce/2025-04

Header

CHANGE	BEFORE	AFTER
as-store-id value format updated	The UUID generated by AfterShip (The store.id for the version 2025-01 and earlier)	Use store.source_id as the value, you can also retrieve the store.id from the Store resource with the latest 2025-04 API

2. Customizable ID

In the version 2025-04, we introduced Customizable ID across all resources in Commerce API, when creating the resource, you can optionally provide your ID as the resource ID, instead of forcibly using our system-generated ID, and hence provide a much better experience for the case such as being unable to store AfterShip resource ID in your system.

Quick Overview

Aspect	Before (2025-01)	After (2025-04)
Create Resource	POST /{resources} Request: { "source_id": "custom-id-123" }	POST /{resources} Request: { "id": "custom-id-123" }
Get Resource	GET /{resources}/ef123...789ef (system-generated UUID)	GET /{resources}/custom-id-123 (value of the id field)
Update Resource	PATCH /{resources}/ef123...789ef (system-generated UUID)	PATCH /{resources}/custom-id-123 (value of the id field)
System Generated ID	Always generates UUID as resource identifier	Generates UUID only if id not provided

2.1 New id field Specification

• Maximum length: 128 characters
• Allowed pattern: ^[a-zA-Z0-9_-]+$
• Immutable after creation
• If not provided, a system-generated UUID will be assigned

2.2 Creating Resources

In 2025-04, you can optionally provide your ID when creating the resource. Take creating an order as an example:

Request

Please do not include store_id in the request body payload.

Response

If you do not provide the id when creating the resource, AfterShip will generate an ID for you, similar to the earlier API versions:

Request

Response

2.3 Getting or Updating Resources by ID

Same as previous API version, you need to use the ID field returned by the API when creating the resource, to retrieve or update the resource by ID.

Example

2.3.1 Accessing resources created in previous API versions

For all resources created in earlier API versions, you need to use the resource's original source_id value as the id in version 2025-04 to access the resource. You can no longer use the UUID style ID found in the previous API version to access the resource starting from 2025-04 API.

Example

For a resource created in 2025-01 API:

In 2025-01 and earlier versions, the resource could be accessed with the id:

From 2025-04 you can only access this resource with the source_id (now id from 2025-04):

3. Store Resource

3.1 store.id

1. The field has been renamed from source_id to id
2. The id can no longer start with the reserved prefix app- when creating a new store
3. The id must be unique within the organization

Affected Endpoints (Request and Response Body)

• POST /stores

Affected Endpoints (Response Body)

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

3.2 Query Parameter Changes

Parameter	BEFORE	AFTER
Filter by IDs	source_ids[]	ids[]

Affected Endpoints

• GET /stores

4. Order Resource

4.1 Field Renamed

The field has been renamed:

BEFORE	AFTER
source_id	id
items.*.source_product_id	items.*.product_id
items.*.source_variant_id	items.*.product_variant_id
customer.source_id	customer.id

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}

4.2 Query Parameter Changes

Parameter	BEFORE	AFTER
Filter by IDs	source_ids[]	ids[]

Affected Endpoints

• GET /orders

4.3 Response Status Code Changes

Affected Endpoints

• POST /orders/:id/items

When creating the order item with an ID which is already exist in any one of the existing item in the order, the API response error code has been updated, together with the response body meta.code:

Code	BEFORE	AFTER
HTTP Status code	422	409
response_body.meta.code	42200	40900

5. Product Resource

5.1 Field Renamed

BEFORE	AFTER
source_id	id
variants.*.source_id	variants.*.id

Affected Endpoints (Request and Response Body)

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

Affected Endpoints (Response Body)

• GET /products
• GET /products/{id}

5.2 New Endpoints

New endpoints for managing product variants are added. For the detailed endpoint specification, please refer to the API endpoint reference.

1. Product variant management endpoints:
   • POST /products/{id}/variants
   • GET /products/{id}/variants/{variant_id}
   • PATCH /products/{id}/variants/{variant_id}
   • DELETE /products/{id}/variants/{variant_id}
2. Product listing endpoint with pagination support:
   • GET /products

5.3 Updated Endpoints

5.3.1 PATCH /products/{id}

The endpoint now supports updating all variants of a product in a single request:

• Added variants array field in the request body

If variants are provided in the request body, this array will replace all existing variants. Also, variants could not be an empty array if provided in the request body.

6. Fulfillment Resource Changes

6.1 Field Renamed

BEFORE	AFTER
source_id	id
source_order_id	order_id
line_items.*.source_product_id	line_items.*.product_id
line_items.*.source_product_variant_id	line_items.*.product_variant_id

Affected Endpoints (Request and Response Body)

• POST /fulfillments

Affected Endpoints (Response Body)

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

6.2 Query Parameter Changes

Parameter	Changes
source_id	Removed. Use ids[] parameter instead
ids[]	Now accepts values that were previously used in source_id parameter
source_order_id	Renamed to order_id

Affected Endpoints

• GET /fulfillments

7. Field Value Limitation Update

The field value limitation of some fields across multiple resources has been updated accordingly to provide a better using experience.

7.1 Order Resource

Field	Type	Before	After
order_total	Number	No specific limitation	Accepting values >= 0 only.
shipping_total	Number	No specific limitation	Accepting values >= 0 only.
tax_total	Number	No specific limitation	Accepting values >= 0 only.
discount_total	Number	No specific limitation	Accepting values >= 0 only.
subtotal	Number	No specific limitation	Accepting values >= 0 only.
items.*.quantity	Number	Accepting values < 0 or > 0	Accepting values > 0 only.
items.*.unit_weight.value	Number	No specific limitation	Accepting values >= 0 only.
items.*.unit_price.amount	Number	No specific limitation	Accepting values >= 0 only.
items.*.discount	Number	No specific limitation	Accepting values >= 0 only.
items.*.tax	Number	No specific limitation	Accepting values >= 0 only.
items.*.returnable_quantity	Number	No specific limitation	Accepting values >= 0 only.
customer.emails[].*	String	No specific limitation	Max string length: 256 Must be a valid email address following RFC5322.
shipping_address.email	String	Max string length: 254	Max string length: 256 Must be a valid email address following RFC5322.
billing_address.email	String	Max string length: 254	Max string length: 256 Must be a valid email address following RFC5322.

7.2 Product Resource

Field	Type	Before	After
variants.*.available_quantity	Number	No specific limitation	Accepting values >= 0 only.
variants.*.price	Number	No specific limitation	Accepting values >= 0 only.
variants.*.compare_at_price	Number	No specific limitation	Accepting values >= 0 only.
variants.*.weight.value	Number	No specific limitation	Accepting values >= 0 only.

7.3 Store Resource

Field	Type	Before	After
support_email	String	Max string length: 254	Max string length: 256 Must be a valid email address following RFC5322.
owner_email	String	Max string length: 254	Max string length: 256 Must be a valid email address following RFC5322.

7.4 Fulfillment Resource

Field	Type	Before	After
ship_to_location.address.email	String	Max string length: 254	Max string length: 256 Must be a valid email address following RFC5322.