Migrate from 2025-07 to 2026-01

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

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

2. Fulfillment Endpoints

Affected Endpoints (Request and Response Body)

• POST /fulfillments
• PATCH /fulfillments/{id}

Affected Endpoints (Response Body only)

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

Removed Endpoints

• POST /fulfillments/{id}/ship

How to migrate

• Replace the ship endpoint: The POST /fulfillments/{id}/ship endpoint has been removed. You must update your integration to use PATCH /fulfillments/{id} instead. To achieve the same result (updating the status to shipped), send a request body containing {"status": "shipped"}.

• Update trackings logic: The trackings object now enforces strict mutual exclusivity between two usage modes. You must review your code to ensure you are using the correct mode:

  • Reference Mode (Recommended): Pass the tracking ID which was created via the Tracking API. This mode links to a full tracking resource.
    • Action: If providing id, ensure tracking_number and slug are removed from the payload.
  • Inline Mode: Provide a tracking_number (and optional slug). This is strictly for record-keeping purposes and does not create an active tracking task; the system will not provide status updates for this number.
    • Action: If providing tracking_number, ensure id is removed from the payload.

  Note: Providing both id and tracking_number in the same object will now result in an error.

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.