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, 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:

PUT https://{projectId}.api.fulfillmenttools.com/api/orderrecords

{
  "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": "[email protected]",
        "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"
      }
    }
  ]
}

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
      }
    }
  ]
}

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:

{
  "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:

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

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:

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 for more information.

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 for more details.

Last updated 1 month ago