Skip to main content

​
Draft Returns API

This API version is unreleased and subject to change. Test it via the unstable version path: /api/unstable/draft-returns/...
The Draft Returns API lets you build a complete return-creation flow by managing draft returns through a state machine. Endpoints allow you to initialize a draft, add or remove items, set customer and address details, finalize selections, and submit the completed return.

​
Response structure

Each successful response includes:
  • draft_return — the draft return and shopper details
  • context — data needed to fill action payloads
  • _links — available actions, keyed by relation name, each with an href
  • _templates — action descriptors keyed by name, with method, title, contentType, and properties
  • client_application — how the client should identify itself on later requests
  • errors — any errors from processing
Responses use Content-Type: application/prs.hal-forms+json. Request bodies use Content-Type: application/json. Authenticate with the X-Authorization API key header.

​
State machine

  • created — add items and set customer information
  • items-finalized — choose credit type and return method
  • submitted / cancelled / expired — terminal; _templates and _links are empty