Migrate from legacy to 2024-10

Compared to legacy webhook, our 2024-10 release includes significant changes, but we strive to provide all the capabilities offered by legacy APIs and webhooks in this version. If you are currently using the legacy version of APIs & Webhooks and wish to use the latest Return model and the latest features, please follow the steps below to migrate.

1. API Endpoint Updates

1.1 Update Return Status (POST /returns/rma/{rma_number}/status-transitions)

1.1.1 The endpoint has been splited into three different endpoints in 2024-10

• POST /returns/rma/{rma_number}/approve
• POST /returns/rma/{rma_number}/resolve
• POST /returns/rma/{rma_number}/reject

The original endpoint had 4 types of request bodies, each corresponding to a different case. The migration can be done for each of the use case scenario:

Simple status transitions

Legacy

preparing...

2024-10

In the new version of the API, the corresponding status API can be used directly, and there is no need to manually retrieve from_status as in the legacy version.

preparing...

Rejection

Legacy

preparing...

2024-10

In the new version of the API, can directly use reject endpoint

preparing...

Approval with label url - deprecated flow

Legacy

preparing...

2024-10

In the early version of Returns system, merchants were required to provide a label before performing the approval operation, so the API was designed accordingly. In the latest Return system, providing the label and the approve operation have been decoupled into two separate actions. Therefore, starting from the 2024-10 version, the approve endpoint no longer accepts the label URL. If you still need to do this, please use the attach shipment endpoint instead.

Approval and create label

Legacy

preparing...

2024-10

In the new version of the API, can use approve endpoint with generate_label

preparing...

1.1.2 Add new optional field notify_customer , which allows you to decide whether to notify your customer via email after this operation.

1.2 Batch mark items as received (POST /returns/rma/{rma_number}/item-receive-batch)

Changes from legacy to 2024-10:

• The endpoint is changed to POST /returns/rma/{rma_number}/receive-items.
• Changes in request payload:
  • send_notification is changed to notify_customer.
• The response payload has been updated to the new Return Object.

Legacy

Request:

preparing...

Response:

preparing...

2024-10

Request:

preparing...

Response:

preparing...

1.3 Update return items By RMA (PATCH /returns/rma/{rma_number}/items/{external_id})

Changes from legacy to 2024-10:

• Changes in request payload:
  • merchant_tags is changed to item_tags.
  • merchant_images is changed to merchant_uploaded_image_urls , and the type of the field is changed from object to string
• The response payload has been updated to the new ReturnItem Object.

Legacy

Request:

preparing...

Response:

preparing...

2024-10

Request:

preparing...

OR

preparing...

Response:

preparing...

1.4 Batch attach shipments to an RMA (POST /returns/rma/{rma_number}/shipment-batch)

Changes from legacy to 2024-10:

• The endpoint is changed to POST /returns/rma/{rma_number}/attach-shipments.
• Changes in request payload:
  • shipments[*].label.aftership_tracking_slug is changed to shipments[*].label.slug
  • type of shipments[*].label.total_charge.amount is changed from number to string
  • send_notification is changed to notify_customer
• The response payload has been updated to the new Return Object.

Legacy

Request:

preparing...

Response:

preparing...

2024-10

Request:

preparing...

Response:

preparing...

1.5 List Return Item Tags (GET /merchant-tags)

Changes from legacy to 2024-10:

• The endpoint is changed to GET /returns/rma/{rma_number}/item-tags
• Changes in response payload:
  • merchant_tags is changed to item_tags

Legacy

Request:

preparing...

Response:

preparing...

2024-10

Request:

preparing...

Response:

preparing...

2. Webhook updates

2.1 Migrate from the legacy version to 2024-10

To address some of the shortcomings in the Legacy version, we re-design a new webhook starting from the 2024-07 version. The main changes compared to the legacy version are as follows:

• More detailed events.

  In the legacy version, only a limited number of events were provided. This led to the issue of supporting fewer scenarios, makes it difficult for merchants to automate in various processes effectively.

• Redesigned the payload structure - We provide two fields in webhooks, modified and data , start from 2024-07.

  In the legacy version, only an event name and a Return object were provided. When developers only receive the event name and a Return object at the time of occurrence, it becomes difficult to accurately determine the specific changes that occurred. For example, when receiving a return.shipment.created event, developers couldn’t determine which specific shipment had been created based on the event payload.

  The new webhook introduces a modified field to indicate the piece of data changed/produced in each particular event, aka delta data. In the example of return.shipment.created event, the modified field includes the created tracking number, label pdf, etc.

  The data field always returns the Return object at the time the event occurs.

If you are using events from the legacy version, we expect you will find corresponding alternatives in the 2024-10 version:

Legacy Events	Alternatives in 2024-10
return.created	return.submitted
return.updated	The return.updated event in the legacy version was designed as a very coarse-grained event, where any update in the return would trigger this event. In the 2024-10 version, finding a corresponding alternative depends on how you previously used this event. For developers who used this event to receive primary status changes, you can use events such as return.approved, return.resolved, and others.
return.approved	return.approved
return.shipment.created	If the shipment should be provided by merchant, use return.shipment.provided instead. If the shipment should be provided by shopper, use return.shipment.recorded instead.
return.shipments.created	If the shipment should be provided by merchant, use return.shipments.provided instead. Currently, we do not support shoppers providing multiple shipments, so no available event for this case for now.
return.shipment.updated	return.shipment.updated
return.dropoff.created	return.dropoff.created
return.dropoff.updated	return.dropoff.updated
return.dropoff.shipment.updated	return.dropoff.shipment.updated