This API is used to create a Return. Currently, it only supports the "Refund" resolution and does not support "Replace with the same item" or "Exchange for anything."

Request

Security: API Key

Body

order

object

required

external_id

string

required

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

Example:

4254002020558

store

object

required

return_items

array[object]

required

external_order_item_id

string

required

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

Example:

10579097059534

intended_return_quantity

integer

required

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

>= 1

return_reason

string

required

The return reason provided by the customer.

Example:

Wrong size

return_subreason

string

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

Example:

Too small

return_reason_comment

string

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

Example:

To Small

shopper_uploaded_image_urls

array[string]

The images provided by the customer when submitting a return.

resolution

string

required

The resolution for processing this item, currently only supports refund.

Allowed value:

refund

return_method

object

type

string

required

Allowed values:

retailer_labelcustomer_courierhappy_returnsin_storegreen_returnretail_reworkscarrier_pickup

refund_destination

string

required

The destination for the refund

Allowed values:

original_paymentstore_credit

Responses

422

A 422 will be returned when:

When the requested data contains fields that do not comply with the validation rules. We will provide the path of the invalid fields and errors in the meta.errors.
When the submitted return violates the merchant's configured return policy.

Body

code

number

Error code in integer format.

Default:

20000

Example:

20000

type

string

Response type string for the reference.

>= 1 characters

Example:

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

429

A 429 will be returned when:

When another return request for the same order is already in progress during the call.

Body

code

number

Error code in integer format.

Default:

20000

Example:

20000

type

string

Response type string for the reference.

>= 1 characters

Example:

message

string

Human-readable response message.

>= 1 characters

Example:

The request was successfully processed by AfterShip.

errors

array[Error]

path

string

Example:

items[0].quantity

info

string

Example:

quantity must be 1 or greater

Auth

Body

{
  "order": {
    "external_id": "4254002020558",
    "store": {
      "platform": "shopify",
      "external_id": "cool-shoe-store"
    }
  },
  "return_items": [
    {
      "external_order_item_id": "10579097059534",
      "intended_return_quantity": 1,
      "return_reason": "Wrong size",
      "return_subreason": "Too small",
      "return_reason_comment": "To Small",
      "shopper_uploaded_image_urls": [
        "https://example.com/1.jpeg"
      ],
      "resolution": "refund"
    }
  ],
  "return_method": {
    "type": "retailer_label"
  },
  "refund_destination": "original_payment"
}

Response Example

{
  "meta": {
    "code": 20100,
    "type": "Created",
    "message": "The request has been fulfilled and a new resource has been created."
  },
  "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"
    ]
  }
}