Return

id
string
Example:
b3eedf69b7c0410d8975d4350c007705
organization
object
id
string
Example:
4f94e5fe178c46a9b976b7d4e646d65a
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
amount
string

The amount represented with two decimal places.

Example:
99.99
currency
string

The currency code, using ISO 4217 standards.

Example:
USD
return_tax

The tax amount associated with the return.

amount
string

The amount represented with two decimal places.

Example:
99.99
currency
string

The currency code, using ISO 4217 standards.

Example:
USD
refund_destination
string or null
Allowed values:
original_paymentstore_credit
refunded_total

The total amount refunded for the return.

amount
string

The amount represented with two decimal places.

Example:
99.99
currency
string

The currency code, using ISO 4217 standards.

Example:
USD
estimated_refund_total
amount
string

The amount represented with two decimal places.

Example:
99.99
currency
string

The currency code, using ISO 4217 standards.

Example:
USD
checkout_total
amount
string

The amount represented with two decimal places.

Example:
99.99
currency
string

The currency code, using ISO 4217 standards.

Example:
USD
order
object
id
string
external_id
string

The order ID of the original order on the e-commerce platform.

Example:
4254002020558
order_number
string

The order number of the original order on the e-commerce platform.

Example:
10001
order_name
string

The order name of the original order on the e-commerce platform.

Example:
#10001
customer
object

The basic information of the customer. Currently, only the customer’s email address is returned.

country_region
string

The sales region of the original order, represented by the ISO 3166-1 alpha-3 country code.

Example:
USA
store
object

The brief information of the store associated with the original order.

placed_at
string<date-time> or null

The date and time when the order was placed, in ISO 8601 format (UTC).

Example:
2024-09-27T10:45:30Z
return_items
array[ReturnItem]
id
string

The ID of the item.

Example:
10579097059534
external_order_item_id
string

The ID of the item on the e-commerce platform.

Example:
10579097059534
external_product_id
string

The ID of the product on the e-commerce platform.

Example:
7002111410382
external_variant_id
string

The ID of the variant on the e-commerce platform.

Example:
41681852399822
sku
string

The SKU of the item.

Example:
t-shirt-blue-xl
product_title
string

The title of the product.

Example:
T-Shirt
intended_return_quantity
integer

The number of items that the customer plans or expects to return.

Example:
2
variant_title
string or null

The title of the variant.

Example:
Blue - XL
return_reason
string

The return reason provided by the customer.

Example:
Wrong size
return_reason_comment
string

Additional information provided by the customer regarding the reason for the return.

Example:
Too Small
return_subreason
string

If the return reason supports sub-reasons, this is the sub-reason provided by the customer.

Example:
Too small
ordered_quantity
integer

The purchase quantity of the item in the original order.

Example:
3
refund_quantity
integer

The number of items that need to be refunded.

Example:
2
return_quantity
integer

The number of items that need to be returned.

Example:
2
received_quantity
integer

The number of items that have been received by the merchant.

Example:
0
restocked_quantity
integer

The number of items that have been restocked by the merchant.

Example:
0
unit_display_price

The display price of each item.

unit_discounted_price_including_tax

The tax-inclusive discounted price for each item, representing the actual amount paid by the buyer.

unit_discount

The discount allocated to each item.

unit_tax

The tax allocated to each item.

properties
array[object]

Custom properties filled in by the customer when purchasing the product.

shopper_uploaded_image_urls
array[string]

The images provided by the customer when submitting a return.

product_image_urls
array[string]

The images of the product.

product_categories
array[string]

The product categories configured on the e-commerce platform.

product_tags
array[string]

The product tags configured on the e-commerce platform.

item_tags
array[ItemTag]

The tags applied by the merchant to this return item.

merchant_uploaded_image_urls
array[string]

The images uploaded by the merchant for this return item.

bundled_items
array[object]

When the item being returned is a whole bundle, this array will represent its child items.

exchange_variant
object or null

Exchange variant associated with this return item. Available only when using replacement.

parent_item_id
string or null

When the item being returned is one of the child items in a bundle, this ID will represent its parent item, which is the bundle ID.

return_method
ReturnMethod
type
string

The type of return method.

Allowed values:
retailer_labelcustomer_courierhappy_returnsin_storegreen_returncarrier_dropoffretail_reworkscarrier_pickup
name
string

The name of the return method.

zone
object

Details about the zone.

rule
object

Details about the rule.

exchange
order
object or null

The order details associated with the exchange. This field will only have a value after an order has been created.

items
array[object]

The list of items included in the exchange.

tax_total

The total amount of tax applied to the exchange.

bonus_credits
array[object]

The bonus credits applied to the exchange.

bonus_credits_used_total

The total value of bonus credits used in the exchange.

exchange_total_including_tax

Total value including tax for the exchange.

instant_exchange
status

The status of the instant exchange payment. "pending" means the shopper has authorized the charge, "charged" means the merchant has successfully collected the payment, and "canceled" means the payment is no longer required and has been canceled.

Allowed values:
pendingchargedcanceledfailed
payment
object or null
receivings
array[Receiving]
id
string

ID of the receiving operation

Example:
fcd437b4532b44739f52e304f850f360
items
array[object]

The items involved in this receive operation

received_at
string<date-time>

The date-time (ISO string in UTC) when the items were received

Example:
2023-07-15T00:00:00Z
gift_return
recipient
object
shipments
array[ReturnShipment]
id
string

The unique identifier for the shipment.

tracking_number
string

The tracking number for the shipment.

Example:
ABC123456789
tracking_status
string or null

The current status of the shipment. All possible tracking statuses can be found on https://www.aftership.com/docs/tracking/enum/delivery-statuses

Example:
InTransit
slug
string

A unique identifier for the shipment. All supported slugs can be found on https://track.aftership.com/couriers/download

Example:
usps
items
array[object]

The list of items included in the shipment.

label
object or null

The shipping label associated with the shipment.

packing_slip_url
string or null

The URL for the packing slip related to the shipment.

Example:
https://cdn.example.com/x/y/z.pdf
shipping_documents_url
string or null

The URL for the shipping documents.

Example:
https://cdn.example.com/x/y/z.pdf
shipping_documents_components
array

The components of the shipping documents.

Allowed values:
labelpacking_slipconditional_shipping_document
conditional_shipping_document_urls
array[string]

The URLs for any conditional shipping documents.

source
string

The source of the shipment label.

Allowed values:
shopper_uploadmerchant_uploadmerchant_apimerchant_generate
restocks
array[object]
items
array[object]
cost_of_return
charged

This field indicates the cost of return that has already been charged. If payment or refund has not yet occurred, this value will be null, as the cost of return has not been actually charged yet.

value
Money

This field indicates the cost of return that should be charged.

refunds
array[Refund]
destination
string

The refund destination.

Allowed values:
original_paymentstore_creditrefundid
external_id
string

The identifier for this refund on the e-commerce platform.

gateway
string

The payment gateway used for processing the refund.

store_credit_reference
string or null

The identifier of the issued store credit on the platform, such as a gift card code. Available only when using refund to store credit.

total

The amount and currency of the refund.

items
array[object]

The details of the refund items.

dropoffs
array[Dropoff]
id
string

The unique identifier for the dropoff.

qr_code_url
string

The QR code URL provided by the dropoff service provider to the shopper.

dropoff_number
string

The identifier of this dropoff resource on the dropoff service provider's side (e.g., Express Code from Happy Returns).

service_provider
string

The dropoff service provider used for this operation.

Allowed values:
happy-returnsretail-reworks
created_at
string<date-time>

The creation time of the dropoff record.

status
string

The current status of the dropoff.

Allowed values:
createddroppedpartially_dropped
items
array[object]

The list of items included in the dropoff operation.

shipments
array[DropoffShipment]

The list of shipments associated with this dropoff.

created_at
string
Example:
2024-01-01T00:00:00.001Z
Example
preparing...