Open a return against an order
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Path Parameters
Body
The order is the path and cannot be repeated in the body, so the two can never disagree. The return opens as 'requested': a merchant still approves it, because a key that could open an already-approved return would be the approval gate defeated by the create route. The refund figure is COMPUTED from the returned lines and then scaled by the order's own discounts, gift cards and credit, so it is never sent: this grant chooses whether to refund and never how much. location_id is refused by name. Where returned stock lands is write_inventory's authority, so a return opened here carries no restock destination and receiving it records the receipt without moving stock, exactly as every shopper-raised return does today. A note is refused too: the column it would land in is shared with merchant prose about the shopper, and the read publishes it only for text the shopper wrote, so anything sent here could never be read back.
The lines coming back, in the order they are stored and served in. A line may appear twice; the cumulative quantity is capped at what is left to return on it, counting earlier returns.
1Response
Created
