Migrate from 2025-04 to 2025-07
The following guide will help you migrate the API and webhook from version 2025-04 to version 2025-07.
1. General API Changes
1.1 Endpoint Change
What's the difference?
| Change | Before | After |
|---|---|---|
| Base URL | https://api.aftership.com/returns/2025-04 | https://api.aftership.com/returns/2025-07 |
| as-api-version response header value | 2025-04 | 2025-07 |
| as-webhook-version request header value | 2025-04 | 2025-07 |
What do I need to do?
Make the following updates to your application's code:
- Replace the base URL from https://api.aftership.com/returns/2025-04 to https://api.aftership.com/returns/2025-07.
- When editing existing URLs or adding new ones, select the webhook version. Please review your webhook settings for verification.
- Parse the header to distinguish between different versions. Otherwise, no action is required.
2. New API Endpoints
The following endpoints are added in API 2025-07:
- POST /returns/{return_id}/remove-items
- POST /returns/rma/{rma_number}/remove-items
- POST /returns/link
What do I need to do?
Make the following updates to your application's code:
- Implement these new endpoints in your code to use this feature. Otherwise, no further action is required.
3. Return Model New Fields Added
| new fields | description |
|---|---|
| shipments[*].ship_to | The ship_to field represents the destination address of the shipment and will only have a value when using AfterShip Shipment to print labels. |
| shipments[*].ship_from | The ship_from field represents the source address of the shipment and will only have a value when using AfterShip Shipment to print labels. |
| refunds[*].transactions | The transactions field represents the transaction records on the e-commerce platform associated with the refund, including the transaction ID and other details. Currently, this is only available for Shopify. |
| order.customer.locale | The locale field represents the language code of the customer, e.g., en-US. |
| exchange.order.customer.locale | The locale field represents the language code of the customer, e.g., en-US. |
What do I need to do?
Simply parse the new field in the API response and the webhook body to fetch the data. Otherwise, no action is required.
4. Returns Endpoints Common Changes
4.1 New fields added in return
Please refer to the Return Model New Fields Added section of the guide.
5. Webhook Changes
5.1 New fields added in return
Please refer to the Return Model New Fields Added section of the guide.