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

• For fetching resources created by the API earlier than 2025-04, use the source_id retrieved from the earlier API as the id when calling the 2025-07 API.

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.