QUICKSTART
API Quick Start
Authentication
SignString
Rate Limit
Body Envelope
Request Errors
CHANGELOG
Changelog
Migration
Migrate from 2025-01
Reference
API Overview
Returns
Get return detail by ID
get
Get return detail by RMA number
get
Get returns
get
Create Return
post
Approve Return By RMA number
post
Approve Return By Return ID
post
Resolve Return By RMA number
post
Resolve Return By Return ID
post
Reject Return By RMA number
post
Reject Return By Return ID
post
Receive items by RMA number
post
Receive items by Return ID
post
Attach shipments by RMA number
post
Attach shipments by Return ID
post
Return Dropoffs
Record dropped-off return items
post
Return items
Update return items by Return ID
patch
Update return items By RMA number
patch
Item tags
Get item tags
get
Model
Primitive
Address
Money
Envelope
Meta
Error
Resource
Return
Return item
Item tag
Webhook
Webhook Overview
Webhook Specifications
Webhook Outgoing IPs
Webhook Signature
Support
Contact Support

Webhook Specifications

Learn how AfterShip Returns verifies and secures all the webhook requests.

Method
POST application/jsonWhen the corresponding event is triggered, we will send a webhook to the address you specified based on your configuration.
The post body contains a JSON string of the below data.
  • id - UUID v4 format, to uniquely identify the webhook event
  • created_at - UTC timestamp in ISO string that the event occurred
  • event - the code of the event
  • modified - details about the message for which the event occurred. Each event will have a different data structure, please refer to the Body chapter below for specifics
  • data - A complete snapshot of the top-level resource (currently all are returns) at the moment the event occurs.

    • 1. Events List

    Event NameDescription
    return.approvedOccurs when a return request is approved.
    return.expiredOccurs when a return request is expired.
    return.rejectedOccurs when a return request is rejected.
    return.resolvedOccurs when a return request is resolved.
    return.submittedOccurs when a return request is successfully submitted.
    return.dropoff.createdOccurs when a drop-off parcel QR code is generated.
    return.dropoff.shipment.updatedOccurs when a shipment of drop-off is updated.
    return.dropoff.updatedOccurs when a drop-off parcel is updated, e.g., when it is handed over to parcel collection location.
    return.restock.createdOccurs when a restock operation is executed via AfterShip.
    return.shipment.providedOccurs when the merchant provides a shipment.
    return.shipment.recordedOccurs when the shopper provides a shipment information.
    return.shipment.updatedOccurs when the tracking status of a shipment changes.
    return.shipments.providedOccurs when the merchant has provided all the necessary shipment information.
    return.exchange.order.createdOccurs when the exchange order has been created
    return.receiving.createdOccurs when the returned items have been received by the merchant.

    Webhooks will be divided into these categories.

    1. Returns
    2. Shipments
    3. Receivings
    4. Refund
    5. Restock
    6. Exchange
    7. Items

    1.1 Returns Events

    Returns event reflects the approval process.

    • return.submitted : When a shopper submitted an RMA.
    • return.approved: When the merchant approves an RMA
    • return.resolved : When the merchant completed all necessary processing for an RMA.
    • return.rejected : When the merchant rejected an RMA
    • return.expired : When an approved RMA expired due to items not being received by merchants.

    1.2 Shipments Events

    The shipments events of the return items appears AFTER an RMA is approved.

    Typically, these events can be integrated with a 3rd party notification system to send different kinds of notifications to shoppers.

    Below is an overview of major events in different cases.

    2.png

    Case: Merchants provide shipping labels

    • return.shipment.provided : When a shipping label with a tracking number is generated/uploaded by the merchant.
    • return.shipments.provided : When all labels of the RMA complete generation/fully supplied. If the RMA only has 1 label to generate, this event will immediately fire after return.shipment.proivdedevent.
    • return.shipment.updated : This is a per-shipment event powered by AfterShip Tracking. It happens for every logistic status updates.
    3.png

    Case: Green Return

    When merchants decide to let the shopper keep the items. The event below is emitted after an RMA is approved.

    • return.shipment.skipped : (Not available yet) Shipment is skipped. Generally, a notification to notify shoppers to keep the returned items can be sent at this moment.
    4.png

    Case: Shoppers upload shipping labels

    • return.shipments.requested : (Not available yet) Shipping instructions are now displayed on the Returns Page to shoppers.
    • return.shipment.recorded : Shoppers uploaded a tracking number of the shipped return items.
    5.png

    1.3 Dropoff Events

    When merchant adopted a parcel collection network like Happy Returns that provides return item drop-off service, that parcel collection network will take charge of items’ collections, packing and shipping back to warehouses with its own source of carriers and tracking system.

    Case: Shopper dropped items at a parcel collection network

    • return.dropoff.created : The parcel collection network is ready to receive the items.
    • return.dropoff.updated : Shoppers dropped the return items at one of the parcel collection hub.
    • return.dropoff.shipment.updated : Return items of the RMA were shipped by the parcel collection network with specific tracking numbers.

    1.4 Restock Events

    • return.restock.created : When some items are restocked to an inventory warehouse.

    2. Headers

    preparing...

    3. Body

    Webhook
    id
    string
    Example:
    3df04d0cdf3c492fad33a15f753fb960
    version
    string
    Example:
    2025-04
    event
    string
    Example:
    return.restock.created
    created_at
    string<date-time>
    Example:
    2024-06-25T06:35:21.798Z
    modified
    data
    Return
    id
    string
    Example:
    b3eedf69b7c0410d8975d4350c007705
    organization
    object
    rma_number
    string
    Example:
    A1B2C3D4
    filed_by
    Allowed values:
    shoppermerchantcustomer_support
    approval_status
    string
    Allowed values:
    submittedapproveddonerejectedexpired
    approved_at
    string or null

    The timestamp when this return was approved.

    auto_approved
    boolean or null

    Indicates whether the return was automatically approved.

    rejected_at
    string or null

    The timestamp when this return was rejected.

    reject_reason
    string or null

    The reason for the return rejection.

    auto_rejected
    boolean or null

    Indicates whether the return was automatically rejected.

    resolved_at
    string or null

    The timestamp when this return was resolved.

    auto_resolved
    boolean or null

    Indicates whether the return was automatically resolved.

    refunded_at
    string or null

    The timestamp when this return was refunded.

    auto_refunded
    boolean or null

    Indicates whether the return was automatically refunded.

    auto_received
    boolean or null

    Indicates whether the return has triggered an automatic receive.

    expired_at
    string or null

    The timestamp when this return was expired.

    shop_now
    boolean

    Whether the "Shop Now" feature (also known as "Exchange for other items") has been used.

    merchant_note
    string or null
    Example:
    This is an internal note
    return_total_including_tax
    return_tax

    The tax amount associated with the return.

    refund_destination
    string or null
    Allowed values:
    original_paymentstore_credit
    refunded_total

    The total amount refunded for the return.

    estimated_refund_total
    checkout_total
    order
    object
    return_items
    array[ReturnItem]
    return_method
    ReturnMethod
    exchange
    instant_exchange
    receivings
    array[Receiving]
    gift_return
    shipments
    array[ReturnShipment]
    restocks
    array[object]
    cost_of_return
    refunds
    array[Refund]
    dropoffs
    array[Dropoff]
    outcomes
    array[string]

    Expected result of the return

    Allowed values:
    exchangerefundupsellstore_credit
    created_at
    string
    Example:
    2024-01-01T00:00:00.001Z
    shipping_status
    string

    The shipping status at the return level.

    Allowed values:
    no_labelpendingin_transitdeliveredpartially_receivedreceivedpartially_droppeddroppedvoid
    exceptions
    array[string]

    Exceptions in the return that require manual handling

    Allowed values:
    exchange_failedrestock_failedgenerate_label_failedrefund_failedcharge_failedflagged