Skip to main content
POST
Resolve a mis-shipment correction's return

Authorizations

Authorization
string
header
required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity
via Settings > Developers > API Keys.

Headers

Idempotency-Key
string

Client-generated unique key for idempotent POST/PATCH/DELETE operations. Alias for the Idempotency parameter. Max 255 chars. On retry with the same key, the original response is returned without re-executing the operation. Keys expire after 24 hours. A second request with the same key sent while the first is still running waits for it and returns its answer; if the first is still running after 20 seconds the second answers 409 idempotency_key_in_use (retryable, nothing done). An answer carrying retryable: true is not cached. Reusing a key with a different request body answers 409 idempotency_key_collision (nothing done; send the new request with a fresh key). The replay, the wait and these two 409 codes come from the idempotency layer, so they apply to the operations that run it, each of which can answer the two codes whether or not its own 409 response lists them. The handlers of these operations take the header but do not run the layer, so on them the key neither replays nor answers either code: createPaymentPlan, chargePaymentPlanInstallment, setProductLocations, updateOrder, emailOrder, updateOrderItem, confirmPickup, markOrderNoShow, applyExistingPaymentToInvoices, updatePackage, movePackageItem, changePackageBox, changePackageCarrier, voidPackageLabel, printPackageLabel, emailPackage, setProNumberV1, setPackageProNumber, sendPurchaseOrderToVendorV1, notifyRevisionPurchaseOrderV1, addMaintenanceLog, generateBOLV1, createReportJobV1 and customerAcknowledgeRevision; recordVendorPrepaymentV1 and recordCustomerDepositV1 hand the key to their own write instead.

Maximum string length: 255

Path Parameters

id
string<uuid>
required

Body

application/json
intent
enum<string>
required

no_replacement: close the reopened units short on the order (nothing is refunded). replacement_later: keep the return open; books nothing. not_coming_back: write the held wrong item off.

Available options:
no_replacement,
replacement_later,
not_coming_back
note
string

Words for the return's internal note (and, for no_replacement, the close-short's reason; for not_coming_back, the write-off's note). Trimmed; at most 500 characters.

Maximum string length: 500
reason_code
enum<string>
default:inventory_short

no_replacement only: why the line closes short. inventory_short: the correct item is not available; customer_request: the customer declined the replacement. Any other value is read as inventory_short.

Available options:
inventory_short,
customer_request

Response

The choice was made. The answer says what was done, read after the write: for no_replacement the lines closed, the order's new totals, what it now holds beyond them (overpaid, for its Issue Refund) and what came back off the receivable (taken_back, with its sentences in books); for replacement_later the note (books is nothing); for not_coming_back the units written off, their value and the journal entries.

data
object
required

One of three shapes, told apart by intent (the choice made).