QUICKSTART
API Quick Start
Authentication
SignString
Versioning
Rate Limit
Body Envelope
Request Errors
CHANGELOG
Changelog
Migration
Migrate from 2026-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
Remove return items by Return ID
post
Remove return items by RMA number
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
Returns Page
Create Returns Page Deep Link
post
Model
Primitive
Address
Money
Envelope
Meta
Error
Resource
Return
Return item
Item tag
enum
Platforms
Webhook
Webhook Overview
Webhook Specifications
Webhook Outgoing IPs
Webhook Signature
Support
Contact Support

Resolve Return By Return ID

post
/returns/{return_id}/resolve

Through the resolve return API, you can transition a return to resolved status.

Request

Path Parameters

return_id
string
required

Body

notify_customer
boolean

Responses

200

Body

meta
Meta

Meta data object.

code
number
required
Default:
20200
Example:
20200
type
string
required
>= 1 characters
Example:
Accepted
message
string
required
>= 1 characters
Example:
The request has been accepted for processing.
data
Return
id
string
Example:
b3eedf69b7c0410d8975d4350c007705
organization
object
rma_number
string
Example:
A1B2C3D4
contact_email
string

The contact email address for the return.

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
shipping_address
Address

The shipping address for the return.

Example:
{"street_1":"1234 Elm Street","street_2":"Apt 5","city":"New York","state":{"name":"New York"},"postal_code":"10001","country_region":{"code":"USA"}}
order
object
return_items
array[ReturnItem]
return_method
ReturnMethod
exchange
instant_exchange
receivings
array[Receiving]
is_gift_return
boolean

Indicates whether this is a 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

404

When the RMA does not exist (including when the RMA does not belong to the org), a 404 will be returned.

Body

code
number

Error code in integer format.

Default:
20000
Example:
20000
type
string

Response type string for the reference.

>= 1 characters
Example:
OK
message
string

Human-readable response message.

>= 1 characters
Example:
The request was successfully processed by AfterShip.
errors
array[Error]

Error detail object. Each error object contains a "path" key and an "info" key. The "path" is the JSON path of the request object to indicate the error location. The "info" is a human-readable description of the error.

path
string
Example:
items[0].quantity
info
string
Example:
quantity must be 1 or greater

409

We will check whether the current approval status can be transitioned to done before executing the status change. If the current approval status cannot be transitioned to done, a 409 will be returned.

Body

code
number

Error code in integer format.

Default:
20000
Example:
20000
type
string

Response type string for the reference.

>= 1 characters
Example:
OK
message
string

Human-readable response message.

>= 1 characters
Example:
The request was successfully processed by AfterShip.
errors
array[Error]

Error detail object. Each error object contains a "path" key and an "info" key. The "path" is the JSON path of the request object to indicate the error location. The "info" is a human-readable description of the error.

path
string
Example:
items[0].quantity
info
string
Example:
quantity must be 1 or greater
Auth
:
Parameters
:
Body
{ "notify_customer": true }
Response Example
{
  "meta": {
    "code": 20200,
    "type": "Accepted",
    "message": "The request has been accepted for processing."
  },
  "data": {
    "id": "b3eedf69b7c0410d8975d4350c007705",
    "organization": {
      "id": "4f94e5fe178c46a9b976b7d4e646d65a"
    },
    "rma_number": "A1B2C3D4",
    "contact_email": "string",
    "filed_by": "shopper",
    "approval_status": "submitted",
    "approved_at": "string",
    "auto_approved": true,
    "rejected_at": "string",
    "reject_reason": "string",
    "auto_rejected": true,
    "resolved_at": "string",
    "auto_resolved": true,
    "refunded_at": "string",
    "auto_refunded": true,
    "auto_received": true,
    "expired_at": "string",
    "shop_now": true,
    "merchant_note": "This is an internal note",
    "return_total_including_tax": {
      "amount": "99.99",
      "currency": "USD"
    },
    "return_tax": {
      "amount": "99.99",
      "currency": "USD"
    },
    "refund_destination": "original_payment",
    "refunded_total": {
      "amount": "99.99",
      "currency": "USD"
    },
    "estimated_refund_total": {
      "amount": "99.99",
      "currency": "USD"
    },
    "checkout_total": {
      "amount": "99.99",
      "currency": "USD"
    },
    "shipping_address": {
      "street_1": "1234 Elm Street",
      "street_2": "Apt 5",
      "city": "New York",
      "state": {
        "name": "New York"
      },
      "postal_code": "10001",
      "country_region": {
        "code": "USA"
      }
    },
    "order": {
      "id": "string",
      "external_id": "4254002020558",
      "order_number": "10001",
      "order_name": "#10001",
      "customer": {
        "emails": [
          "[email protected]"
        ],
        "locale": "string"
      },
      "country_region": "USA",
      "store": {
        "platform": "shopify",
        "external_id": "cool-shoe-store"
      },
      "placed_at": "2024-09-27T10:45:30Z"
    },
    "return_items": [
      {
        "id": "10579097059534",
        "external_order_item_id": "10579097059534",
        "external_product_id": "7002111410382",
        "external_variant_id": "41681852399822",
        "sku": "t-shirt-blue-xl",
        "product_title": "T-Shirt",
        "intended_return_quantity": 2,
        "variant_title": "Blue - XL",
        "return_reason": "Wrong size",
        "return_reason_comment": "Too Small",
        "return_subreason": "Too small",
        "ordered_quantity": 3,
        "refund_quantity": 2,
        "return_quantity": 2,
        "received_quantity": 0,
        "restocked_quantity": 0,
        "removed_quantity": 0,
        "unit_display_price": {
          "amount": "99.99",
          "currency": "USD"
        },
        "unit_discounted_price_including_tax": {
          "amount": "99.99",
          "currency": "USD"
        },
        "unit_discount": {
          "amount": "99.99",
          "currency": "USD"
        },
        "unit_tax": {
          "amount": "99.99",
          "currency": "USD"
        },
        "properties": [
          {
            "name": "monogram",
            "value": "joe"
          }
        ],
        "shopper_uploaded_image_urls": [
          "https://cdn.example.com/x/y/z.jpg"
        ],
        "product_image_urls": [
          "https://cdn.example.com/x/y/z.jpg"
        ],
        "product_categories": [
          "clothing"
        ],
        "product_tags": [
          "clothing"
        ],
        "item_tags": [
          {
            "id": "da1c35a503364bf8bb851ffaa49028c4",
            "name": "Defective",
            "created_at": "2023-07-15T00:00:00Z"
          }
        ],
        "merchant_uploaded_image_urls": [
          "https://cdn.example.com/x/y/z.jpg"
        ],
        "bundled_items": [
          {
            "external_id": "string",
            "external_product_id": "string",
            "external_variant_id": "string",
            "sku": "string",
            "product_title": "string",
            "variant_title": "string",
            "unit_display_price": {
              "amount": "99.99",
              "currency": "USD"
            },
            "unit_discounted_price_including_tax": {
              "amount": "99.99",
              "currency": "USD"
            },
            "unit_discount": {
              "amount": "99.99",
              "currency": "USD"
            },
            "unit_tax": {
              "amount": "99.99",
              "currency": "USD"
            },
            "product_categories": [
              "string"
            ],
            "product_tags": [
              "string"
            ],
            "intended_return_quantity": 0,
            "return_quantity": 0,
            "received_quantity": 0,
            "ordered_quantity": 0
          }
        ],
        "exchange_variant": {
          "external_product_id": "string",
          "external_variant_id": "string",
          "sku": "string",
          "product_title": "string",
          "title": "string",
          "unit_display_price": {
            "amount": "99.99",
            "currency": "USD"
          }
        },
        "parent_item_id": "string",
        "green_return": false
      }
    ],
    "return_method": {
      "type": "retailer_label",
      "name": "string",
      "zone": {
        "name": "string"
      },
      "rule": {
        "name": "string"
      }
    },
    "exchange": {
      "order": {
        "external_id": "string",
        "order_number": "string",
        "customer": {
          "emails": [
            "string"
          ],
          "locale": "string"
        },
        "country": "string",
        "store": {
          "platform": "string",
          "external_id": "string"
        }
      },
      "items": [
        {
          "external_product_id": "string",
          "external_variant_id": "string",
          "sku": "string",
          "title": "string",
          "variant_to_replace": {
            "external_id": "string",
            "external_product_id": "string",
            "title": "string",
            "sku": "string"
          },
          "quantity": 0,
          "unit_display_price": {
            "amount": "99.99",
            "currency": "USD"
          },
          "product_title": "string",
          "variant_title": "string",
          "product_image_urls": [
            "string"
          ]
        }
      ],
      "tax_total": {
        "amount": "99.99",
        "currency": "USD"
      },
      "bonus_credits": [
        {
          "type": "extra_credit",
          "value": {
            "amount": "99.99",
            "currency": "USD"
          },
          "rate": 0,
          "used": {
            "amount": "99.99",
            "currency": "USD"
          }
        }
      ],
      "bonus_credits_used_total": {
        "amount": "99.99",
        "currency": "USD"
      },
      "exchange_total_including_tax": {
        "amount": "99.99",
        "currency": "USD"
      },
      "charge_by": "aftership"
    },
    "instant_exchange": {
      "status": "pending",
      "payment": {
        "id": "string",
        "external_id": "string",
        "total": {
          "amount": "99.99",
          "currency": "USD"
        },
        "gateway": "stripe"
      }
    },
    "receivings": [
      {
        "id": "fcd437b4532b44739f52e304f850f360",
        "items": [
          {
            "external_id": "13910507487475",
            "external_product_id": "8524159222003",
            "external_variant_id": "45258012197107",
            "sku": "snowboard-powder",
            "quantity": 3,
            "gradings": [
              {
                "grade": "b",
                "quantity": 2,
                "notes": "The items have minor scratches and some packaging damage.",
                "image_urls": [
                  "https://example.com/image1.jpg"
                ],
                "inspector": "John Doe",
                "inspected_at": "2023-10-01T10:30:00Z"
              }
            ]
          }
        ],
        "received_at": "2023-07-15T00:00:00Z"
      }
    ],
    "is_gift_return": true,
    "shipments": [
      {
        "id": "string",
        "tracking_number": "ABC123456789",
        "tracking_status": "InTransit",
        "slug": "usps",
        "items": [
          {
            "external_order_item_id": "10579097059534",
            "quantity": 2
          }
        ],
        "label": {
          "url": "https://cdn.example.com/x/y/z.pdf",
          "aftership_shipping_slug": "usps",
          "slug": "usps",
          "total_charge": {
            "amount": "99.99",
            "currency": "USD"
          },
          "qr_code_url": "string"
        },
        "packing_slip_url": "https://cdn.example.com/x/y/z.pdf",
        "shipping_documents_url": "https://cdn.example.com/x/y/z.pdf",
        "shipping_documents_components": [
          "label"
        ],
        "conditional_shipping_document_urls": [
          "https://cdn.example.com/x/y/z.pdf"
        ],
        "source": "shopper_upload",
        "created_at": "string",
        "tracking_status_updated_at": "string",
        "ship_from": {
          "street_1": "1234 Elm Street",
          "street_2": "Apt 5",
          "city": "New York",
          "state": {
            "name": "New York"
          },
          "postal_code": "10001",
          "country_region": {
            "code": "USA"
          }
        },
        "ship_to": {
          "street_1": "1234 Elm Street",
          "street_2": "Apt 5",
          "city": "New York",
          "state": {
            "name": "New York"
          },
          "postal_code": "10001",
          "country_region": {
            "code": "USA"
          }
        },
        "invoice_url": "https://cdn.example.com/x/y/invoice.pdf"
      }
    ],
    "restocks": [
      {
        "items": [
          {
            "source_order_item_id": "13892318167283",
            "quantity": 1,
            "location": {
              "source_id": "75333206259",
              "name": "My Custom Location"
            }
          }
        ]
      }
    ],
    "cost_of_return": {
      "charged": {
        "amount": "99.99",
        "currency": "USD"
      },
      "value": {
        "amount": "99.99",
        "currency": "USD"
      }
    },
    "refunds": [
      {
        "destination": "original_payment",
        "external_id": "string",
        "gateway": "string",
        "store_credit_reference": "string",
        "total": {
          "amount": "99.99",
          "currency": "USD"
        },
        "items": [
          {
            "external_order_item_id": "string",
            "external_product_id": "string",
            "external_variant_id": "string",
            "sku": "string",
            "title": "string",
            "refund_quantity": 0
          }
        ],
        "transactions": [
          {
            "external_id": "string",
            "parent_external_id": "string",
            "payment_gateway": "string",
            "refunded_amount": {
              "amount": "99.99",
              "currency": "USD"
            }
          }
        ]
      }
    ],
    "dropoffs": [
      {
        "id": "string",
        "qr_code_url": "string",
        "dropoff_number": "string",
        "service_provider": "happy-returns",
        "created_at": "2019-08-24T14:15:22Z",
        "status": "created",
        "items": [
          {
            "external_order_item_id": "string",
            "quantity": 0
          }
        ],
        "shipments": [
          {
            "id": "string",
            "external_id": "string",
            "service_provider_carrier_code": "string",
            "tracking_number": "string",
            "items": [
              {
                "external_order_item_id": "string",
                "quantity": 0,
                "return_bag_barcodes": [
                  "string"
                ]
              }
            ]
          }
        ]
      }
    ],
    "outcomes": [
      "exchange"
    ],
    "created_at": "2024-01-01T00:00:00.001Z",
    "shipping_status": "no_label",
    "exceptions": [
      "exchange_failed"
    ]
  }
}