Orders

Orders come from your platform: Drelife imports them (Shopify, PrestaShop and Logicommerce) or receives them from the shop (a Custom platform), and every return, exchange, second-life offer or repair hangs from one of them. The merchant API reads them, adjusts two things per fulfillment, and, on a Custom platform, creates and deletes them. All calls need StoreOwner, Manager or Approver, except creating and deleting, reserved to StoreOwner and Manager.

Find an order

Two searches exist. GET /orders/search?search=1029 is the quick picker: up to twenty orders matching the order name or number, newest first and excluding draft orders, as { "id", "orderName" }. GET /orders/returns/list is the paged list used by the returns screens, fifteen per page:

GET /orders/returns/list?page=0&search=jane&startDate=2026-08-01&endDate=2026-09-16&sortField=date&sortOrder=DESC

{
  "items": [
    { "id": "7f6e5d4c-3b2a-4190-8e7d-6c5b4a392817", "orderName": "#1029", "customerName": "Jane Doe", "customerEmail": "[email protected]", "createdAt": "2026-09-01T10:12:00.000Z" }
  ],
  "page": 0,
  "hasNext": true
}

search matches the order name or number, the email and the customer name (several words match first and last name); customerName, customerEmail and orderName (name or number) narrow one field each; startDate and endDate bound the creation date; sortField is date, order, customer or email. There is no total count: page while hasNext is true.

Read an order

GET /orders/7f6e5d4c-3b2a-4190-8e7d-6c5b4a392817

:id accepts the Drelife identifier or the identifier of the order in your platform.

{
  "id": "5294120468773",
  "name": "#1029",
  "creationDate": "2026-09-01T10:12:00.000Z",
  "currency": "EUR",
  "totalValue": 89.80,
  "discount": 0,
  "tags": ["vip"],
  "customer": { "firstName": "Jane", "lastName": "Doe", "email": "[email protected]", "phone": "+34600000000", "currency": "EUR" },
  "shippingAddress": { "firstName": "Jane", "lastName": "Doe", "address1": "Calle Mayor 1", "city": "Madrid", "zip": "28013", "countryCode": "ES", "provinceCode": "M", "phone": "+34600000000" },
  "billingAddress": { "...": "..." },
  "parentOrder": null,
  "fulfillments": [
    {
      "id": "0c1d2e3f-...",
      "externalId": "5294120468773",
      "name": "#1029.1",
      "createdAt": "2026-09-02T08:00:00.000Z",
      "maxReturnDate": "2026-10-02T08:00:00.000Z",
      "trackingStatus": "Delivered",
      "trackingNumber": "12345678",
      "trackingUrl": "https://...",
      "trackingDeliveredAt": "2026-09-04T12:30:00.000Z",
      "items": [
        {
          "id": "14577068736858",
          "productId": "8253231888",
          "variantId": "47046763118885",
          "name": "Essentials slim T-shirt",
          "description": "M / Black",
          "price": 29.90,
          "discount": 0,
          "weight": 0.25,
          "quantity": 2,
          "quantityReturned": 1,
          "eligibility": {
            "return": { "allowed": true, "blockers": [] },
            "exchange": { "allowed": false, "blockers": [ { "code": "OutOfDate", "detail": "PolicyDays" } ] },
            "quantityAvailable": 1,
            "returnDeadline": "2026-10-02T08:00:00.000Z",
            "exchangeDeadline": "2026-09-16T08:00:00.000Z",
            "maxReturnDays": 30,
            "maxExchangeDays": 14
          }
        }
      ]
    }
  ],
  "returns": [ { "id": "1a2b3c4d-...", "name": "1029-R1", "state": "Pending", "createdAt": "2026-09-15T09:12:00.000Z", "fulfillmentIds": ["0c1d2e3f-..."], "includeReturn": true, "includeChange": false } ],
  "purchases": [],
  "repairs": []
}

Notes on the shape:

id is the identifier of the order in your platform; the Drelife identifier is the one the lists return. parentOrder is set on the exchange orders Drelife created (the Drelife id and the name of the original order).
Each unit line has quantity, quantityReturned and, in eligibility, quantityAvailable (what can still be requested). weight is in kilograms.
eligibility tells whether a return or an exchange is possible right now and why not: blockers[].code is StoreInactive, ReturnsDisabled, ExchangesDisabled, ItemNotReturnable, Blacklisted or NotWhitelisted (detail Email, OrderName, OrderTag, CustomerTag), ProductBlacklisted (detail ID, Name, Tag, CustomAttribute), NoQuantityAvailable or OutOfDate (detail MaxReturnDate or PolicyDays); detail is only present for the blacklist, product and date blockers. It is computed with the rules of Set up your shop and omitted when they cannot be evaluated.
returns, purchases and repairs list the requests already made on the order, with their state and the fulfillments they touch.
labelURL, qrCodeURL and labelCreated on a fulfillment are only filled for shops using Drelife direct logistics on Shopify.

Adjust a fulfillment

Two things can be changed on an order. Extend or shorten the return window of a fulfillment:

PATCH /orders/{id}/fulfillments/{fulfillmentId}/update-return-date
Content-Type: application/json

{ "maxReturnDate": "2026-12-31T23:59:59.000Z" }

The date must be in the future (400 maxReturnDate must be ahead of now); it overrides the policy windows of that fulfillment for returns and exchanges, and eligibility reflects it in returnDeadline and exchangeDeadline. And record that the outbound parcel was delivered, which starts the return window when it counts from the delivery:

PATCH /orders/{id}/fulfillments/{fulfillmentId}/mark-delivered
Content-Type: application/json

{ "deliveredAt": "2026-09-04T12:30:00.000Z" }

deliveredAt defaults to now. fulfillmentId accepts the Drelife identifier or the one of your platform. Both answer the updated fulfillment.

Orders of a Custom platform

Shops without a connected platform push their orders themselves. POST /orders answers 201 with the order as read above:

POST /orders
Content-Type: application/json

{
  "id": "ORD-1029",
  "name": "#1029",
  "tags": [],
  "discount": 0,
  "customer": { "externalID": "CUST-77", "firstName": "Jane", "lastName": "Doe", "email": "[email protected]", "currency": "EUR", "phone": "+34600000000" },
  "shippingAddress": { "firstName": "Jane", "lastName": "Doe", "address1": "Calle Mayor 1", "city": "Madrid", "zip": "28013", "countryCode": "ES", "provinceCode": "M", "phone": "+34600000000" },
  "billingAddress": { "firstName": "Jane", "lastName": "Doe", "address1": "Calle Mayor 1", "city": "Madrid", "zip": "28013", "countryCode": "ES", "provinceCode": "M", "phone": "+34600000000" },
  "fulfillments": [
    {
      "id": "ORD-1029-F1",
      "name": "#1029.1",
      "tracking": { "number": "12345678", "url": "https://tracking.example.com/12345678", "status": "Delivered" },
      "items": [
        { "id": "LINE-1", "productId": "PROD-55", "variantId": "VAR-551", "variantTitle": "M / Black", "name": "Essentials slim T-shirt", "sku": "TS-M-BLK", "price": 29.90, "discount": 0, "weight": 250, "quantity": 2, "image": "https://cdn.example.com/ts.jpg", "returnable": true }
      ]
    }
  ]
}

Field	Rules
`id`, `name`	Required, up to 50 characters; `id` is your identifier and must be unique (`400 Order Name or External ID already exists`)
`customer`	`externalID`, `firstName`, `lastName`, `email`, `currency` (up to 3 characters) required; `phone` (E.164, with `+`), `note`, `tags` optional
`shippingAddress`, `billingAddress`	Both optional and independent (the billing address is not copied from the shipping one). When present: `firstName`, `lastName`, `address1`, `countryCode` (2 letters), `zip`, `phone` (E.164) required; `address2`, `city`, `company`, `country`, `province`, `provinceCode` optional. Text fields are limited to extended ASCII
`fulfillments[]`	`id`, `name` required; `locationId`, `tracking` (`number`, `url`, `status` as a tracking status such as `Delivered`) optional; at least one item each
`fulfillments[].items[]`	`id`, `productId`, `name` (50 characters, like every identifier and `sku`, `vendor`, `variantTitle`), `price`, `weight` (grams, positive integer), `quantity` required; `variantId` (then `variantTitle` too), `description` (255), `image` (URL), `discount` (the total discount of the line; the response shows it per unit), `sku`, `vendor`, `tags`, `returnable` (default `true`) optional

DELETE /orders/{id} removes an imported order and answers true, unless it has returns (400 Order has returns and cannot be deleted). Both calls are refused on a shop connected to a platform (400 Orders can only be created in a Custom CMS, 400 Orders can only be deleted in a Custom CMS). There is no update endpoint: delete and create again while the order has no returns.

Errors of this page

HTTP	Message	Meaning
404	`Order not found`	Unknown order for this shop (Drelife or platform identifier)
404	`Fulfillment not found`	Unknown fulfillment on that order
400	`maxReturnDate must be ahead of now`	The new return window is in the past (a malformed date is a `ValidationFailed`)
400	`Orders can only be created in a Custom CMS` / `Orders can only be deleted in a Custom CMS`	The shop has a connected platform
400	`Order Name or External ID already exists`	Duplicate `id` or `name`
400	`Order has returns and cannot be deleted`	Delete refused
400	`ValidationFailed`	A body or query rule above; `message` lists the fields