Return Create Overview

Return Create API

The Return Create 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/remove items, set customer and address details, finalize selections, and submit the completed return.

Return type

Each returning item has its own set-returning-item-return-type link. The values you can send depend on the item, so send only a value from that link’s allowed_values. A return type the item does not allow is rejected with action-validation-failed. exchange is not offered when the item’s return policy turns exchanges off, even if Shop Now is on. On a warranty claim, only the outcomes the warranty allows are offered, even when the item is still within its return window. See Set Returning Item Return Type.

Processing type

draft_return.processing_type is regular or instant. Every draft return starts as regular. In the items-finalized state, context.processing_type_options shows which processing types you can use:

{
  "context": {
    "processing_type_options": {
      "required": false,
      "options": [
        {
          "type": "regular",
          "available": true,
          "unavailability_reason": null,
          "authorization_amount": null,
          "charge_amount": null,
          "window_days": null,
          "hold_window_days": null
        },
        {
          "type": "instant",
          "available": true,
          "unavailability_reason": null,
          "authorization_amount": { "amount": 5000, "currency_code": "USD" },
          "charge_amount": { "amount": 5000, "currency_code": "USD" },
          "window_days": 14,
          "hold_window_days": null
        }
      ]
    }
  }
}

Field	Meaning
`required`	`true` when the return policy requires Instant. `regular` is then unavailable.
`options[].type`	`regular` or `instant`.
`options[].available`	Whether you can set this type now.
`options[].unavailability_reason`	Why the type is unavailable: `not-enabled`, `not-applicable`, `excluded`, or `instant-required`. `null` when available.
`options[].authorization_amount`	The amount Loop holds (authorizes) for Instant, in minor units.
`options[].charge_amount`	The amount Loop charges for Instant, in minor units.
`options[].window_days`	The Instant window, in days, from the return policy.
`options[].hold_window_days`	The hold window, in days. Set only when Instant applies to a refund rather than an exchange.

The amounts and day counts are set only on an available instant option. They are null otherwise. When the draft has an exchange item, Instant runs as Instant Exchange. It stays available even when the credit type is refund. To change the processing type, call the set-processing-type link and send only a value from its allowed_values. See Set Processing Type.

Instant reset

While the draft is in items-finalized, Loop checks on every request (including GET and submit) whether Instant is still available. If it is not, Loop:

sets draft_return.processing_type to regular
removes the payment intent, so draft_return.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.

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 link is offered and marked required. Call it (POST /draft-returns/{draft_return_id}/payment-intent) before you submit.
If the shop has no usable Stripe connection, Loop cannot collect the payment. The add-payment-intent link is not offered and draft_return.requires_uncollectible_payment is true. The draft return cannot be submitted. 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 draft_return.payment_intent comes back null. Check processing_type and payment_intent before you submit. If a payment is still needed, the add-payment-intent link is offered again.

Using the API

APIs

Return Create API

Return type

Processing type

Instant reset

Payment

​Return Create API

​Return type

​Processing type

​Instant reset

​Payment

Return Create API

Return type

Processing type

Instant reset

Payment