Create headless return

API docs by Redocly

Create headless return

Download OpenAPI specification:Download

This is only for headless merchants. Please see the implementation guide for more details.

Overview

For partners and merchants who want to keep their own return flow, but use Happy Returns to manage return shipments across various drop-off methods. View the implementation guide for more details.

Authentication

Partners can authenticate for this endpoint by following the steps here: API set up.

Create Return

Creates a return for headless retailers. https://partner.happyreturns.com/create_return

header Parameters
X-Hr-Apikey
required
string

A partner’s API key. The partner must be authorized by Happy Returns to create headless returns. Contact Happy Returns to grant permission.

Example: your-api-key

Request Body schema: application/json
required

Request body to send to create a return

One of
retailer_id
required
string

The identifier of the retailer for the returning items. This needs to match an already existing retailer, cannot be arbitrary.

email
required
string

The email address on the order for sending email confirmations for the return

return_fee
string

Return fee amount with currency code

dropoff_method_id
string

Shopper selected dropoff method ID of the return, which can be one of the following return-bar, in-store, mail, mail-nolabel, or mail-nobox-nolabel (Defaults to "return-bar" if not specified).

dropoff_methods_offered
Array of strings

Methods offered to the shopper. Used by Happy Returns for evaluating the user's experience. Can be one or more from the following return-bar, mail, mail-nolabel, mail-nobox-nolabel, mail-shopper-provided, in-store, home-pickup, or other.

  • return-bar - Shopper receives a QR code for box-free drop off at a Happy Returns' Return Bar
  • mail - Shopper receives a prepaid printable label
  • mail-nolabel - Shopper receives a QR code for pre-packaged drop off at a participating drop off location
  • mail-nobox-nolabel - Shopper receives a QR code for pre-packaged drop off at a The UPS Store® location
  • mail-shopper-provided - Shopper instructed to purchase their own shipping label
  • home-pickup - Return is picked up from shopper’s location
  • retailer-store - Shopper receives a QR code for drop off at a merchant store location
  • other - Other - Some other method not listed above
Array of objects (Return Item)

The purchases being returned

Responses

Response Schema: application/json
One of
rma_id
required
string

The shopper facing RMA ID for the return that was created. This ID can be used by the customer to look up a return at a return bar that was started through the partner/retailer return app by providing it to the Returnista

qr_code
required
string

The URL to download the QR code generated for the return. This QR code can be used by the customer to more quickly look up a return at a return bar that was started through the partner/retailer return app by showing it to the Returnista to scan

Request samples

Content type
application/json
Example
{
  • "retailer_id": "modern-retailer",
  • "email": "customer@example.com",
  • "return_fee": "5.00 USD",
  • "dropoff_method_id": "return-bar",
  • "dropoff_methods_offered": [
    ],
  • "returning": [
    ]
}

Response samples

Content type
application/json
Example
{}