Second life (Circular)

In the Circular mode the shopper does not send an order back: they offer products to the shop for a second life, the shop values them, and the shopper is paid for what the shop accepts. This page describes the API behind the second-life portal. The returns and exchanges flow is covered in Create a return and Create an exchange; most concepts (sessions, shipping methods, labels, the error body) are the same.

The mode is enabled per shop. Every endpoint below answers an error when the shop has no Circular: 400 Circular is not enabled when the code is requested (POST /otp; the other login calls answer 400 Marketplace not found), 503 Catalog is not available for the current mode on the catalog.

Authentication

The second-life portal identifies the shopper by email alone, with a one-time code, because the products offered do not have to come from an order.

1. Request the code. marketplaceName is the URL name of the shop (the one in the portal address), mode and lang are query parameters, both required:

POST /otp?mode=Circular&lang=en
Content-Type: application/json

{ "email": "[email protected]", "marketplaceName": "your-shop" }

{ "message": "Verification code sent" }

2. Exchange the six-digit code received by email for a session token:

POST /otp/verify
Content-Type: application/json

{ "email": "[email protected]", "marketplaceName": "your-shop", "code": "123456", "mode": "Circular" }

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "2026-09-16T11:12:00.000Z"
}

The code is valid for seven minutes by default and for one use; five wrong attempts lock it. Each of /otp and /otp/verify is limited to six requests per minute per IP and email. A wrong or expired code answers 401 Unauthorized; an email the shop has blacklisted (or not whitelisted) answers 401 as well. The session is scoped to the shop and the email, not to an order: the endpoints that need an order (/products/{id}/options, /products/{id}/search, PATCH /orders/contact) do not work with it.

This flow is built for the portal: without a key, the call must come from a browser on a portal domain of the shop (Origin or Referer header: 401 ApiKeyRequired when there is neither, 400 Domain is not allowed from any other site). The partner API key described in Getting started identifies a server-side integration by itself and lifts that check.

A second way to open a session is the link the shopper receives by email once an offer exists: it carries a signed token that POST /auth exchanges for a session on that offer ({ "mode": "Circular", "token": "...", "internalId": "<id of the offer>" }).

What can be offered

Shops decide how the shopper picks products, and the answer of GET /orders reflects it. It is a list of pseudo-orders built from up to three sources, depending on the shop configuration:

• Catalog: one entry with every product of the shop catalog as items (returnable true, cannotBeExchanged true, no real fulfillment).
• Categories: one entry carrying categories, a tree whose leaves have reasons and questions, for shops that value by category instead of by product.
• Orders: the real orders of the shopper in the shop, with their line items and the units still available.

Two more entry points help build a picker:

• GET /orders/list: the orders of the shopper rendered as catalog products (id, name, createdAt, products[] with their variants, reasons and questions), skipping units already returned or offered.
• GET /products/catalog/{marketplaceUrlName}?mode=Circular&numResults=15&query=shirt: the public catalog of the shop, no session needed, paged with pageCursor and cursorAction (after or before; up to 15 products per page). Always pass mode=Circular: without it the endpoint answers the Returns catalog.
• GET /categories/{marketplaceUrlName}?mode=Circular: the category tree alone, public as well, with the reasons and questions of each leaf; the same tree GET /orders embeds, useful before the shopper logs in.

In every source each variant or category leaf carries the reasons the shopper can choose. Reasons decide the money: amount is the amount offered for the item (a percentage of the catalog price when isAmountPercentage is true), a reason with amountMax is a range between amount and amountMax the shop settles at appraisal, and an assessable reason means the shop will value the item after seeing it. The order entries of GET /orders expose only amount and isAmountPercentage; amountMax and assessable come with the catalog and category entries and with GET /products/catalog/.... Reasons also say what the shopper must provide: requireCustomerInfo, requireCustomerImage, minPicsRequired, minVideosRequired (see Attachments). questions are the extra questions of the shop, answered in answers.

The policy

GET /policies returns the rules of the shop for the mode of the token. In Circular the relevant fields are:

allowedPaymentMethods and maxNumberOfItems are not enforced by the API in Circular: honour them in your integration.

Shipping methods

An offer that ships needs a method. In Circular the API prices by weight and origin address rather than by order items:

POST /carriers/methods
Content-Type: application/json

{
  "weight": 1200,
  "addressParam": { "firstName": "Jane", "lastName": "Doe", "address1": "Calle Mayor 1", "city": "Madrid", "zip": "28013", "countryCode": "ES", "provinceCode": "M", "phone": "+34600000000" }
}

weight is in grams (20 to 80000). The response is the same list of methods as in returns, each with id (the methodId of the creation), shippingMethodId, shippingMethodType, price, needSchedule and, for pick ups, pickUpDates (see the returns guide). Without weight the request fails validation (400 ValidationFailed) unless items is sent instead; without addressParam the endpoint answers an empty list, not an error. The alternative POST /carriers/group-methods prices by country and province plus the selected products, categories or itemIds, grouped by shipping type.

Create the offer

There are two endpoints, and the policy decides which one to use.

Shops that accept offers directly

POST /purchases/create creates the offer with its shipping and payout in one call. The offer is accepted as it is (validationStatus Accepted), the label is generated (unless the shop pays through MultiSafePay and the payout does not cover the shipping, in which case the shopper pays first) and the shop receives the parcel.

POST /purchases/create?lang=en
Content-Type: application/json

{
  "contact": { "firstName": "Jane", "lastName": "Doe", "address1": "Calle Mayor 1", "city": "Madrid", "zip": "28013", "countryCode": "ES", "provinceCode": "M", "phone": "+34600000000" },
  "products": [
    {
      "id": "8253231888",
      "items": [
        { "variantId": "47046763118885", "reasonId": "9e09f0f3-55bd-4be9-ab86-971eeb773ded", "customerInfo": "Worn twice", "customerImageNames": ["c0ffee00-1111-4a4a-9c9c-bbbbbbbbbbbb"], "answers": [] }
      ]
    }
  ],
  "methodId": "fdba82c7-abd2-441f-9498-15227cfa0514",
  "shippingMethodId": "BNS_PCL",
  "shippingType": "DropOff",
  "paymentMethod": "BankTransfer",
  "iban": "ES9121000418450200051332",
  "holderName": "Jane Doe",
  "termsAndConditionsAcceptance": true
}

Shops that value first

When the policy says needValidation, use POST /purchases/request with only the items and the acceptance of the terms; no contact, shipping or payout yet:

{
  "products": [
    {
      "id": "8253231888",
      "items": [
        {
          "variantId": "47046763118885",
          "reasonId": "9e09f0f3-55bd-4be9-ab86-971eeb773ded"
        }
      ]
    }
  ],
  "termsAndConditionsAcceptance": true
}

The shop then values each item from its dashboard. The shopper receives an email with a link to the offer; from your integration, reopen it with POST /auth (token flow above) and read the appraisal:

GET /purchases/{internalId}/token

It returns the offer with validationStatus (Accepted or Rejected by the shop), includeUserPreValidation (whether the shopper has a say) and each item with its id, validationStatus, price (the amount offered) and validationReasonInfo when the shop declined it. The shopper closes the offer with one of two calls:

• POST /purchases/{internalId}/validate: accept and reject lists of { "itemId" } (the item id of the token response; reject entries may add reasonInfo), refundMethod (always required, with iban and holderName for BankTransfer), and the shipping (methodId, shippingMethodId, shippingType, desiredPickUp for pick ups, and contact, which an offer opened with /request needs because it has no address yet). Approved items left out of both lists stay Pending, so decide on all of them; when the shop does not let the shopper reject (includeUserPreValidation false), every approved item must be in accept. Accepting nothing marks the offer as rejected.
• POST /purchases/{internalId}/reject: no body; rejects the whole appraisal.

Calling /purchases/request on a shop without validation answers 400 Purchase prevalidation is not enabled. The opposite is not blocked: /purchases/create on a shop that values first skips the appraisal, so read needValidation before choosing.

The response and the follow-up

Both creation endpoints answer the offer:

{
  "internalId": "1789734400123",
  "name": "P-1789734400123",
  "state": "Pending",
  "creationDate": "2026-09-16T10:12:00.000Z",
  "currency": "EUR",
  "totalValue": 18.0,
  "shippingCost": 0,
  "paymentMethod": "BankTransfer",
  "shippingType": "DropOff",
  "needLabel": true,
  "items": [
    {
      "name": "Essentials slim T-shirt",
      "price": 18.0,
      "status": "OnHold",
      "reason": { "id": "9e09f0f3-55bd-4be9-ab86-971eeb773ded" }
    }
  ]
}

• internalId is the identifier of the offer in every other call (GET /purchases/{internalId}, /token, /label, /validate, /reject); GET /purchases/history lists the offers of the shopper with internalId, name and creationDate.
• items[].price is the amount offered for the unit; range reasons expose offerRangeMin and offerRangeMax and carry the upper bound in price until the shop settles them; a plain assessable reason with no catalog price shows 0 until the appraisal. totalValue is the sum after the bank-transfer deduction, if any.
• validationStatus, userValidationStatus, ibanLast4 and holderName are missing from the creation responses; read them from GET /purchases/{internalId} (or /token for the validation fields). items[].id is only meaningful in /token, where it is the offer item identifier that /validate expects; in the other responses it is the category id for category items and absent for product items.
• state follows the same values as returns (Pending, PendingApproval, Approved, PartiallyApproved, Declined, Cancelled) and items[].status starts at OnHold until the shop processes the parcel.
• The label (labelURL, qrCodeURL) and the tracking are generated asynchronously after the creation or after the shopper's validation; poll GET /purchases/{internalId} with bounded retries. GET /purchases/{internalId}/label answers 404 while no document exists.
• The payout is decided by the shop when it processes the offer; the API exposes no payment flag to the shopper beyond state.

Errors specific to this flow

The generic codes (ValidationFailed, Unauthorized, TooManyRequests, ServiceUnavailable) apply as described in Getting started.