Migrate from 2025-07 to 2026-01

The following guide will help you migrate the API and webhook from version 2025-07 to version 2026-01.

1. General API Changes

1.1 Endpoint Change

What's the difference?

Change	Before	After
Base URL	https://api.aftership.com/returns/2025-07	https://api.aftership.com/returns/2026-01
as-api-version response header value	2025-07	2026-01
as-webhook-version request header value	2025-07	2026-01

What do I need to do?

Make the following updates to your application's code:

1. Replace the base URL from https://api.aftership.com/returns/2025-07 to https://api.aftership.com/returns/2026-01.
2. When editing existing URLs or adding new ones, select the webhook version. Please review your webhook settings for verification.
3. Parse the header to distinguish between different versions. Otherwise, no action is required.

2. Return Model New Fields Added

new fields	description
contact_email	The contact_email field represents the contact email address for the return.
shipping_address	The shipping_address field represents the ship-from location address for the return.
is_gift_return	The is_gift_return field is a boolean value indicating whether the return is a gift return.
exchange.items[*].product_image_urls	The product_image_urls field represents an array of URLs pointing to the exchange item’s product images.

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.

3. Return Model Fields Removed

The following fields are removed in the API 2026-01 version:

removed fields	description
gift_return	The gift_return field has been removed.

Why was gift_return removed?

We now provide contact_email and shipping_address as recipient information fields, supporting both gift return and non-gift return scenarios. Therefore, a separate gift_return field is no longer required.

If you were previously using the gift_return field to determine whether an RMA is a gift return, you can now use the new is_gift_return field instead.

3.1 Gift Return Field Migration Reference

Purpose	Old Field (2025-07)	New Field (2026-01)
Determine if it's a gift return	gift_return (presence check)	is_gift_return
Contact email	gift_return.email	contact_email
Shipping address	gift_return.shipping_address	shipping_address

What do I need to do?

Make the following updates to your application's code:

1. Remove any references to the gift_return field.
2. Use is_gift_return to check if a return is a gift return.
3. Use contact_email and shipping_address directly instead of accessing them through gift_return.

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.

4.2 Fields removed from return

Please refer to the Return Model Fields Removed 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.

5.2 Fields removed in return

Please refer to the Return Model Fields Removed section of the guide.