# Order records
An order record represents the finalized state of an order that has already been completed or originated outside the operational OMS flow. Unlike an [order](/documentation/by-pillar/order-management/orders.md), an order record doesn't express customer intent that needs to be fulfilled. It captures what happened, not what needs to happen next. It doesn't participate in the fulfillment lifecycle and doesn't trigger routing, picking, packing, shipping, or any downstream operational processes.
Order records exist to make non-operational order data available for audit, analytics, and reporting, without adding load or complexity to the operational OMS.
## Distinction between order and order record
| Dimension | Order record | Order |
| ------------------- | ------------------------------------ | -------------------------------------- |
| Purpose | Persist completed or external orders | Create demand and trigger fulfillment |
| Lifecycle | No lifecycle | Full lifecycle with events |
| Downstream entities | None | Yes (pick jobs, pack jobs, parcels, …) |
| Validation | Minimal | Strict |
| Input type | Offline, batch, legacy, historical | Real-time operational orders |
| Cost profile | Low (storage-oriented) | Higher (event-driven, stateful) |
## Create order records
Order records are created using a bulk endpoint that accepts up to 25 records per request. To create order records, call the following `PUT` endpoint:
{% tabs %}
{% tab title="Endpoint" %}
```http
PUT https://{projectId}.api.fulfillmenttools.com/api/orderrecords
```
{% endtab %}
{% tab title="Request example" %}
```json
{
"operations": [
{
"tenantOrderRecordId": "A-RECORD-99211",
"orderRecordDate": "2026-03-24T13:21:00.000Z",
"facilityRef": "22675b17-04d3-40eb-8970-5a5a382b4a76",
"consumer": {
"consumerId": "429117bb-6de0-462c-9062-44d7e6d68db2",
"email": "anna.mueller@example.com",
"addresses": [
{
"firstName": "Anna",
"lastName": "Müller",
"street": "Hauptstraße",
"houseNumber": "34",
"postalCode": "50667",
"city": "Köln",
"province": "Nordrhein-Westfalen",
"country": "DE"
}
]
},
"lineItems": [
{
"article": {
"tenantArticleId": "ELEC-CAMERA-INSTANT",
"title": "Sofortbildkamera Mini",
"attributes": [
{
"category": "descriptive",
"priority": 100,
"key": "Filmformat",
"value": "Instax Mini",
"type": "STRING"
},
{
"category": "basePrice",
"key": "value",
"value": "7499"
},
{
"category": "basePrice",
"key": "currency",
"value": "EUR"
},
{
"category": "basePrice",
"key": "decimalPlaces",
"value": "2"
}
]
},
"quantity": 1,
"warranty": {
"warrantyStartDate": "2026-03-23T23:00:00.000Z",
"warrantyPeriod": "P2Y"
},
"returnPolicy": {
"isReturnable": true,
"returnWindowEndDate": "2026-04-22T22:00:00.000Z"
}
}
],
"payments": [
{
"paymentMethod": "Cash",
"value": {
"value": 8246,
"currency": "EUR",
"decimalPlaces": 2
},
"status": "COMPLETED"
}
],
"origin": {
"type": "POS",
"terminalId": "terminal-99211",
"cashierId": "cashier-99211"
}
}
]
}
```
{% endtab %}
{% tab title="Response example" %}
If the request was successful, it returns an HTTP `200 OK` response with a summary and details for each operation:
`summary`: Counts of created, updated, and unchanged records in the batch
`details[].status`: The result for each operation — `CREATED`, `UPDATED`, `UNCHANGED`, or `FAILED`
`details[].orderRecord`: The full order record object including system-generated fields
`details[].error`: Present when status is `FAILED`, contains `type` and `message`
{
"summary": {
"created": 1,
"updated": 0,
"unchanged": 0
},
"details": [
{
"status": "CREATED",
"orderRecord": {
"id": "665a1b2c3d4e5f6a7b8c9d0e",
"version": 1,
"tenantOrderRecordId": "A-RECORD-99211",
"orderRecordDate": "2026-03-24T13:21:00.000Z",
"facilityRef": "22675b17-04d3-40eb-8970-5a5a382b4a76",
"created": "2026-03-24T14:00:00.000Z",
"lastModified": "2026-03-24T14:00:00.000Z",
"anonymized": false
}
}
]
}
{% endtab %}
{% endtabs %}
## Order record structure
### Required fields
* `orderRecordDate`: Date and time of the transaction (ISO 8601)
* `facilityRef`: Reference to the facility where the transaction occurred
* `lineItems`: Array of purchased items (1–500 items)
### Optional fields
* `tenantOrderRecordId`: Your external order record ID for reference
* `consumer`: Customer information including `consumerId`, `email`, and `addresses` (up to 10)
* `payments`: Payment details (up to 100) including method, amounts, and status (`COMPLETED`, `FAILED`, `CANCELLED`, `REFUNDED`, `PARTIALLY_REFUNDED`)
* `origin`: POS origin information with `terminalId` and `cashierId`
* `pricing`: Order-level pricing breakdown with discounts (up to 100), fees (up to 100), and taxes (up to 100)
* `customAttributes`: Free-form key-value attributes for tenant-specific data
### Line items
Each line item requires an `article` with a `tenantArticleId` and a `quantity` (minimum 1). Optional fields include:
* `article.title`: Product name
* `article.attributes`: Product attributes with `key`, `value`, and optional `category`, `priority`, `type`, and localized values
* `measurementUnitKey`: Unit of measure
* `warranty`: Warranty details with `warrantyStartDate` and `warrantyPeriod` (ISO 8601 duration, for example, `P2Y` for 2 years)
* `returnPolicy`: Return details with `isReturnable` flag and `returnWindowEndDate`
* `customAttributes`: Free-form attributes
### Monetary values
All monetary values use the `MonetaryValue` format:
```json
{
"value": 7499,
"currency": "EUR",
"decimalPlaces": 2
}
```
`value`: Amount in the smallest currency unit (for example, cents)
`currency`: ISO 4217 currency code
`decimalPlaces`: Number of decimal places (defaults to currency standard)
### System-generated fields
These fields are automatically set and returned in the response:
* `id`: Unique identifier for the order record
* `version`: Version number for optimistic locking
* `created`: Timestamp when the record was created
* `lastModified`: Timestamp of the last modification
* `anonymized`: Whether PII has been anonymized (GDPR)
* `gdprCleanupDate`: When anonymization will occur
* `deletionDate`: When the record will be permanently deleted
* `pricing.priceBreakdown`: Calculated totals including `subTotal`, `totalDiscounts`, `totalTaxes`, `totalFees`, `totalDeposit`, and `total`
## List order records
To retrieve a paginated list of order records, call the following `GET` endpoint:
```http
GET https://{projectId}.api.fulfillmenttools.com/api/orderrecords
```
### Query parameters
* `size` (optional): Number of items per page, maximum 500, default 20
* `startAfterId` (optional): Cursor for keyset pagination — pass the `id` of the last record from the previous page
* `facilityRef` (optional): Filter by facility reference
* `tenantOrderRecordId` (optional): Filter by your external order record ID
### Example: List with filtering
```http
GET https://{projectId}.api.fulfillmenttools.com/api/orderrecords?facilityRef=22675b17-04d3-40eb-8970-5a5a382b4a76&size=50
```
## Get a single order record
To retrieve a specific order record by its ID:
```http
GET https://{projectId}.api.fulfillmenttools.com/api/orderrecords/{orderRecordId}
```
Returns the full order record object or a `404 Not Found` if the record doesn't exist.
## Authorization
Order record operations require the following permissions:
* `ORDER_RECORD_READ`: Required for listing and retrieving order records
* `ORDER_RECORD_WRITE`: Required for creating order records
See the [Authorization article](/documentation/getting-started/authentication-and-authorization.md) for more information.
## GDPR and data retention
Order records support automatic GDPR compliance:
* **Anonymization**: PII is automatically anonymized based on the configured GDPR cleanup schedule
* **Deletion**: Records are permanently deleted after the configured retention period
* The `anonymized`, `gdprCleanupDate`, and `deletionDate` fields track the GDPR lifecycle
See the [GDPR configuration](/documentation/by-pillar/order-management/gdpr-configuration.md) for more details.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/order-management/order-records.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.