Resail API

The Rexel API is organized around REST. Our API has a predictable resource-oriented URLs, accepts application/json request bodies and returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.

Just getting started ?

Check out our development quickstart guide

Accounts

Rexel API support multiple account for same client_id, client_secret by default it apply the same linkage of account that the admin has on the web.

Errors

Rexel API uses standard HTTP Status Codes to communicate errors. Also, a message is provided indicating more information about the error:

Attributes

`timestamp` date of the error
`status` will be same as http status
`message` will be use if `error` is underfined
`errors` array of :
* `field` in error
* `message` associated validation failure

HTTP STATUS CODES

200 OK Everything worked as expected.

400 Bad Request The request was unacceptable, often due to missing a
required parameter.

401 Unauthorized No valid API key provided _or_ Oauth token invalid

402 Request Failed The parameters were valid but the request failed.

403 Forbidden The API key _or_ your account doesn’t have
permissions to perform the request.

404 Not Found The requested resource doesn’t exist.

429 Too many requests Too many requests hit the API too quickly. We
recommend an exponential backoff of your requests.

500, 502, 503, 504 Server Errors Something went wrong on Rexel Api’s end.

Example: Could not find a product


HTTP 404
{
"timestamp": "2023-02-22T15:06:29.837+00:00",
"status": 404,
"message": "Product reference could not be found"
}

Example: Could validate email format


HTTP 400
{
"timestamp": "2025-02-22T15:06:29.837+00:00",
"status": 400,
"errors" : [
{
field : "email"
message : "email format is invalid"
}
]
}

Idempotent Write Operations

For write operations—such as creating an order—the Resail API supports idempotency.
Idempotency ensures that if the same request is sent multiple times (for example due to network retries or client-side timeouts), the API will not create duplicate resources or trigger the same action repeatedly.

How Idempotency Works

To enable idempotency, clients can include an idempotency identifier in the request header.
This value should be:

  • unique per intended business action

  • stable across retries

  • generated by the client application (e.g., the order’s business ID)

Example header:

Idempotency-Key: <unique_business_identifier>

Retry Behavior

When the API receives a write request with an idempotency key:

  • If it is the first time, the operation is processed normally.

  • If the same request (same endpoint + same parameters + same idempotency key) is replayed,
    the API returns the same successful response, without executing the action again.

This protects your system from duplicated orders or repeated side effects.

Handling Mismatched Requests

If a request is retried with the same idempotency key but different body or parameters, the API will reject it.

The response will be:

  • HTTP 400 Bad Request

  • An explanation stating that the operation cannot be replayed with different data

This prevents accidental inconsistencies that could occur if an idempotency key is reused improperly.

Best Practices

  • Use a stable identifier from your domain model (e.g., your internal order ID).

  • Never reuse an idempotency key for different business actions.

  • Log the idempotency key with your request for easier debugging.

Idempotency makes your integration more reliable, especially in distributed systems where retries may occur automatically.

Metadata

For write operations such as order creation, you can include a metadata object in your request payload.
This metadata is not processed by the Resail API itself but is stored and returned so you can associate Resail operations with your own internal business logic.

A common use case is to include your client-side order identifier inside the metadata.
This allows you to:

  • Track the order using your own reference

  • Retrieve or reconcile the order later

  • Simplify debugging and auditing between systems

Example

{   
  "order": {     
    "items": [ ... ],     
    "metadata": {       
      "clientOrderId": "ORD-2025-002348"     
    }   
  } 
}

When you later query the order, the metadata will be returned unchanged, allowing you to directly map the Resail order to your internal data.

Including metadata is optional, but strongly recommended for systems that require cross-referencing between platforms.