Migrate from 2024-07 or 2024-10 to 2025-07

Purpose and Scope

This guide helps migrate integrations from (2024-07 or 2024-10) to version 2025-07 of the Commerce API.

Quick Migration Checklist

• Set the as-store-id header using store.id from GET /stores on 2025-07.
• Replace source_id with id where applicable.
• Orders: stop using items.*.fulfillable_quantity; apply field renames.
• Fulfillment: remove ship_to_location; apply field and parameter renames.
• Stores: enforce id constraints when creating; update parameter rename.
• Apply field constraints (values, formats, lengths) listed below.

Global Updates

All Endpoints

The Base URL for the API has been updated. You must update the version in the URL path for all your API requests.

• Before: https://api.aftership.com/commerce/2024-07 or https://api.aftership.com/commerce/2024-10
• After: https://api.aftership.com/commerce/2025-07

Headers

• as-store-id: Get store.id via GET /stores (2025-07) and pass it as the value of the as-store-id header.

Historical ID Compatibility

• ID Reference Change: Starting from version 2025-04, the API uses your original custom ID as the primary identifier.
• Legacy UUIDs: The internal AfterShip UUIDs (e.g., 417f7cc7...) returned by API versions 2024-10 or earlier are no longer recognized as valid references in version 2025-07.
• Action Required: When referencing an order in 2025-07 (e.g., the order_id field in Fulfillment or Returns), you must use the source_id you originally provided during order creation.

Example (Fulfillment Creation):

• Old API (2024-10): You provided source_id: "USA04879288" and received AfterShip ID 417f7cc7....

• New API (2025-07): In the POST /fulfillments request, you must set "order_id": "USA04879288". Using the UUID 417f7cc7... will result in an Order Not Found error.

Resource Changes

Orders

Affected Endpoints

• POST /orders
• GET /orders
• PATCH /orders/{order_id}

Remove

Path	Applies To
order.items.*.fulfillable_quantity	Request & Response

Rename

Path (Before)	Path (After)	Applies To
source_id	id	Request & Response
order.items.*.source_id	order.items.*.id	Request & Response
items.*.source_product_id	items.*.product_id	Request & Response
items.*.source_variant_id	items.*.product_variant_id	Request & Response
customer.source_id	customer.id	Request & Response
source_ids (GET /orders)	ids	GET /orders query

Products

Affected Endpoints

• POST /products
• GET /products/{product_id}
• PATCH /products/{product_id}

Rename

Path (Before)	Path (After)	Applies To
source_id	id	Request & Response
variants.*.source_id	variants.*.id	Request & Response

Fulfillment

Affected Endpoints

• POST /fulfillments
• GET /fulfillments
• GET /fulfillments/{fulfillment_id}
• PATCH /fulfillments/{fulfillment_id}

Rename

Path (Before)	Path (After)	Applies To
source_id	id	Request & Response
source_order_id	order_id	Request & Response
line_items.*.source_id	line_items.*.id	Request & Response
line_items.*.source_product_variant_id	line_items.*.product_variant_id	Request & Response
source_ids (GET /fulfillments)	ids	GET /fulfillments query
source_order_id (GET /fulfillments)	order_id	GET /fulfillments query

Remove

Path	Applies To
ship_to_location	Request & Response

Stores

Affected Endpoints

• POST /stores
• GET /stores
• GET /stores/{store_id}
• PATCH /stores/{store_id}

Rename

Path (Before)	Path (After)	Applies To
source_id (POST /stores request)	id	Request body
source_ids (GET /stores query)	ids	GET /stores query

Create Rules

Rule	Applies To
Store id must not start with prefix app-	POST /stores
Store id must be unique within the organization	POST /stores

Field Constraints

Orders

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.

Products

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.

Stores

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.