AfterShip Return items API
The Return items API from AfterShip — 2 operation(s) for return items.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/aftership-return-items-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.2.0
info:
title: Overview Return items API
version: 2026-07
summary: API Overview
description: '> OAS Schema can be downloaded [here](https://stoplight.io/api/v1/projects/automizely/docs-api-returnscenter-com-public/nodes/reference/api.json?branch=production/2026-07&deref=optimizedBundle)'
contact:
name: AfterShip Support
url: https://www.aftership.com/contact-us
email: support@aftership.com
termsOfService: https://www.aftership.com/legal/terms-of-service
servers:
- url: https://api.aftership.com/returns/2026-07
description: API Endpoint
security:
- as-api-key: []
tags:
- name: Return items
paths:
/returns/{return_id}/items/{item_id}:
parameters:
- schema:
type: string
name: return_id
in: path
required: true
- schema:
type: string
name: item_id
in: path
required: true
patch:
summary: Update return items by Return ID
responses:
'200':
$ref: '#/components/responses/UpdateReturnItems'
'404':
$ref: '#/components/responses/UpdateReturnItemsError404'
operationId: patch-returns-return_id-items-item_id
x-stoplight:
id: w1h9tozhfx3wi
requestBody:
$ref: '#/components/requestBodies/UpdateReturnItems'
tags:
- Return items
/returns/rma/{rma_number}/items/{item_id}:
parameters:
- schema:
type: string
name: rma_number
in: path
required: true
- schema:
type: string
name: item_id
in: path
required: true
patch:
summary: Update return items By RMA number
responses:
'200':
$ref: '#/components/responses/UpdateReturnItems'
'404':
$ref: '#/components/responses/UpdateReturnItemsError404'
operationId: patch-returns-rma-rma_number-items-item_id
x-stoplight:
id: w1h9tozhfx3w3
requestBody:
$ref: '#/components/requestBodies/UpdateReturnItems'
tags:
- Return items
components:
schemas:
Meta:
title: Meta
x-stoplight:
id: dxay0rufhj07b
type: object
examples:
- code: 20000
type: OK
message: The request was successfully processed by AfterShip.
properties:
code:
type: number
default: 20000
example: 20000
description: Error code in integer format.
type:
type: string
minLength: 1
example: OK
description: 'Response type string for the reference. '
message:
type: string
minLength: 1
example: The request was successfully processed by AfterShip.
description: Human-readable response message.
errors:
type: array
items:
$ref: '#/components/schemas/Error'
Item_tag:
x-stoplight:
id: q94m5j9owjozk
title: ItemTag
type: object
properties:
id:
type: string
description: The unique identifier for the item tag.
example: da1c35a503364bf8bb851ffaa49028c4
name:
type: string
description: The name of the item tag.
example: Defective
created_at:
type: string
x-stoplight:
id: nuzjnjy1v00m2
description: The create time of the item-tag.
example: '2023-07-15T00:00:00Z'
Meta_20000:
description: Meta data object.
x-stoplight:
id: 35d0c02d30f62
type: object
x-examples: {}
examples: []
title: Meta
x-tags:
- Envelope
required:
- code
- type
- message
properties:
code:
type: number
default: 20000
example: 20000
x-stoplight:
id: qxyxke3nejh32
type:
type: string
minLength: 1
x-stoplight:
id: 9a7ftn28bils7
example: OK
message:
type: string
minLength: 1
x-stoplight:
id: pf8hdo8p7yqdz
example: The request was successfully processed by AfterShip.
Money:
type: object
title: Money
properties:
amount:
type: string
example: '99.99'
description: The amount represented with two decimal places.
currency:
type: string
example: USD
description: The currency code, using ISO 4217 standards.
Error:
type: object
examples:
- info: quantity must be 1 or greater
path: items[0].quantity
properties:
path:
type: string
x-stoplight:
id: d9hc9ncjy3jkh
example: items[0].quantity
info:
type: string
x-stoplight:
id: kk25irujeobgd
example: quantity must be 1 or greater
description: 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.
title: Error
Return_item:
x-stoplight:
id: 9kxjirjxt007p
type: object
title: ReturnItem
x-internal: false
properties:
id:
type: string
example: '10579097059534'
description: The ID of the item.
x-stoplight:
id: 8qgyrtsvdbqj1
external_order_item_id:
type: string
example: '10579097059534'
description: The ID of the item on the e-commerce platform.
x-stoplight:
id: ermjek6xti21b
external_product_id:
type: string
example: '7002111410382'
description: The ID of the product on the e-commerce platform.
x-stoplight:
id: ht7ov6l0rzg7l
external_variant_id:
type: string
example: '41681852399822'
description: The ID of the variant on the e-commerce platform.
x-stoplight:
id: v4j06695712jw
sku:
type: string
example: t-shirt-blue-xl
description: The SKU of the item.
x-stoplight:
id: 4h2vj0wf1fc9o
product_title:
type: string
example: T-Shirt
description: The title of the product.
x-stoplight:
id: 8i96q9ejn037n
intended_return_quantity:
type: integer
example: 2
description: The number of items that the customer plans or expects to return.
x-stoplight:
id: cf2xpcveyjhie
variant_title:
type:
- string
- 'null'
example: Blue - XL
description: The title of the variant.
x-stoplight:
id: rle3p0bkghuzy
return_reason:
type: string
example: Wrong size
description: The return reason provided by the customer.
x-stoplight:
id: 7osq3ur1uzwcx
return_reason_comment:
type: string
example: Too Small
description: Additional information provided by the customer regarding the reason for the return.
x-stoplight:
id: vrmncvwdkjfm5
return_subreason:
type: string
example: Too small
description: If the return reason supports sub-reasons, this is the sub-reason provided by the customer.
x-stoplight:
id: aj4upgbmsl0ah
ordered_quantity:
type: integer
example: 3
description: The purchase quantity of the item in the original order.
x-stoplight:
id: aonj70wgv6cpd
refund_quantity:
type: integer
example: 2
description: The number of items that need to be refunded.
x-stoplight:
id: mohkqco5hocj4
return_quantity:
type: integer
example: 2
description: The number of items that need to be returned.
x-stoplight:
id: wq2q2ooibmqxr
received_quantity:
type: integer
example: 0
description: The number of items that have been received by the merchant.
x-stoplight:
id: ya7la00p35awf
restocked_quantity:
type: integer
example: 0
description: The number of items that have been restocked by the merchant.
x-stoplight:
id: cxr5gp7x2d5a0
removed_quantity:
type: integer
example: 0
description: The number of items that have been removed by the merchant.
x-stoplight:
id: gchhc1eiicphl
unit_display_price:
description: The display price of each item.
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: cqxqoix5eypsx
- x-stoplight:
id: tlqy24brncw68
type:
- 'null'
x-stoplight:
id: 0z313s55xkp1z
unit_discounted_price_including_tax:
description: The tax-inclusive discounted price for each item, representing the actual amount paid by the buyer.
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: m8fc8vf2krfpx
- x-stoplight:
id: r92b8kt4t6zyx
type:
- 'null'
x-stoplight:
id: i9yyfzcrte8d8
unit_discount:
description: The discount allocated to each item.
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: xjvbecngb7vis
- x-stoplight:
id: kj4r4633yoevz
type:
- 'null'
x-stoplight:
id: 1dn8ajtxryrds
unit_tax:
description: The tax allocated to each item.
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: u1nk16ip7bpxj
- x-stoplight:
id: y7q8d6toejurz
type:
- 'null'
x-stoplight:
id: ipwjndigalglo
properties:
type: array
description: Custom properties filled in by the customer when purchasing the product.
x-stoplight:
id: sfi42vf3k54ft
items:
type: object
x-stoplight:
id: 3pda0g4yslqqu
properties:
name:
type: string
example: monogram
description: Custom property name.
x-stoplight:
id: 17oj3pip2m153
value:
type: string
example: joe
description: Custom property value.
x-stoplight:
id: 0uxxza5377nup
shopper_uploaded_image_urls:
type: array
description: The images provided by the customer when submitting a return.
x-stoplight:
id: 3x59w4vwjjwd0
items:
type: string
example: https://cdn.example.com/x/y/z.jpg
x-stoplight:
id: hg16an4lr5pwl
product_image_urls:
type: array
description: The images of the product.
x-stoplight:
id: s7nrg3m1msvqs
items:
type: string
example: https://cdn.example.com/x/y/z.jpg
x-stoplight:
id: k5jy5l292154b
product_categories:
type: array
description: The product categories configured on the e-commerce platform.
x-stoplight:
id: o7c3fdivpkqcy
items:
type: string
example: clothing
x-stoplight:
id: cw30yb9nr4a92
product_tags:
type: array
description: The product tags configured on the e-commerce platform.
x-stoplight:
id: vyn5guy5vpxf9
items:
type: string
example: clothing
x-stoplight:
id: 3tge4x61tizib
item_tags:
type: array
description: The tags applied by the merchant to this return item.
x-stoplight:
id: geup1h97kn00w
items:
$ref: '#/components/schemas/Item_tag'
x-stoplight:
id: kjx3797vzy7x1
merchant_uploaded_image_urls:
type: array
description: The images uploaded by the merchant for this return item.
x-stoplight:
id: 85g4si2ngk5eh
items:
type: string
example: https://cdn.example.com/x/y/z.jpg
x-stoplight:
id: dzl08raonlnp6
bundled_items:
type: array
description: When the item being returned is a whole bundle, this array will represent its child items.
x-stoplight:
id: vyh66x2vtumab
items:
type: object
x-stoplight:
id: tftfpwsxf8cwo
properties:
external_id:
type: string
description: The ID of the item on the e-commerce platform.
x-stoplight:
id: s5lpf09r07kra
external_product_id:
type: string
description: The ID of the product on the e-commerce platform.
x-stoplight:
id: 1pldjafyiept0
external_variant_id:
type: string
description: The ID of the variant on the e-commerce platform.
x-stoplight:
id: 6gjn8i1iutnm5
sku:
type: string
description: The SKU of the item.
x-stoplight:
id: ukm2h7b8re6hv
product_title:
type: string
description: The title of the product.
x-stoplight:
id: 9f775ewsdyes4
variant_title:
type:
- string
- 'null'
description: The title of the variant.
x-stoplight:
id: i9o1ujhvhfj2b
unit_display_price:
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: 1mjeby2x7r278
- x-stoplight:
id: afgkpofk42xd8
type:
- 'null'
description: The display price of each item.
x-stoplight:
id: x1kob53ndccyh
unit_discounted_price_including_tax:
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: lvqoe62n04z5c
- x-stoplight:
id: po4kl95mxnkg8
type:
- 'null'
description: The tax-inclusive discounted price for each item, representing the actual amount paid by the buyer.
x-stoplight:
id: jnrr8mjbo8ywo
unit_discount:
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: ne6fvupxraec2
- x-stoplight:
id: ej38q887538d2
type:
- 'null'
description: The discount allocated to each item.
x-stoplight:
id: 14rf7r5k2k0dn
unit_tax:
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: uu7wn74wiemqm
- x-stoplight:
id: 9xg7vwmw3f46l
type:
- 'null'
description: The tax allocated to each item.
x-stoplight:
id: k89kygp8v9ibc
product_categories:
type: array
description: The product categories configured on the e-commerce platform.
x-stoplight:
id: qgfztkadw0npo
items:
type: string
x-stoplight:
id: p7h7svklmdjpn
product_tags:
type: array
description: The product tags configured on the e-commerce platform.
x-stoplight:
id: sspcgczz7g7sk
items:
type: string
x-stoplight:
id: wnr5mql4c8lk8
intended_return_quantity:
type: number
description: The number of items that the customer plans or expects to return.
x-stoplight:
id: i8gzk2brj4yyh
return_quantity:
type: number
description: The number of items that need to be returned.
x-stoplight:
id: v1ggsc7kl8u1e
received_quantity:
type: number
description: The number of items that have been received by the merchant.
x-stoplight:
id: hce5gccf8eswn
ordered_quantity:
type: number
description: The purchase quantity of the item in the original order.
x-stoplight:
id: sw0ltz2my5f5t
exchange_variant:
type:
- object
- 'null'
description: Exchange variant associated with this return item. Available only when using replacement.
x-stoplight:
id: tjq9ggrfnis07
properties:
external_product_id:
type: string
description: The ID of the product on the e-commerce platform.
x-stoplight:
id: 5jrfod76kj3pw
external_variant_id:
type: string
description: The ID of the variant on the e-commerce platform.
x-stoplight:
id: d4hg34nim04l2
sku:
type: string
description: The SKU of the item.
x-stoplight:
id: oxrm5bp6d0bxw
product_title:
type: string
description: The title of the product.
x-stoplight:
id: 8c1zcwsletcgd
title:
type: string
description: The title of the variant.
x-stoplight:
id: akp2uyxtybosq
unit_display_price:
oneOf:
- type: object
$ref: '#/components/schemas/Money'
x-stoplight:
id: 4jjcpmvgmkb1z
- x-stoplight:
id: v7zqzrln1uztv
type:
- 'null'
description: The display price of each item.
x-stoplight:
id: l8miv9gxtlgeo
parent_item_id:
type:
- string
- 'null'
description: 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.
x-stoplight:
id: xx6fbtjg6rc2h
green_return:
type: boolean
x-stoplight:
id: swlaoo3bwpteo
default: false
description: Whether this return item is marked as a green return item. When true, no physical return is required for this item.
responses:
UpdateReturnItems:
description: ''
content:
application/json:
schema:
type: object
properties:
meta:
$ref: '#/components/schemas/Meta_20000'
x-stoplight:
id: gb6g16v7bzjyo
data:
$ref: '#/components/schemas/Return_item'
x-stoplight:
id: 9kxjirjxt007p
UpdateReturnItemsError404:
description: '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'
content:
application/json:
schema:
$ref: '#/components/schemas/Meta'
examples:
Return not found:
value:
meta:
code: 40406
type: NotFound
message: Return not found
data: null
Item not found:
value:
meta:
code: 40425
type: NotFound
message: Return item not found
data: null
requestBodies:
UpdateReturnItems:
content:
application/json:
schema:
oneOf:
- title: TagItem
properties:
item_tags:
type: array
x-stoplight:
id: ddhfn711zdw8y
items:
x-stoplight:
id: ytbgyofr5v9qf
type: object
properties:
id:
type: string
x-stoplight:
id: hhj1egia6vj8u
- title: UpdateImages
x-stoplight:
id: ko17fcdhsmw6l
properties:
merchant_uploaded_image_urls:
type: array
x-stoplight:
id: epb556iayxnmv
items:
x-stoplight:
id: i5s32dd9u9yhj
type: string
type: object
securitySchemes:
as-api-key:
name: as-api-key
type: apiKey
in: header