Migrate from 2024-07 to 2025-07

The following guide will help you migrate the API and webhook from version 2024-07 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/2024-07	https://api.aftership.com/returns/2025-07
as-api-version response header value	2024-07	2025-07
as-webhook-version request header value	2024-07	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/2024-07 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. API Endpoint Updates

2.1 Restock

What's the difference?

Change	Before	After
Field name	`restock.items[*].source_order_item_id`	`restock.items[*].external_order_item_id`
Field name	`restock.items[*].location.source_id`	`restock.items[*].location.external_id`

What do I need to do?

Update your code to parse the new field names. Replace source_order_item_id with external_order_item_id and location.source_id with location.external_id.

2.2 ReturnItem

What's the difference?

Change	Before	After
Field name	`return_items[*].exchange_variant.source_product_id`	`return_items[*].exchange_variant.external_product_id`
Field name	`return_items[*].exchange_variant.source_variant_id`	`return_items[*].exchange_variant.external_variant_id`
Field removed	`return_items[*].discounted_price_including_tax`	-
Field added	-	`return_items[*].unit_discounted_price_including_tax`
Field name	`return_items[*].image_urls`	`return_items[*].product_image_urls`

What do I need to do?

Update field names: replace source_product_id with external_product_id and source_variant_id with external_variant_id.
Replace discounted_price_including_tax with unit_discounted_price_including_tax. The discounted_price_including_tax provided in the 2024-07 version is based on the ordered_quantity, which can easily be misused. In the 2024-10 version, we will only provide unit_discounted_price_including_tax, which can be used together with fields like intended_return_quantity, ordered_quantity, etc., to calculate the total amount you need.
Update image_urls to product_image_urls.

2.3 Address

What's the difference?

Change	Before	After
Field structure	`{"country_region": {"name": "USA"}}`	`{"country_region": {"code": "USA"}}`
Field type	`{"state": "Arkansas"}`	`{"state": {"name": "Arkansas"}}`
New fields	-	`contact_name`, `company_name`, `phone`, `email`
What do I need to do?

Update country_region.name to country_region.code.
Update state from a string array to an object array with a name property.
Handle the new Address primitive fields (contact_name, company_name, phone, email), if needed.

2.4 Order

What's the difference?

Change	Before	After
Field name	`order.country`	`order.country_region`

What do I need to do?

Update your code to use order.country_region instead of order.country.

Previously, the data section in the GET /returns response was a simple array. Starting April 2025, the data section will be an object that includes both the return results (data.returns) and pagination details (data.pagination).

Before:

preparing...

After:

preparing...

What do I need to do?

Update your code to parse data.returns instead of data directly, Handle the new data.pagination object if needed.

2.6 GET /returns Query Parameters

What's the difference?

Starting April 2025, the GET /returns API supports additional query parameters:

approval_status
created_at_min
limit
order_name
outcome
page
return_method
customer_email

What do I need to do?

You can use these new query parameters to filter and paginate returns more effectively. No action is required if you don't need these new fields.

3. New API Endpoints

3.1 Endpoints Added

The following endpoints are added:

POST /returns/rma/{rma_number}/approve
POST /returns/returns/{return_id}/approve
POST /returns/rma/{rma_number}/resolve
POST /returns/returns/{return_id}/resolve
POST /returns/rma/{rma_number}/reject
POST /returns/returns/{return_id}/reject
POST /returns/rma/{rma_number}/attach-shipments
POST /returns/returns/{return_id}/attach-shipments
POST /returns/rma/{rma_number}/receive-items
POST /returns/returns/{return_id}/receive-items
PATCH /returns/rma/{rma_number}/items/{item_id}
PATCH /returns/returns/{return_id}/items/{item_id}
GET /item-tags
POST /returns
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 the related features. Otherwise, no further action is required.

4. Return Model New Fields Added

Multiple new fields have been added to the Return model in the 2025-07 version. This section does not list all the details here. Refer to Return Object 2025-07 for more details.

What do I need to do?

Simply parse the new fields in the API response and the webhook body to fetch the data. Otherwise, no action is required.

5. Webhook Updates

5.1 return.restock.created

What's the difference?

As an experiential version of the new webhook design, the 2024-07 version only provided a single event: return.restock.created. While designing the new events for the 2024-10 version, we identified flaws in the design of the modified field. Therefore, corrections have been made in the 2024-10 version.

modified in 2024-07:

preparing...

modified in 2025-07:

preparing...

What do I need to do?

Update your webhook handler to parse the new, modified field structure. The restocks wrapper has been removed, and the field names have been updated to match the API changes.

5.2 New Webhook Events

The following webhook events are added:

return.approved
return.expired
return.rejected
return.resolved
return.submitted
return.dropoff.created
return.dropoff.shipment.updated
return.dropoff.updated
return.shipment.provided
return.shipment.recorded
return.shipment.updated
return.shipments.provided
return.exchange.order.created
return.receiving.created

What do I need to do?

If you want to receive these new webhook events, configure your webhook settings to subscribe to them. Otherwise, no action is required.

5.3 New fields added in return

Please refer to the Return Model New Fields Added section of the guide.

6. What if I don’t migrate?

After June 30, 2026, any requests made to the 2024-07 version will automatically be redirected to the 2025-01 version. While this redirection is designed to minimize disruptions, it may not fully support all functionalities available in the newer versions.Therefore, we encourage you to complete the migration at your earliest convenience.