> ## Documentation Index > Fetch the complete documentation index at: https://docs.loopreturns.com/llms.txt > Use this file to discover all available pages before exploring further. # Cancel Draft Return > Cancel a draft return. Cancelled draft returns can't be reopened. ## OpenAPI ````yaml draft-returns-hal-forms post /draft-returns/{draft_return_id}/cancel openapi: 3.1.0 info: title: Draft Returns API version: v1 description: > # Overview 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. This document describes the API as of version `2026-10`. Use `/api/2026-10/draft-returns/...` for production or `/api/unstable/draft-returns/...` to test upcoming changes. ## Response architecture Successful responses include `draft_return`, `context`, `errors`, plus hypermedia controls. ### `_links` An object keyed by relation name. Each value includes `href` and optional metadata: ```json { "_links": { "self": { "href": "https://api.loopreturns.com/api/2026-10/draft-returns/123" }, "add-returning-item": { "href": "https://api.loopreturns.com/api/2026-10/draft-returns/123/returning-items" }, "finalize-items": { "href": "https://api.loopreturns.com/api/2026-10/draft-returns/123/finalize-items" } } } ``` ### `_templates` Each available action is described by a template in the `_templates` object: ```json { "_templates": { "add-returning-item": { "method": "POST", "title": "Add a line item to the return", "contentType": "application/json", "properties": [ { "name": "order_line_item_id", "type": "number", "required": true, "prompt": "ID of the line item to return" } ] }, "finalize-items": { "method": "POST", "title": "Lock in item selections and proceed", "contentType": "application/json", "properties": [] } } } ``` Each template may include: - `method`: The HTTP method (`POST`, `DELETE`, etc.) - `title`: Human-readable description of the action - `contentType`: The request content type (typically `application/json`) - `properties`: Array of field descriptors with `name`, `type`, `required`, `prompt`, and optionally `options` (for enum-like fields) - `required`: `true` when the action must be completed before the draft return can progress, for example while a label format still has to be picked. This flag belongs to the template. It is separate from `required` on each entry in `properties`, which only says whether that field must be sent in the request body - `systemMessage`: Only on a yes/no `add-returning-item-user-input` template, when the merchant turned on a "Response if yes" message. See User input below Whether an action's template is present, and its `required` flag, describe only that one action, not the draft return as a whole. The only reliable signal that the draft return is ready to submit is the presence of the `submit-draft-return` template. ### `client_application` Responses include a `client_application` object describing how the client should identify itself on subsequent requests. ### Content type | Header | Value | |---|---| | `Accept` (request) | `application/prs.hal-forms+json` | | `Content-Type` (response) | `application/prs.hal-forms+json` | | `Content-Type` (request body) | `application/json` | Requests to version `2026-10` or later always return HAL-Forms format regardless of the `Accept` header, on every endpoint including `GET /draft-returns` (List). On earlier versions such as `2026-07`, send `Accept: application/prs.hal-forms+json` to get HAL-Forms; without that header, those versions respond with `application/json` and send merchant questions and messages as plain text. On those earlier versions, List is the exception: it requires the HAL-FORMS `Accept` header and returns `422` `unsupported-feature` when the header is missing or is `application/json`. ### Shopper token Shopper-portal draft responses include `shopper_token`. Send that value as `X-Loop-Shopper-Token` on later shopper-portal requests that include a draft return id. Merchant public API responses omit this field and do not require the header. A missing, empty, or non-matching token on those draft-id requests returns `404`. Create, initialize, and list do not require the header. ## State Machine ``` created → finalize-items → items-finalized → submit → submitted ↓ ↓ ↓← ← unfinalize-items ← ← ← ← ↓ ↓ ↓ └→ cancel → cancelled expired ``` ### States - **created**: Initial state where items are added and customer information is set - **items-finalized**: Items are locked in; credit type and return method can be selected - **submitted**: Terminal state — draft has been converted to an actual return - **cancelled**: Terminal state — draft was explicitly cancelled - **expired**: Terminal state — draft timed out due to inactivity ### Available Templates by State #### Created State `_templates` may include: - `add-returning-item`: Add an item from the order to the return - `remove-returning-item`: Remove an item from the return - `set-returning-item-return-reason`: Set why an item is being returned - `set-returning-item-return-type`: Set the return type for an item. Send only a value from that item's template `options` - `add-returning-item-exchange-item`: Add an exchange product for a returning item - `add-returning-item-user-input`: Provide additional information requested by merchant - `remove-cart-item`: Remove an exchange or shop-now item - `set-customer`: Set customer email and name - `set-address`: Set return shipping address - `finalize-items`: Lock in item selections and proceed to return method selection - `cancel-draft-return`: Cancel this draft return #### Items-Finalized State `_templates` may include: - `set-credit-type`: Choose how to receive the refund - `set-processing-type`: Choose `regular` or `instant` processing. See Processing type below - `select-return-method`: Select the shipping method for the return - `add-payment-intent`: Attach a payment intent when the draft return requires a payment. Not offered when the shop has no usable Stripe connection. - `submit-draft-return`: Submit the draft and convert it to an actual return - `unfinalize-items`: Go back to add/remove items - `cancel-draft-return`: Cancel this draft return #### Terminal States When a draft return reaches a terminal state (`submitted`, `cancelled`, `expired`), `_templates` and `_links` will be empty objects. ## User input Each unanswered merchant question on a returning item has its own `add-returning-item-user-input` template. Its `title` is the question as HTML, because merchants can format questions. After the shopper answers, the question is in `returning_items[].user_inputs[]` with the same HTML in `prompt`. Sanitize this HTML before you show it. A yes/no template can include `systemMessage`, the merchant's "Response if yes" message. It is only present when the merchant turned that response on. Show it when the shopper answers `Yes`. If the merchant's rule rejects the item on `Yes`, the item is removed from the draft return and the next response does not include the message. Keep it from the template before you submit the answer, show it, then return the shopper to item selection. ```json { "_templates": { "add-returning-item-user-input:1:10": { "method": "POST", "title": "

Have the seals been broken?

", "systemMessage": "

Used cartridges cannot be returned.

" } } } ``` ## Processing type `processing_type` is `regular` or `instant`. Every draft return starts as `regular`. In the `items-finalized` state, `_embedded.processing_type_options` shows whether each processing type is available, and the amounts for Instant. To change the processing type, use the `set-processing-type` template and send only a value from its `options`. When the draft has an exchange item, Instant runs as Instant Exchange. It stays available even when the credit type is `refund`. ### Instant reset While the draft is in `items-finalized`, Loop checks again on every request (including `GET` and submit) whether Instant is still available. If it is not, Loop: - sets `processing_type` to `regular` - removes the payment intent, so `payment_intent` is `null` Before you submit, read `processing_type` and `payment_intent` in the latest response. If you still want Instant and it is available again, set it again and attach a new payment intent. `unfinalize-items` also sets `processing_type` back to `regular`. ## Payment A draft return can require a payment, for example when the shopper owes money after exchanging into a pricier item, or when `processing_type` is `instant`. Loop collects it through the shop's Stripe connection: - If the shop has a usable Stripe connection, the `add-payment-intent` template is offered and marked required. Call it before you submit. - If the shop has no usable Stripe connection, Loop cannot collect the payment. The `add-payment-intent` template and link are not offered, and `requires_uncollectible_payment` is `true`. The draft return cannot be submitted in this state. To continue, change the draft so no payment is needed, for example by changing items or the return method. If Instant stops being available, Loop resets `processing_type` to `regular` and removes the payment intent, so `payment_intent` comes back `null`. Check `processing_type` and `payment_intent` before you submit. If a payment is still needed, `add-payment-intent` is offered again. servers: - url: https://api.loopreturns.com/api/2026-10 description: 2026-10 (Stable) - url: https://api.loopreturns.com/api/unstable description: Unstable (Preview) security: [] paths: /draft-returns/{draft_return_id}/cancel: post: summary: Cancel Draft Return description: | Cancel a draft return. Cancelled draft returns can't be reopened. operationId: cancelDraftReturnHalForms parameters: - $ref: '#/components/parameters/DraftReturnId' - $ref: '#/components/parameters/ShopId' - $ref: '#/components/parameters/AcceptHalForms' - $ref: '#/components/parameters/LoopLocale' - $ref: '#/components/parameters/ShopperToken' responses: '200': $ref: '#/components/responses/HalFormsDraftReturnResponse' '401': $ref: '#/components/responses/UnauthorizedError' '404': $ref: '#/components/responses/ShopperDraftReturnNotFound' '422': $ref: '#/components/responses/ValidationError' security: - api_key: [] components: parameters: DraftReturnId: name: draft_return_id in: path description: The unique identifier of the draft return. required: true schema: type: integer ShopId: name: X-Shop-Id in: header description: > The unique identifier of the shop associated with the draft return. This header is not required, as the merchant's shop is identified by the API key present in the request. schema: type: integer AcceptHalForms: name: Accept in: header required: false description: > Optional. Responses use `Content-Type: application/prs.hal-forms+json`. Ignored on `2026-10` and later. On earlier versions, send it to receive HAL-Forms, and it is required for `GET /draft-returns` (List). schema: type: string enum: - application/prs.hal-forms+json LoopLocale: name: X-Loop-Locale in: header required: false description: > The shopper's locale: a two-letter language code with an optional two-letter region, for example `fr` or `fr-CA`. When the value is valid and product translations are enabled for the shop, the response includes translated product text in the operation's translated fields. Otherwise those fields are not populated. schema: type: string example: fr-CA ShopperToken: name: X-Loop-Shopper-Token in: header required: false description: > Shopper-portal only. The `shopper_token` from a shopper-portal draft response. Required on shopper-portal requests that include a draft return id. A missing, empty, or non-matching value returns `404`. Merchant public API requests ignore this header. schema: type: string responses: HalFormsDraftReturnResponse: description: > Successful response with draft return data. The response uses `Content-Type: application/prs.hal-forms+json` and includes hypermedia controls in `_links` and `_templates` instead of the standard `links` array. content: application/prs.hal-forms+json: schema: type: object properties: _links: $ref: '#/components/schemas/HalFormsLinks' _templates: $ref: '#/components/schemas/HalFormsTemplates' client_application: type: object description: > Client-application header specification. Describes how the client should identify itself in subsequent requests. shopper_token: type: string description: > Shopper-portal only. Present on shopper-portal draft responses. Send this value as `X-Loop-Shopper-Token` on later shopper-portal requests that include a draft return id. Merchant public API responses omit this field. draft_return: $ref: '#/components/schemas/DraftReturn' context: $ref: '#/components/schemas/DraftReturnContext' errors: type: array description: > An array of error codes. In the event of a partial failure, the API will return all possible data as well as any error codes that were thrown. See [Error codes](/api-reference/error-codes#draft-returns-specific-errors) for a full list of possible errors. items: $ref: '#/components/schemas/DraftReturnError' UnauthorizedError: description: API key is missing or invalid. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - unauthorized message: type: string example: Unauthorized. ShopperDraftReturnNotFound: description: | Not found. On shopper-portal draft-id requests, also returned when `X-Loop-Shopper-Token` is missing, empty, or does not match the draft. ValidationError: description: Validation error occurred. content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: string enum: - validation-failed message: type: string example: Validation failed. schemas: HalFormsLinks: type: object description: > HAL `_links` object. Always includes `self`. Other keys are relation names corresponding to available actions for the current draft return state. properties: self: $ref: '#/components/schemas/HalLink' additionalProperties: $ref: '#/components/schemas/HalLink' HalFormsTemplates: type: object description: > `_templates` object. Each key is a template/action name matching a relation in `_links`. Templates describe the method, fields, and constraints for the action. additionalProperties: $ref: '#/components/schemas/HalFormsTemplate' DraftReturn: type: object description: The draft return object. properties: id: type: integer description: The unique identifier of the draft return. example: 12345 return_id: type: - integer - 'null' description: >- The unique identifier of the return, if the draft return has been submitted. example: 67890 state: type: string description: The current state of the draft return. enum: - created - items-finalized - submitted - cancelled - expired currency: type: string description: The three-character ISO 4217 currency code. examples: - USD - EUR language: type: string description: The language code for the draft return. example: en credit_type: type: - string - 'null' description: The type of credit for the return. enum: - refund - gift - exchange - null example: null processing_type: type: string description: > How the return should be processed. Every draft return starts as `regular`. Change it with the `set-processing-type` template. `_embedded.processing_type_options` shows which values are available. While the draft is in `items-finalized`, Loop checks on every request whether Instant is still available. If it is not, Loop sets `processing_type` to `regular` and removes the payment intent, so `payment_intent` is `null`. Check `processing_type` and `payment_intent` again before you submit. enum: - regular - instant example: regular customer: type: object description: The customer information associated with the draft return. properties: email: type: string format: email description: The email address of the customer. example: someone@test.com shipping_address: type: object description: The shipping address for the return. properties: name: type: string example: Jane Doe company: type: - string - 'null' example: null address1: type: string example: 123 Main St address2: type: - string - 'null' example: Apt 4 city: type: string example: Chicago state: type: string example: Illinois zip: type: string example: '60622' country: type: string example: United States country_code: type: string example: US phone: type: - string - 'null' example: 555-555-5555 returning_items: type: array description: The items being returned. items: type: object properties: id: type: integer description: >- The unique identifier of this returning item within the draft return. example: 1 order_line_item_id: type: integer description: >- The unique identifier created by Loop of the order line item being returned. example: 12346 return_type: type: - string - 'null' enum: - credit - exchange - null example: credit resolution: type: - string - 'null' enum: - return - keep - donate - reject - exchange - null example: return return_reason: type: - object - 'null' properties: name: type: string example: Item didn't fit comment: type: - string - 'null' example: null user_inputs: type: array items: type: object properties: id: type: integer example: 1 type: type: string example: yes-no prompt: type: string description: The merchant's question as HTML. example:

Is the item still in its original packaging?

value: type: - string - boolean - 'null' example: true image_uploads: type: array items: type: string example: https://cdn.example.com/return-images/abc123.jpg cart_items: type: array description: The items in the cart (exchange items or shop-now items). items: type: object properties: id: type: integer example: 201 variant_id: type: integer example: 501 product_id: type: - integer - 'null' example: 100 sku: type: - string - 'null' example: SHIRT-RED-S title: type: - string - 'null' example: Red Shirt variant_title: type: - string - 'null' example: Small translated_title: type: - string - 'null' description: > The product title in the shopper's locale, set when the item is added. `null` when no locale was sent, product translations are not enabled for the shop, or no translation exists. example: Chemise rouge translated_variant_title: type: - string - 'null' description: > The variant title in the shopper's locale, set when the item is added. `null` under the same conditions as `translated_title`. example: Petit price: type: - integer - 'null' description: The price in minor units (e.g. cents). example: 2500 image: type: - string - 'null' example: https://cdn.example.com/products/red-shirt.jpg exchange_type: type: - string - 'null' enum: - storefront - pos-storefront - variant-storefront - advanced-storefront - advanced - exchange - pos-exchange - recommended - recommended-storefront - null example: exchange exchange_for_returning_item_id: type: - integer - 'null' example: 1 selected_return_method: type: - object - 'null' description: The selected return shipping method. properties: id: type: integer name: type: string type: type: string enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store title: type: string logo_url: type: string location_url: type: string payment_intent: type: - object - 'null' description: > The payment intent attached to the draft return, if any. Loop removes it, and this field becomes `null`, when you set `processing_type` to `regular` or when Loop resets Instant to `regular` because Instant is no longer available. properties: id: type: integer provider: type: string provider_intent_id: type: string return_key: type: - string - 'null' description: The unique key for the resulting return once submitted. requires_uncollectible_payment: type: boolean description: > `true` when the draft return requires a payment but the shop has no usable Stripe connection, so Loop cannot collect it. When `true`, the `add-payment-intent` template and link are not offered and the draft return cannot be submitted. Change the draft so no payment is needed, for example by changing items or the return method. example: false DraftReturnContext: type: object description: > Contextual data for building the return UI. Keys are omitted when their value is null. properties: languages: type: - array - 'null' items: type: object properties: name: type: string abbreviation: type: string order: type: - object - 'null' properties: id: type: integer currency: type: string original_payment_transactions: type: array items: type: object properties: type: type: string gateway: type: - string - 'null' amount: type: integer currency: type: string brand: type: - string - 'null' last4: type: - integer - 'null' line_items: type: array items: type: object properties: id: type: integer provider_product_id: type: integer provider_variant_id: type: integer title: type: string variant_title: type: - string - 'null' sku: type: - string - 'null' description: type: - string - 'null' price: type: - integer - 'null' image: type: - string - 'null' parent_line_item_id: type: - integer - 'null' options: type: array items: type: object properties: name: type: string value: type: string return_reason_groups: type: - array - 'null' items: type: object properties: id: type: integer return_reasons: type: array items: type: object properties: id: type: integer name: type: string parent_return_reason_id: type: - integer - 'null' parent_return_reason_name: type: - string - 'null' is_commentable: type: boolean requires_comments: type: boolean items_eligible_to_return: type: - array - 'null' items: type: object properties: order_line_item_id: type: integer return_reason_group_id: type: integer expiration: type: - string - 'null' items_not_eligible_to_return: type: - array - 'null' items: type: object properties: order_line_item_id: type: integer ineligibility_code: type: string expiration: type: - string - 'null' return_reason_options: type: - array - 'null' items: type: array items: type: object properties: id: type: integer name: type: string is_commentable: type: boolean requires_comments: type: boolean exchange_options: type: - array - 'null' items: type: object properties: product_options: type: - array - 'null' items: type: object properties: name: type: string values: type: array position: type: - integer - 'null' description: > The 1-based Shopify product option position this dimension maps to. Clients should read variant option values by this position, not by array index, because single-value options may be omitted from this list. product_variants: type: array items: type: object properties: product_id: type: - integer - 'null' variant_id: type: integer title: type: - string - 'null' variant_title: type: - string - 'null' product_type: type: - string - 'null' options: type: object additionalProperties: type: string image: type: - string - 'null' price: type: - integer - 'null' currency: type: - string - 'null' is_available: type: boolean translated_title: type: - string - 'null' description: > The product title in the shopper's locale. `null` when no locale was sent, product translations are not enabled for the shop, or no translation exists. `title` always stays in the default language. translated_variant_title: type: - string - 'null' description: > The variant title in the shopper's locale. `null` under the same conditions as `translated_title`. `variant_title` always stays in the default language. translated_options: type: array description: > The variant's options in the shopper's locale, one entry per option in `product_options` and in the same order. Each name and value falls back to its default-language text. Empty when no option name or value is translated. items: type: object properties: name: type: string description: The option name, for example "Taille". value: type: string description: >- The value selected for this variant, for example "Petit". return_method_options: type: - array - 'null' items: type: object properties: id: type: integer name: type: string type: type: string enum: - box-and-ship - carrier-choice - drop-off - pick-up - in-store fee: type: integer title: type: string logo_url: type: string location_url: type: string processing_type_options: $ref: '#/components/schemas/ProcessingTypeOptions' DraftReturnError: type: object properties: code: type: string description: The error code. enum: - draft-returns-not-enabled - validation-failed - action-validation-failed - shop-not-found - order-lookup-failed - order-not-found - error-retrieving-order - secondary-input-mismatch - returns-unavailable-for-order - order-has-been-cancelled - order-line-item-get-data-failed - draft-return-not-found - draft-return-version-mismatch - draft-return-not-actionable - items-not-finalizable - totals-calculation-failed - return-creation-failed - terminal-state - context-generation-failed - action-generation-failed - no-eligible-return-methods - invalid-return-method - product-variant-not-found - product-variant-unavailable - return-reason-not-found - currency-mismatch - unsupported-feature - internal-error message: type: string description: Optional error message. HalLink: type: object properties: href: type: string description: The fully-qualified URL for this link relation. required: - href HalFormsTemplate: type: object properties: method: type: string description: The HTTP method for this action (POST, DELETE, etc.). title: type: string description: Human-readable title/description of the action. contentType: type: string description: The content type of the request body. default: application/json required: type: boolean description: > `true` when this action must be completed before the draft return can progress. For `select-return-method-carrier`, it is `true` while a label format still has to be picked and `false` once one is selected. This flag belongs to the template. It is separate from `required` on each entry in `properties`, which only says whether that field must be sent in the request body. properties: type: array description: Property descriptors for the action's fields. items: $ref: '#/components/schemas/HalFormsTemplateProperty' systemMessage: type: string description: > Only on an unanswered yes/no `add-returning-item-user-input` template. The merchant's "Response if yes" message in the draft return's language. When that language has no translation, it is the merchant's first configured message. It may contain HTML. Omitted when the merchant has not turned the response on or has no message. Show this message when the shopper answers `Yes`. If that answer removes the item from the draft return, the next response no longer has the item or its answered input, so keep this value from the template before you submit the answer. example:

Used cartridges cannot be returned.

ProcessingTypeOptions: type: object description: > Which processing types the draft return can use. In HAL-Forms responses this object is at `_embedded.processing_type_options`. Present only in the `items-finalized` state. Omitted in other states. properties: required: type: boolean description: > `true` when the return policy requires Instant. In that case the `regular` option has `available: false` with `unavailability_reason: instant-required`. example: false options: type: array description: One entry for `regular` and one for `instant`. items: $ref: '#/components/schemas/ProcessingTypeOption' HalFormsTemplateProperty: type: object properties: name: type: string description: The property name (snake_case). type: type: string description: > The property type. Common types: `number`, `text`, `boolean`, `hidden`. required: type: boolean description: Whether this property is required. prompt: type: string description: Human-readable prompt/description of the property. options: type: object description: > For enum-like fields, an object with `inline` containing the list of valid values. Send only a value from this list. properties: inline: type: array description: > Each item is either a value string or an object with `prompt` and `value`. When it is an object, send its `value`. items: oneOf: - type: string - type: object properties: prompt: type: string description: Human-readable label for the value. value: type: string description: The value to send in the request body. ProcessingTypeOption: type: object properties: type: type: string description: The processing type this entry describes. enum: - regular - instant available: type: boolean description: > Whether you can set this processing type now. Send only an available type to `set-processing-type`. When the draft has an exchange item, Instant runs as Instant Exchange and stays available even when the credit type is `refund`. unavailability_reason: type: - string - 'null' description: > Why this type is not available. `null` when `available` is `true`. - `not-enabled`: Instant is not turned on for this shop or return policy, or the shop cannot take the payment. - `not-applicable`: Instant does not apply to this draft, for example an in-store return, a return where every item is kept, or a return with nothing to charge. - `excluded`: An item in the draft is excluded from Instant. - `instant-required`: Only on `regular`. The return policy requires Instant. enum: - not-enabled - not-applicable - excluded - instant-required - null authorization_amount: description: > Only on an available `instant` option. The amount Loop holds (authorizes) on the shopper's payment method for Instant. `null` otherwise. oneOf: - $ref: '#/components/schemas/ProcessingTypeMoney' - type: 'null' charge_amount: description: > Only on an available `instant` option. The amount Loop charges for Instant. `null` otherwise. oneOf: - $ref: '#/components/schemas/ProcessingTypeMoney' - type: 'null' window_days: type: - integer - 'null' description: > Only on an available `instant` option. The Instant window, in days, from the return policy. `null` otherwise. example: 14 hold_window_days: type: - integer - 'null' description: > Only on an available `instant` option when Instant applies to a refund rather than an exchange. The hold window, in days, from the return policy. `null` otherwise. example: null ProcessingTypeMoney: type: object properties: amount: type: integer description: The amount in minor units (e.g. cents). example: 5000 currency_code: type: string description: The three-character ISO 4217 currency code. example: USD securitySchemes: api_key: type: apiKey in: header name: X-Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.