Migrate from 2024-04 to 2025-07

Purpose and Scope

This guide helps migrate integrations from 2024-04 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 in requests and queries.
• Orders: remove deprecated fields, apply field renames, and update items.*.unit_price structure.
• Move order.shipments to the Fulfillment resource.
• Stores: rename address_line_* to street_*; move latitude/longitude to coordinate.
• Apply field constraints (values, formats, lengths) listed below.
• For GET /orders, rename query parameter source_ids to ids.
• For GET /stores, rename query parameter source_ids to ids.
• Stop using POST for upsert; use PATCH /{resource}/{id} to update.

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-04
• 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.

Create vs Update (Upsert removed)

• Endpoints for creating resources no longer accept an existing id.
• Affected endpoints: POST /orders, POST /products, POST /stores.
• To update an existing resource, use PATCH /{resource}/{id}.

Resource Changes

Orders

Affected Endpoints

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

Add Required

Path	Applies To
order.delivery_method	POST /orders: Request body

Remove

Path	Applies To
order.shipments	Request & Response
order.shipping_address.tax_number	Request & Response
order.shipping_address.source_id	Request & Response
order.shipping_address.description	Request & Response
order.billing_address.tax_number	Request & Response
order.billing_address.source_id	Request & Response
order.billing_address.description	Request & Response
order.items.*.fulfillable_quantity	Request & Response

Rename

Path (Before)	Path (After)	Applies To
source_id	id	Request/Query & Response
order.shipping_address.address_line_1	order.shipping_address.street_1	Request & Response
order.shipping_address.address_line_2	order.shipping_address.street_2	Request & Response
order.shipping_address.address_line_3	order.shipping_address.street_3	Request & Response
order.billing_address.address_line_1	order.billing_address.street_1	Request & Response
order.billing_address.address_line_2	order.billing_address.street_2	Request & Response
order.billing_address.address_line_3	order.billing_address.street_3	Request & Response
order.items.*.title	order.items.*.product_title	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

Type/Structure Changes

Path	Before	After	Applies To
order.items.*.unit_price	number	{ currency: string, amount: number }	Request & Response

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 (replacement for order.shipments)

Affected Endpoints

• Fulfillment resource endpoints (refer to API reference)

Order-to-Fulfillment Mapping

Order Field	Fulfillment Field	Description
id	order_id	Order resource ID
shipments	trackings	Shipment information
-	id	The original fulfillment ID in your system
-	type	Use "shipping" for typical non-BOPIS cases
-	status	Fulfillment status
-	line_items	Items to be fulfilled
-	ship_from_location	Ship-from location details

Stores

Affected Endpoints

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

Remove

Path	Applies To
store.plan_name	Request & Response

Rename

Path (Before)	Path (After)	Applies To
store.address.address_line_1	store.address.street_1	Request & Response
store.address.address_line_2	store.address.street_2	Request & Response
store.address.address_line_3	store.address.street_3	Request & Response
source_id	id	Request & Response

Type/Structure Changes

Path (Before)	Path (After)	Applies To
store.address.latitude	store.address.coordinate.latitude	Request & Response
store.address.longitude	store.address.coordinate.longitude	Request & Response

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.