Download OpenAPI specification:
This API is versioned using dates, based on when the version was released
(e.g. 2026-04-02). Whenever breaking changes are introduced, the version
is updated.
Clients can specify which version they expect by adding the X-Api-Version
header to a request (e.g. X-Api-Version: 2026-04-02). If a resource
is deprecated or requires a higher version, the server adds
Deprecation and Sunset
headers to the response. For example:
Deprecation: @1775080800 # HTTP date (UNIX)
Sunset: Fri, 02 Oct 2026 00:00:00 UTC # RFC1123 timestamp
Important: these headers are used to notify clients of breaking changes, so it is recommended to log and monitor them in order to upgrade in time. The client is given an upgrade window of 6 months, during which the deprecated resource is still supported. If a client has not upgraded before the sunset date, the server may respond with an error, or stop responding altogether. Breaking changes and upgrade information can be found here.
When the client does not include the version header, the first published
API version is assumed (2026-04-02).
Fulfillment API
customerEmail field to the request body.Reorganized all endpoints into three main APIs: Checkout, Fulfillment and Return. Paths have been prefixed with /checkout, /fulfillment and /return respectively. Old endpoints have been deprecated and will be removed in the future.
API keys are provided by BOXO to authenticate with this API, and contain the appropriate scopes for your business needs. Attempting to access endpoints outside of these scopes may result in an authentication error.
By default, API usage is rate limited to 5 requests per second per API key.
Exceeding this limit may result in a 429 Too Many Requests response.
A sandbox environment of this API is available at https://sandbox-api.boxo.nu, which may be used during development. A separate API key is provided for authentication. Please note that this environment is intended to be used during development and testing only, and only works with the provided example values.
Deprecated since version 2026-05-27.
Check if BOXO Return is available for the given postal code.
| postalCode required | string Example: 8932PA Dutch postal code in the format 1234AB. |
{- "available": true
}Load deposit onto a bag.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
| customerName required | string Name of the customer in the checkout. |
| customerEmail required | string <email> Email address of the customer in the checkout. |
{- "customerName": "Jane Doe"
}{- "code": "bag_has_deposit",
- "message": "string"
}Cancel a deposit that was previously loaded onto a Bag. This can be done to correct mistakes, and is only allowed within two hours after loading.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "code": "no_deposit",
- "message": "string"
}Return a bag back to the warehouse, in the event of an order being returned by a customer. The bag may be loaded with deposit again after a successful request.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "code": "no_deposit",
- "message": "string"
}Deprecated since version 2026-05-27.
Load deposit onto a bag.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "code": "bag_has_deposit",
- "message": "string"
}Deprecated since version 2026-05-27.
Cancel a deposit that was previously loaded onto a Bag. This can be done to correct mistakes, and is only allowed within two hours after loading.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "code": "no_deposit",
- "message": "string"
}Deprecated since version 2026-05-27.
Return a bag back to the warehouse, in the event of an order being returned by a customer. The bag may be loaded with deposit again after a successful request.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "code": "no_deposit",
- "message": "string"
}Get information about a bag.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| Retailer-Id | string <uuid> (RetailerId) Required for fulfillment locations using a single API key to act of behalf of multiple retailers. |
{- "gs1SerialNumber": "1234567812345678",
- "status": "deposit_loaded",
- "deposit": {
- "retailerId": "7d655746-feeb-4a09-9d4e-b23e12b2337a",
- "loadedAt": "2019-08-24T14:15:22Z"
}
}Get information about a bag.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
{- "depositAmount": 395
}Return a bag at the specified return point. Any active deposit will be removed from the bag after a successful request.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| returnPointQrId required | string <uuid> QR id of the return point at which the bag is being returned. |
{- "returnPointQrId": "34bcb67c-d9ed-410a-a7a5-ee18614b800b"
}Deprecated since version 2026-05-27.
Get information about a return point.
| returnPointId required | string <uuid> Example: 90503fed-1a96-427a-b5d1-fc86f0257eb8 Id of the return point. |
{
}Deprecated since version 2026-05-27.
Get information about a bag.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
{- "depositAmount": 395
}Deprecated since version 2026-05-27.
Return a bag at the specified return point. Any active deposit will be removed from the bag after a successful request.
| gs1SerialNumber required | string (GS1SerialNumber) = 16 characters Example: 1234567812345678 GS1 serial number that is obtained by parsing the GS1 Digital Link URI contained in the QR code of a bag. |
| returnPointQrId required | string <uuid> QR id of the return point at which the bag is being returned. |
{- "returnPointQrId": "0e7fc65c-e30b-4183-914d-bf15ed9ccfe9"
}