Getting started

The Drelife merchant API is the API behind the Drelife dashboard: the shop staff uses it to configure the shop and to manage the returns, exchanges, second-life purchases and repairs of its shoppers. It is meant for the shop and its tools, not for the shoppers themselves: integrations that act on behalf of a shopper (a chat creating a return, for instance) use the customer API instead.

Environments

Every request and response is JSON. Errors share one body: { "statusCode", "errorCode", "message", "path" }, where errorCode is stable and documented in the API reference.

Authentication

Log in with a user of the shop. password accepts the password of the user or its access token, the one shown in the credentials email of the user.

POST /login
Content-Type: application/json

{
  "user": "[email protected]",
  "password": "********"
}

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": "2026-09-16T11:12:00.000Z",
  "tokenType": "Bearer",
  "roles": ["StoreOwner"],
  "modes": ["Returns"]
}

The login answers 201. Send the token as a Bearer token on every other request. Each endpoint of the reference states the roles allowed to call it; a user without the role gets a 403 Forbidden. Tokens expire at expiresIn (one hour by default); log in again when they do.

Log in with an API key

An integration of the shop (an ERP, a warehouse tool, a partner processing your requests) should not hold the password of a person. Give it a merchant API key instead (see below) and it logs in with the key in the X-Api-Key header, no body:

POST /login/api-key
X-Api-Key: drk_4Fh9Kz2QpL8mN3vB6xC1dE5fG7hJ9kM2nP4qR6sT

The answer is the same as POST /login, for the user of the shop the key acts as: the token carries the roles and modes of that user, and everything the integration does is recorded as done by that user. When the token expires, log in with the key again. 401 InvalidApiKey when the key is unknown, revoked, a customer API key, or its user is disabled or deleted. A session opened with a key:

• ends within a minute (401 ApiKeyRevoked) once the key is revoked, or its user is disabled, deleted or loses a role or mode the session carries (log in with the key again to get the current ones);
• cannot manage users nor API keys (403 NotAvailableWithApiKey), so a leaked key cannot create accounts or keys that outlive its revocation.

API keys

An API key opens one API, chosen when it is created:

• Customer keys: a partner (a chat, a helpdesk, any integration working for your shoppers) uses the customer API with them. The key identifies the partner, lets it log in as your shoppers from its servers and gives it its own rate limit; it grants nothing on this API. Store owners and managers create them.
• Merchant keys: an integration logs in on this API with them, acting as a user of the shop you choose. The key never has more permissions than that user: to limit what an integration can do, create a user with the role it needs (for instance Approver) and bind the key to it. Only store owners create them.

A partner that needs both APIs gets two keys, revoked independently.

Create a key, once per partner and API. The key itself is only returned in this response: copy it and hand it to the partner through a secure channel. scope defaults to Customer; a Merchant key needs the userId of an enabled user of the shop.

POST /api-keys
Authorization: Bearer ...
Content-Type: application/json

{ "name": "Konvo" }

POST /api-keys
Authorization: Bearer ...
Content-Type: application/json

{ "name": "Warehouse ERP", "scope": "Merchant", "userId": "2c9a4f1e-8b7d-4e6a-9f3c-1d2e3f4a5b6c" }

{
  "id": "7b1f0c7e-3e2a-4f4a-9c1d-2e5f6a7b8c9d",
  "name": "Warehouse ERP",
  "prefix": "drk_4Fh9Kz2Q",
  "key": "drk_4Fh9Kz2QpL8mN3vB6xC1dE5fG7hJ9kM2nP4qR6sT",
  "scope": "Merchant",
  "userId": "2c9a4f1e-8b7d-4e6a-9f3c-1d2e3f4a5b6c",
  "userEmail": "[email protected]",
  "createdBy": "[email protected]",
  "createdAt": "2026-09-16T09:00:00.000Z",
  "lastUsedAt": null,
  "revokedAt": null
}

List the keys of the shop. Only the prefix of each key is kept, enough to tell them apart; lastUsedAt tells you whether the partner is using it, and scope, userId and userEmail what it opens.

GET /api-keys

Revoke a key when the partner leaves or the key leaks. The API it is for refuses the key, and the sessions it opened, within a minute. Revoking is final: create a new key if the partner needs one again.

DELETE /api-keys/7b1f0c7e-3e2a-4f4a-9c1d-2e5f6a7b8c9d

Webhooks

Drelife can notify a URL of your choice (or of your partner) when a return, a second-life purchase or a repair of the shop is created, updated or deleted. Subscriptions are configured by Drelife on request: send the HTTPS URL, the events and any header the endpoint needs, and you get back the secret that signs every notification (X-Webhook-Signature, HMAC SHA-256 of the body). The payload and the headers are described in Integrations.

Invoices from Drelife

The monthly invoices Drelife sends the shop are available to its StoreOwner and Manager users only:

GET /invoices

The answer is an array of { id, mode, period, notifiedAt, status, paidAt, invoiceDocument, additionalDocuments }, latest period first. Each mode the shop works in is invoiced on its own: mode is the one the invoice bills (Returns, Circular or Repair), so a month may hold one invoice per mode. period is the month the invoice bills, as YYYY-MM (the month before it was sent), and notifiedAt when the shop was sent it. status is PaymentPending until Drelife registers the payment and PaymentCompleted after, with paidAt the date it was marked as paid (null while pending). invoiceDocument is the invoice itself (a PDF), { id, name, size, mimetype }, or null; additionalDocuments lists the other documents of the invoice (its supporting spreadsheet, annexes), newest first, with the same shape. Only the invoices the shop has been sent are listed, paid or not (drafts Drelife is still preparing never are); mode keeps those of one mode only (GET /invoices?mode=Repair, 400 for an unknown one) and page / pageSize paginate, with or without it.

GET /invoices/{id} reads one invoice and GET /invoices/{id}/documents/{documentId}/content streams the bytes of one of its documents, with the Content-Type and the name of that document: Content-Disposition: inline for a PDF or an image, attachment for a spreadsheet, never cacheable. There is no public URL of a document: the content is only served through that call, with the Bearer token. 404 Invoice not found when the invoice does not belong to the shop, is a draft or has not been sent yet, 404 Document not found when the document is not one of that invoice, and 404 File content not found when its content is no longer available.

To save everything at once, GET /invoices/{id}/download answers the only document of the invoice as it is, named after its month and its mode (lowercased) with its own extension (factura-drelife-2026-08-returns.pdf), or a ZIP of all of them (factura-drelife-2026-08-returns.zip, invoice PDF first), always as an attachment. POST /invoices/download with { "ids": [...] } (1 to 50 different invoices) answers Facturas Drelife.zip, with everything under a Facturas Drelife/ folder and one folder per invoice inside it, named by its month (Facturas Drelife/2026-08/, then Facturas Drelife/2026-08 (2)/ if a month repeats), in the order of ids. When the selection spans several modes, each folder carries the mode of its invoice after the month (Facturas Drelife/2026-08 Returns/, Facturas Drelife/2026-08 Repair/). Repeated file names are suffixed (sample.pdf, sample (2).pdf). Both are built while they are sent and never cacheable; 404 Invoice not found when any invoice is not one the shop can read, and 404 File content not found when there is no document or one of them is no longer available, before anything is sent.

Where to go next

• Set up your shop: address, policies, reasons, carriers, portal look, access lists, staff, notifications and banners.
• Process returns and exchanges: the lifecycle of a request from the shop side.
• Orders: the orders synced from your platform and what the shop can do with them.
• Second life and repairs: offers, second-life stock and repair quotes.
• Requests: the unified list of returns, exchanges, offers and repairs.
• Integrations: API keys, webhooks and the connection with your platform.
• API reference: every endpoint, with its parameters, responses and errors.
• Customer API: the API the partners integrate with, and the step-by-step guide to create a return or an exchange.