Skip to main content
POST
Initialize Draft Return

Authorizations

X-Authorization
string
header
required

Headers

X-Shop-Id
integer

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.

Accept
enum<string>

Optional. Responses use Content-Type: application/prs.hal-forms+json.

Available options:
application/prs.hal-forms+json
X-Loop-Locale
string

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.

Example:

"fr-CA"

Body

application/json
order_name
string
required

The order name (the merchant's order identifier, for example an order number).

Example:

"#1001"

secondary_input
string
required

Any secondary input included by the shopper when looking up their order (for example, ZIP/postal code, email address, or phone number). A phone number matches the order's shipping address phone. If the order has no shipping address (for example, a local pickup order), it matches the billing address phone or the customer's phone instead.

is_gift
boolean

Whether or not the return will use Loop's Gift flow.

Example:

false

Response

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.

HAL _links object. Always includes self. Other keys are relation names corresponding to available actions for the current draft return state.

_templates
object

_templates object. Each key is a template/action name matching a relation in _links. Templates describe the method, fields, and constraints for the action.

client_application
object

Client-application header specification. Describes how the client should identify itself in subsequent requests.

draft_return
object

The draft return object.

context
object

Contextual data for building the return UI. Keys are omitted when their value is null.

errors
object[]

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 for a full list of possible errors.