Submit a return request

post

https://api.protectplus.io/returns

Submit a return request on a customer's behalf for review. The request
then goes through merchant approval. This endpoint does not create
an active or approved return, and it does not create a Shopify return,
buy shipping labels, or capture payments.

Each return_line_items[].line_id is validated against the
order: an id that is not on the order, or a quantity that exceeds the
line's remaining returnable_quantity, is rejected with 400. Fetch the
current per-line returnable quantities (and the line_id to send) from
GET /orders/{order_number}/returnable-items.

Accepts an Idempotency-Key header (UUID). Duplicate requests with the same
key and body within 24 hours return the cached response. Same key with a
different body returns 422.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Return request body. All wire fields are snake_case and validated server-side against the SSOT CreateReturnRequest schema (the same schema the runtime AJV validator compiles), so the documented contract and the validator cannot drift. additionalProperties is permitted; unsupported OMS fields (exchange_line_items, exchange_to_address, rate_id, payment_intent_id, warranty_id) are rejected with 422.

POST /returns body. Submit a return request for an OMS (Custom) order, proxied to the returns & exchange service. OMS returns are refund-only and single-flow; exchanges, warranty, and gateway-priced shipping are not supported.

customer_reason

object

order_id

string

required

length ≥ 1

Source-platform order identifier the return is filed against.

return_from_address

object

required

Address the customer returns the goods from. A free-form address object — the returns service accepts platform-shaped address fields, so this is intentionally permissive (no required sub-fields enforced here). The properties below are the commonly-supplied snake_case keys.

return_label

object

PUT /orders/{order_number}/return-label body — a SINGLE object, not an array. The merchant-provided prepaid return label for an OMS (Custom) order. Get Plus never generates or pays for this label; it is surfaced to the customer return flow. You must supply AT LEAST ONE identifier: barcode_data (USPS full-label render), tracking_number, label_url, qr_code_url, or included_in_package — the numbered variants shown below are those mutually-compatible options, NOT repeated objects. See docs/guides/returns-integration.md.

return_line_items

array of objects

required

length between 1 and 100

Lines being returned (at least one).

return_line_items*

return_method

string

enum

required

How the customer is compensated. OMS (Custom) orders offer refund-type resolutions only — there are no exchanges.

Allowed:

return_reason_note

string

length ≤ 1024

Optional free-text note for the return as a whole.

shipment_return_method

string

enum

required

How the item is returned. SELF_SHIP means the customer ships it back with the label the merchant supplies (return_label here, or PUT /orders/{order_number}/return-label); Get Plus does not buy a label for OMS orders. IN_STORE is a physical drop-off (no label).

Allowed:

Headers

Idempotency-Key

uuid

UUID idempotency key. Re-sending the same key + body within 24 h returns the cached response.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201Return request created

400Return rejected by the returns service — e.g. a line_id that is not on the order, or a quantity that exceeds the line's remaining returnable_quantity.

401Unauthorized

404Order not found

422Validation error

429Rate limit exceeded