POST · Checkout API
POST
POST
/api/v1/ordersCreates a new order.
totalGrossis used to validate the calculated value in the API, ensuring the client displayed the correct price to the customer.
Request-Header
Content-Typeapplication/json; charset=utf-8AuthorizationToken <accessToken>Idempotency-Key<idempotencyKey>Security-Token<securityToken>Timestamp<timestamp>Kontext: Baskets & Orders
A basket may be submitted without a profileReference, but an order requires one.
We recommend adding a profileReference to the request body as early as possible to ensure the API can provide a personalized evaluation response.
[Coming soon] Component configuration.
Originaler Blueprint-Ausschnitt
API Blueprint
### POST [POST]
Creates a new order.
+ `totalGross` is used to validate the calculated value in the API, ensuring the client displayed the correct price to the customer.
+ Request (application/json; charset=utf-8)
+ Headers
Authorization: Token <accessToken>
Idempotency-Key: <idempotencyKey>
Security-Token: <securityToken>
Timestamp: <timestamp>
+ Attributes (object)
+ startTimestamp: `2025-11-18T18:40:45Z` (string) - The basket creation date and time in UTC.
+ endTimestamp: `2025-11-18T18:41:12Z` (string) - The basket last updated date and time in UTC.
+ orderTimestamp: `2025-11-18T18:41:12Z` (string, required) - The date and time used for the order in UTC.
+ basketId: `c926d56f-f071-4511-a959-513099a9ff78` (string, required) - The unique identifier of the basket generated by the client.
+ profileReference: `BRBZU5RRXEVXGKHLBZR6` (string, required) - The unique token identifier or an OTP of the profile.
+ menuId: 514717 (number, required) - The unique identifier of the menu card.
+ checkInIds (array) - The check-ins associated with the order.
+ Members
+ `89644` (number) - The unique identifiers of check-in.
+ positions (array, required) - The items to be processed.
+ (object)
+ positionId: 0 (number, required) - A number used to reference a specific position within the basket.
+ productPlu: `QNI-1757944121588` (string, required) - The PLU of the product, which has to be unique.
+ quantity: 2 (number, required) - The quantity of the product.
+ consumptionMode: `Takeaway` (string, required) - The type of consumption.
+ totalGross: 990 (number, required) - The total gross amount (including VAT) for the basket in the currency's minor unit.
+ currency: EUR (string, required) - The currency of the basket.
+ balance (object) - Contains balance charge information.
+ requestCharge: true (boolean, required) - Request for the order to be paid with balance.
+ reservation (object) - Contains balance reservation information. Include to perform the balance charge against reserved balance.
+ reference: `f032f960-9b87-43eb-b434-48a65d7d3efe` (string, required) - The reference of the reservation that will be charged.
+ cancelRemainingAmount: true (boolean) - Cancel the reservation after payment, causing any leftover reserved balance to become freely available again without waiting for the reservation to time out.
+ Body
{
"startTimestamp": "2025-11-18T18:40:45Z",
"endTimestamp": "2025-11-18T18:41:12Z",
"orderTimestamp": "2025-11-18T18:41:12Z",
"profileReference": "BRBZU5RRXEVXGKHLBZR6",
"basketId": "c926d56f-f071-4511-a959-513099a9ff78",
"menuId": 514717,
"checkInIds": [
89644
],
"positions": [
{
"positionId": 0,
"productPlu": "QNI-1757944121588",
"quantity": 2
}
],
"consumptionMode": "Takeaway",
"totalGross": 990,
"currency": "EUR",
"balance": {
"requestCharge": true,
"reservation": {
"reference": "f032f960-9b87-43eb-b434-48a65d7d3efe",
"cancelRemainingAmount": true
}
}
}
+ Schema
{
"type": "object",
"properties": {
"startTimestamp": {
"type": "string",
"format": "date-time"
},
"endTimestamp": {
"type": "string",
"format": "date-time"
},
"orderTimestamp": {
"type": "string",
"format": "date-time"
},
"basketId": {
"type": "string",
"format": "uuid"
},
"profileReference": {
"type": "string"
},
"menuId": {
"type": "number"
},
"checkInIds": {
"type": "array",
"items": {
"type": "number"
}
},
"positions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"positionId": {
"type": "number"
},
"productPlu": {
"type": "string"
},
"quantity": {
"type": "number"
}
}
}
},
"consumptionMode": {
"oneOf": [
{
"type": "string",
"enum": ["OnPremise", "Takeaway"]
},
{
"type": "integer",
"minimum": 0,
"maximum": 1
}
]
},
"totalGross": {
"type": "number"
},
"currency": {
"type": "string"
},
"balance": {
"type": "object",
"properties": {
"requestCharge": {
"type": "boolean"
},
"reservation": {
"type": "object",
"properties": {
"reference": {
"type": "string",
"format": "uuid"
},
"cancelRemainingAmount": {
"type": "boolean"
}
}
}
}
}
}
}
+ Response 200 (application/json; charset=utf-8)
+ Attributes (object)
+ startTimestamp: `2025-11-18T18:40:45Z` (string) - The basket creation date and time in UTC.
+ endTimestamp: `2025-11-18T18:41:12Z` (string) - The basket last updated date and time in UTC.
+ orderTimestamp: `2025-11-18T18:41:12Z` (string, required) - The date and time used for the order in UTC.
+ basketId: `c926d56f-f071-4511-a959-513099a9ff78` (string, required) - The unique identifier of the basket generated by the client.
+ profileReference: `BRBZU5RRXEVXGKHLBZR6` (string, required) - The unique token identifier or an OTP of the profile.
+ menuId: 514717 (number, required) - The unique identifier of the menu card.
+ positions (array, required) - The items to be processed.
+ (object)
+ positionId: 0 (number, required) - A number used to reference a specific position within the basket.
+ productPlu: `QNI-1757944121588` (string, required) - The PLU of the product, which has to be unique.
+ quantity: 2 (number, required) - The quantity of the product.
+ price: 495 (number, required) - The total basket value for this position in the currency's minor unit.
+ vat (object, required) - An object containing VAT information for this position.
+ rate: 7 (number) - The VAT rate (in percent) applied to this position.
+ gross: 990 (number) - The gross amount (including VAT) for this position in the currency's minor unit.
+ net: 925 (number) - The net amount (excluding VAT) for this position in the currency's minor unit.
+ taxAmount: 65 (number) - The VAT amount calculated for this position in the currency's minor unit.
+ consumptionMode: `Takeaway` (string, required) - The type of consumption.
+ receiptUrl: `https://sandbox.cateringportal.io/.../c926d56f-f071-4511-a959-513099a9ff78` (string) - The URL for retrieving a digital receipt.
+ totalGross: 990 (number, required) - The total gross amount (including VAT) for the basket in the currency's minor unit.
+ currency: EUR (string, required) - The currency of the basket.
+ vats (array, required)
+ (object)
+ rate: 7 (number) - The VAT rate (in percent) applied to the basket.
+ gross: 990 (number) - The gross amount (including VAT) for the basket in the currency's minor unit.
+ net: 925 (number) - The net amount (excluding VAT) for the basket in the currency's minor unit.
+ taxAmount: 65 (number) - The VAT amount calculated for the basket in the currency's minor unit.
+ balance (object)
+ oldAmount: 1000 (number) - The old amount before paying the order with balance, expressed in the currency's minor unit.
+ newAmount: 10 (number) - The new amount after paying the order with balance, expressed in the currency's minor unit.
+ currency: `EUR` (string) - The currency of the transaction.
+ reservation (object)
+ oldAmountExcludingReservation: 0 (number) - The profile's balance prior to the transaction, factoring out the reservation that is used for the charge, expressed in the currency's minor unit.
+ newAmountExcludingReservation: 10 (number) - The profile's balance after the transaction, factoring out the potentially remaining amount of the used reservation, expressed in the currency's minor unit.
+ reservedAmountRemaining: 0 (number) - The remaining amount of the reservation, expressed in the currency's minor unit.
+ reservedAmountUsed: 990 (number) - The amount of the reservation used by the transaction, expressed in the currency's minor unit.
+ unreservedAmountUsed: 0 (number) - The amount of unreserved profile balance used by the transaction in case the reserved amount was insufficient to cover the whole transaction, expressed in the currency's minor unit.
+ Body
{
"startTimestamp": "2025-11-18T18:40:45Z",
"endTimestamp": "2025-11-18T18:41:12Z",
"orderTimestamp": "2025-11-18T18:41:12Z",
"basketId": "c926d56f-f071-4511-a959-513099a9ff78",
"profileReference": "BRBZU5RRXEVXGKHLBZR6",
"menuId": 514717,
"positions": [
{
"positionId": 0,
"productPlu": "QNI-1757944121588",
"quantity": 2,
"price": 495,
"vat": {
"rate": 7,
"gross": 990,
"net": 925,
"taxAmount": 65
}
}
],
"consumptionMode": "Takeaway",
"receiptUrl": "https://sandbox.cateringportal.io/.../c926d56f-f071-4511-a959-513099a9ff78",
"totalGross": 990,
"currency": "EUR",
"vats": [
{
"rate": 7,
"gross": 990,
"net": 925,
"taxAmount": 65
}
],
"balance": {
"oldAmount": 1000,
"newAmount": 10,
"reservation": {
"oldAmountExcludingReservation": 0,
"newAmountExcludingReservation": 10,
"reservedAmountRemaining": 0,
"reservedAmountUsed": 990,
"unreservedAmountUsed": 0
}
}
}
+ Schema
{
"type": "object",
"properties": {
"startTimestamp": {
"type": "string",
"format": "date-time"
},
"endTimestamp": {
"type": "string",
"format": "date-time"
},
"orderTimestamp": {
"type": "string",
"format": "date-time"
},
"basketId": {
"type": "string",
"format": "uuid"
},
"profileReference": {
"type": "string"
},
"menuId": {
"type": "number"
},
"positions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"positionPlu": {
"type": "string"
},
"productId": {
"type": "number"
},
"quantity": {
"type": "number"
},
"price": {
"type": "number"
},
"vat": {
"type": "object",
"properties": {
"rate": {
"type": "number"
},
"gross": {
"type": "number"
},
"net": {
"type": "number"
},
"taxAmount": {
"type": "number"
}
}
}
}
}
},
"consumptionMode": {
"oneOf": [
{
"type": "string",
"enum": ["OnPremise", "Takeaway"]
},
{
"type": "integer",
"minimum": 0,
"maximum": 1
}
]
},
"receiptUrl": {
"type": "string",
"type": "uri"
},
"totalGross": {
"type": "number"
},
"currency": {
"type": "string"
},
"vats": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rate": {
"type": "number"
},
"gross": {
"type": "number"
},
"net": {
"type": "number"
},
"taxAmount": {
"type": "number"
}
}
}
},
"balance": {
"type": "object",
"properties": {
"oldAmount": {
"type": "number"
},
"newAmount": {
"type": "number"
},
"reservation": {
"type": "object",
"properties": {
"oldAmountExcludingReservation": {
"type": "number"
},
"newAmountExcludingReservation": {
"type": "number"
},
"reservedAmountRemaining": {
"type": "number"
},
"reservedAmountUsed": {
"type": "number"
},
"unreservedAmountUsed": {
"type": "number"
}
}
}
}
}
}
}