Past Changelog

This page contains the past changelog. For the changelog of the current version, 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.

2025-01 (2025-01-09)

1. General

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

2. Order Resource Changes

2.1 Updated Fields

order.items.*.id

BEFORE	AFTER
order.items.*.source_id	order.items.*.id

Affected Endpoints (Request and Response Body)

• POST /orders (request_body.items.*.id)

Affected Endpoints (Response Body)

• GET /orders
• GET /orders/{id}
• PATCH /orders/{id}

2.2 Removed Fields

order.items.*.fulfillable_quantity

BEFORE	AFTER
order.items.*.fulfillable_quantity	Field deleted

Affected Endpoints (Request and Response Body)

• POST /orders

Affected Endpoints (Response Body)

• GET /orders
• GET /orders/{id}
• PATCH /orders/{id}

2.3 Required Fields Changes

FIELD	BEFORE	AFTER
order.items.*.product_title	Field value is optional	Field value is now required
order.items.*.product_variant_title	Field value is required	Field value is now optional

Affected Endpoints (Request Body)

• POST /orders

3. Order Endpoints Changes

3.1 Update an order by ID (PATCH /orders/{id})

Request Body

The following fields are added to the request body to provide more control to the endpoint. The specification of each of the fields are the same as the model.

• currency
• order_total
• shipping_total
• tax_total
• discount_total
• subtotal

4. Product Resource Changes

4.1 Required Fields Changes

FIELD	BEFORE	AFTER
title	Field value is required	Field value is optional

Affected Endpoints (Request body)

• POST /products

5. Fulfillment Resource Changes

5.1 Updated Fields

fulfillment.line_items.*.id

BEFORE	AFTER
fulfillment.line_items.*.source_id	fulfillment.line_items.*.id

Affected Endpoints (Request and Response Body)

• POST /fulfillments (request_body.line_items.*.id)

Affected Endpoints (Response Body)

• GET /fulfillments
• GET /fulfillments/{id}
• PATCH /fulfillments/{id}
• POST /fulfillments/{id}/update-status
• POST /fulfillments/{id}/ship

6. New API Endpoints

New endpoints for manipulating order.items (OrderItem resource) are added. As the OrderItem resource is a subresource of Order, order.id is required during the request, which would be specified in the URL.

For the detailed endpoint specification, please refer to the API endpoint reference.

1. Create an order item (POST /orders/{id}/items)
   • Create a new order item to an existing order.
2. Get order item by ID (GET /orders/{id}/items/{item_id})
   • Get an existing order item by order ID and order item ID.
3. Update order item by ID (PATCH /orders/{id}/items/{item_id})
   • Update an existing order item by order ID and order item ID.
4. Delete order item by ID (DELETE /orders/{id}/items/{item_id})
   • Delete an existing order item by order ID and order item ID.

2024-10 (2024-10-10)

1. General

CHANGE	BEFORE	AFTER
Base URL	https://api.aftership.com/commerce/2024-07	https://api.aftership.com/commerce/2024-10

2. Order Resource Changes

2.1 New Fields

order.status_timestamps

The status_timestamps field enables you to record the exact timestamp when an order status occurs, such as when the order is canceled or placed.

When order.status is set to canceled, the timestamp recorded in order.status_timestamps.canceled_at will be displayed on the history route of the branded tracking page, indicating the time when the order was canceled.

For detailed information about the model, please refer to the full specifications.

order.custom_fields

The new custom_fields feature allows you to store limited metadata for orders using your preferred key-value pairs. This functionality provides greater control over the notification workflow, enabling you to use custom fields as triggers to determine specific branches of the notification flow.

2.2 Create an Order (POST /orders)

New Request Fields

• order.status_timestamps
• order.custom_fields

Response

See Order Resource changes.

2.3 Update an Order (PATCH /orders/{id})

New Request Fields

• order.status_timestamps
• order.custom_fields

Response

See Order Resource changes.

2.4 List Orders (GET /orders)

Response

See Order Resource changes.

2.5 Get an Order (GET /orders/{id})

Response

See Order Resource changes.

2024-07 (2024-07-11)

1. General

CHANGE	BEFORE	AFTER
Base URL	https://api.aftership.com/commerce/2024-04	https://api.aftership.com/commerce/2024-07

2. New Feature

• The fulfillment related features support BOPIS (Buy Online, Pick up In Store) scenario
• Support next_couriers for AfterShip Tracking

All functionalities related to shipments have been moved to the new resource fulfillments and its API endpoints, the shipments field is no longer in use and has been removed.

3. New API Endpoint and Resource

New resource fulfillment is added. The Fulfillment model encapsulates the details of processing and delivering orders in an eCommerce context. It includes information such as fulfillment status, shipment tracking, the items to be fulfilled, and so on.

For the detailed endpoint specification, please refer to the API endpoint reference.

1. Create a Fulfillment (POST /fulfillments)
   • Supports the creation of different delivery_methods of fulfillments, including pickup and shipping .
2. Update a Fulfillment (PATCH /fulfillments/{id})
   • Allows updating the information of a fulfillment with the fulfillment ID.
3. Update Status (POST /fulfillments/{id}/update-status)
   • Allows updating the status based on the delivery_method of fulfillment.
4. Ship Fulfillment (POST /fulfillments/{id}/ship)
   • Allows shipping operations for a fulfillment with a specified ID.
5. Get Fulfillments (GET /fulfillments)
   • Retrieves a list of all fulfillments for an order.
6. Get Fulfillment by ID (GET /fulfillments/{id})
   • Retrieves detailed information about a specific fulfillment using its ID.

4. Order Resource Changes

4.1 New Fields

• order.delivery_method (Required)
• order.pickup_location
• order.pickup_info
• order.items.*.product_title

4.2 Removed Fields

• order.shipments
• order.shipping_address.tax_number
• order.shipping_address.source_id
• order.shipping_address.description
• order.billing_address.tax_number
• order.billing_address.source_id
• order.billing_address.description

4.3 Renamed Fields

Object	BEFORE	AFTER
order.shipping_address order.billing_address	address_line_1 address_line_2 address_line_3	street_1 street_2 street_3
order.items.*	title	product_variant_title

4.4 Specification Changes

CHANGE	BEFORE	AFTER
Structure of order.items.*.unit_price	String e.g. 1.2	Object e.g. {"currency": "USD", "amount": "1.2"}

4.5 Create an order (POST /orders) Changes

Behavioral Update

POST /orders endpoint now rejects requests containing an existing order ID.

In earlier versions, API users could invoke the POST /orders endpoint with an existing order ID to perform an "upsert" operation, which updates an existing order if it already exists. Starting from version 2024-07, this behavior has been deprecated. To update an existing order, please use the PATCH /orders/{order_id} endpoint.

New Request Fields

• order.delivery_method (Required)
• order.pickup_location
• order.pickup_info

Removed Request Fields

• order.shipments
• order.shipping_address.tax_number
• order.shipping_address.source_id
• order.shipping_address.description
• order.billing_address.tax_number
• order.billing_address.source_id
• order.billing_address.description

Renamed Request Fields

Object	BEFORE	AFTER
order.shipping_address order.billing_address	address_line_1 address_line_2 address_line_3	street_1 street_2 street_3
order.items.*	title	product_variant_title

Request Specification Updates

CHANGE	BEFORE	AFTER
Structure of order.items.*.unit_price	String e.g. 1.2	Object e.g. {"currency": "USD", "amount": "1.2"}

Response

See Order Resource changes.

4.6 Update an order (PATCH /orders/{order_id}) Changes

Removed Request Fields

• order.shipments
• order.shipping_address.tax_number
• order.shipping_address.source_id
• order.shipping_address.description
• order.billing_address.tax_number
• order.billing_address.source_id
• order.billing_address.description

Response

See Order Resource changes.

4.7 Get order(s) (GET /orders and GET /orders/{order_id}) Changes

Response

See Order Resource changes.

5. Store Resource Changes

5.1 Added Fields

• store.address.coordinate
• store.address.coordinate.latitude
• store.address.coordinate.longitude

5.2 Removed Fields

• store.plan_name
• store.address.latitude
• store.address.longitude

5.1 Renamed Fields

Object	BEFORE	AFTER
store.address	address_line_1 address_line_2 address_line_3	street_1 street_2 street_3

2024-04 (2024-04-11)

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
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.
Support for listing data from ecommerce platforms	You can only list data that you import through the Commerce API.	You can list data that you import through Integrations.
New store model field	-	source_id platform
New order model field	-	store.id
New product model field	-	store.id

v1.12.0 (2024-03-12)

Update	Resources
add fileds returnable_quantity for order items	orders

v1.11.1 (2023-10-10)

Update	Resources
add fileds service_type and ship_from_address for shipments	orders
add GET /orders	orders
add GET/stores	stores

v1.11.0 (2023-09-25)

Update	Resources
PATCH /orders/:id support to update status,financial_status,fulfillment_status	orders

v1.10.0 (2023-08-03)

Update	Resources
PATCH /orders/:id support to update shipments	orders

v1.9.0 (2023-05-09)

Update	Resources
Add new field to order shipment: custom_fields	orders

v1.8.0 (2023-04-04)

Update	Resources
Add new field to order shipment: source_delivered_at	orders

v1.7.0 (2023-02-24)

Update	Resources
Remove required validation to the following fields of orders: financial_status、fulfillment_status、shipping_total、tax_total、discount_total、subtotal、source_created_at、source_updated_at	POST /orders
Remove required validation to the following fields of orders.items: sku、unit_weight、unit_price	POST /orders
Remove required validation to the following fields of orders.customers: first_name、emails	POST /orders
Remove required validation to the following fields of orders.shipping_address and orders.billing_address: first_name、address_line_1、city、state、country_region	POST /orders
Remove required validation to the following fields of products: slug、source_created_at、source_updated_at	POST /products
Remove required validation to the following fields of products.variants: image_urls、compare_at_price、allow_backorder、options	POST /products
Remove source_id of stores	POST /stores
Remove required validation to the following fields of stores: timezone_identifier、url	POST /stores

v1.6.0 (2022-11-17)

Update	Resources
Add new fields to order item: product_categories、product_tags	orders

v1.5.0 (2022-08-03)

Update	Resources
Add new domain api.aftership.com to replace api.automizely.com	-

v1.4.2 (2022-06-07)

Update	Resources
Add new header as-api-key to replace am-api-key	Headers

v1.4.1 (2022-01-26)

Update	Resources
Add Snatshot fields validation to orders.item. Snatshot fields cannot be changed after creating in Automizely	POST /orders

v1.4.0 (2021-11-23)

Update	Resources
Add new header am-api-key to replace am-app-id	Headers

v1.3.0 (2021-10-29)

Update	Resources
New endpoints	PATCH /products/:id PATCH /orders/:id PATCH /stores/:id

v1.2.0 (2021-10-08)

Update	Resources
Add required validation to the following fields of orders: source_id、number、currency、status、financial_status、fulfillment_status、order_total、shipping_total、tax_total、discount_total、subtotal、source_created_at、source_updated_at	POST /orders
Add required validation to the following fields of orders.items: source_id、sku、quantity、unit_weight、unit_price、title	POST /orders
Add required validation to the following fields of orders.shipments: tracking_number	POST /orders
Add required validation to the following fields of orders.customers: first_name、emails	POST /orders
Add required validation to the following fields of orders.shipping_address and orders.billing_address: first_name、address_line_1、city、state、country_region	POST /orders
Add required validation to the following fields of products.variants: source_id、sku、title、price、image_urls、compare_at_price、allow_backorder、options	POST /products

v1.1.0 (2021-07-27)

Update	Resources
New endpoints	POST /gdpr GET /stores/:id GET /orders/:id GET /products/:id

v1.0.0 (2021-06-02)

Update	Resources
Initial release	-
New endpoints	POST /orders POST /products POST /stores POST /uninstalls