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

Update return items By RMA number

patch
/returns/rma/{rma_number}/items/{item_id}

Request

Path Parameters

rma_number
string
required
item_id
string
required

Body

(one of)
item_tags
array[object]
id
string

Responses

200

Body

meta
Meta

Meta data object.

code
number
required
Default:
20000
Example:
20000
type
string
required
>= 1 characters
Example:
OK
message
string
required
>= 1 characters
Example:
The request was successfully processed by AfterShip.
data
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
removed_quantity
integer

The number of items that have been removed 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.

green_return
boolean

Whether this return item is marked as a green return item. When true, no physical return is required for this item.

Default:
false

404

A 404 will be returned:

  • When the RMA does not exist (including when the RMA does not belong to the org)
  • When the item not include in RMA

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
{ "item_tags": [ { "id": "string" } ] }
Response Example
{
  "meta": {
    "code": 20000,
    "type": "OK",
    "message": "The request was successfully processed by AfterShip."
  },
  "data": {
    "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
  }
}