Migrate from 2026-01 to 2026-07

This migration guide outlines the essential changes required to maintain the same functionality when transitioning from the previous API version. It does not cover new optional resources or endpoints, and does not cover relaxed conditional changes that do not involve breaking changes.

For comprehensive details on new features, please refer to the Changelog for a complete overview of all API updates.

1. 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/2026-01
• After: https://api.aftership.com/commerce/2026-07

2. New Location Resource

Version 2026-07 introduces the new Location resource and related endpoints:

• POST /locations
• GET /locations
• GET /locations/{id}
• PATCH /locations/{id}

This is a new optional resource. Existing integrations do not need to change unless they want to manage locations through Commerce API.

3. pickup_location.location_id / ship_from_location.location_id Now Uses the Location Resource ID

In 2026-01 and earlier, the location_id on order.pickup_location, fulfillment.pickup_location, and fulfillment.ship_from_location required the AfterShip internal warehouse UUID, which was not exposed by any Commerce API endpoint. From 2026-07, this field only accepts the public Location ID returned by the new Location Resource (§2 of Changelog).

Migration Steps

1. Use GET /locations to obtain the public id for each location your integration references (or remember the id returned by POST /locations).
2. Replace any hard-coded internal warehouse UUID values with the corresponding Location id.

Example

Before (2026-01):

After (2026-07):

For platform-sourced locations, use the composite Location id in the form app-<platform>-<app_key>-<external_id>.

If the supplied location_id does not match any Location under the organization, the endpoint returns 422 Unprocessable Entity with info: "The location does not exist." on the corresponding request_body.*.location_id path.

Migrate from legacy API to Versioned API

For all legacy API user (with the API URL https://api.aftership.com/commerce/v1), please visit 2024-04 migration guide for the detail instruction.