POST basket · POS API
POST basket
POST
/baskets/{basketId}?consumerIdentToken={token1}&giftCardId={token2}A basket is the content of an invoice and is the basis for most menio functions. The result of this call always includes the possible 'rewards' for the products contained in the basket. These calculated 'rewards' are a preliminary result and must be marked as 'granted' by your software, as soon as the invoice amount has been paid in full for the Rewards to take effect and reported to the consumer as having been redeemed (see POST baskets/{basketId}/grant)
If a consumerIdentToken or a giftCardId was specified with the call, the response can also contain information about potentially available credit either on the consumer profile or on the gift card
As long as a basket is not 'granted', it can be updated as often as you like by calling this resource again, e.g. because another item was added or deleted without further ado (a frequent case in the catering trade). Each new call will trigger and deliver a new calculation of the rewards.
Parameters in request body
Since the meaning of most properties should be clear from the name, here are just a few explanations of the properties that require explanation.
| Name | Description |
|---|---|
Timestamp |
DateTime : required - here you should enter the time of billing in ISO8601 format including time zone. Example: 2015-04-30T08:45:15+02:00 for 08:45:15 on April 30, 2015 in Berlin (CEST - daylight saving time) |
HasDiscounts |
bool : required - if true is specified here, no reward calculation will take place in the menio system for this basket |
CurrencyISO |
string : optional - Enter the currency in which billing will be performed as a 3-character abbreviation according to ISO 4217 |
WaiterName |
string : optional - here should be the name of the operator/cashier who has significantly serviced/advised the customer |
BillPdf |
Byte-Array : optional - In order to be able to offer the features of the digital receipt to consumers without a smartphone, your software can send us a copy of the invoice as a PDF file, so that we can display it on the menio Consumer Portal on the one hand, but also send it directly to the consumer via email. To do this, send the contents of the PDF file as a base64-encoded byte array here |
ContextIdentifiers |
String-Array : optional - If Coupon-Identifiers or a Profile-Identifier have been added to the basket (see Context-Identifiers), then they should be specified here |
RegularGrossPrice |
double : optional - here the normal selling price for the article should be given |
CurrentGrossPrice |
double : optional - here should be the price under which this item is sold in this invoice, e.g. if any discounts (promotions, employee discounts etc.) have been applied to this item. |
PositionId |
int - enter a unique number here, which makes the position referenceable This is required to reference any discount calculated by our system to the item that triggers the inh. |
ProductId |
string : optional - enter here the PLU of the product under which the product was submitted to our system so that we can correctly recognize it for the calculation of the product-based rewards. If you have not implemented support for product-based rewards in your software, you can omit this field |
OrderTime |
DateTime : optional - in the catering trade it is often the case that an invoice is open for a long period of time and items are posted one by one. If this is also the case for you, enter the exact booking time of the respective position here in ISO8601 format (incl. time zone). This will allow us to calculate so called "Happy Hour" rewards on a position exactly. Example: 2015-04-30T08:45:15+02:00 for 08:45:15 on April 30, 2015 in Berlin (CEST - daylight saving time) |
Unit |
int - This is the unit of measure in Amount. 0 for quantity, 1 for kilogram. |
Amount |
decimal - Quantity of the article. Can be specified as number of pieces or kilograms (see Unit). |
ProductProps |
dictionary[string, string] : optional - If your products have special features that should be displayed in a structured way on the digital receipt, this list of key-value pairs is exactly the right place for these features |
Response
The response body contains a list of the price reductions (rewards) and loyalty points applicable to the submitted basket. The rewards list will be empty, if no reward is applicable. Otherwise, it is a list of items, each of which represents one Reward per item or refers to the total invoice amount. If a Reward was triggered by a combination of articles, this Reward will be split proportionally among all articles triggering it for tax purposes. Each Reward entry has a reference to the position of the basket to which it is assigned. It is now the task of the cash desk to incorporate these price reductions into the invoice in a correct accounting manner. The calculated Reward amount is always based on the gross price of the respective position in the basket. Each object has the following properties:
| Name | Description |
|---|---|
RewardType |
int: 1 = Reward on product. 2 = Reward on total invoice amount. With 1, the 'ProductId' is assigned the PLU of the product for which this reward was determined. With 2 the field 'ProductId' remains empty. |
ProductId |
string: the PLU of the article transmitted in the basket data record on which a reward could be determined |
GrossRewardValue |
decimal: this is the calculated value of the Reward based on the gross price of the respective position. |
RewardTriggeringPositionId |
int: PositionId of the position of the transmitted basket triggering the current reward. |
Name |
string: Name of the coupon in the menio system for documentation purposes. |
And here is an explanation of the properties of a LoyaltyInfo object:
| Name | Description |
|---|---|
Name |
string: Name of the loyalty point scheme in the menio system for documentation purposes. |
GrossRewardValue |
decimal: this is the calculated value of the Reward based on the gross price of the respective position. It is only set if PreviousPoints+NewPoints >= PointsInScheme is set. |
RewardTriggeringPositionId |
int: PositionId of the position of the transmitted basket triggering the current reward. |
Parameter
basketIdstringErforderlichA string that can be freely generated by your client, which uniquely identifies the basket. You can use the invoice number as 'basketId' here, for example.
ab12345token1stringIf the consumer has already identified himself at the POS, e.g. by showing a customer card in which the 'token' linked to his consumer profile is stored, this 'token' should be entered here.
member123token2stringIf the consumer had presented a gift card when making the purchase and this was recorded by your system, the ID stored in the card should be entered here
giftCardABCRequest-Header
Content-Typeapplication/jsonDevKey{Your Key}TrackingUnitId{trackingUnitId}Originaler Blueprint-Ausschnitt
API Blueprint
### POST basket [POST]
A basket is the content of an invoice and is the basis for most qnips functions.
The result of this call always includes the possible 'rewards' for the products contained in the basket.
These calculated 'rewards' are a preliminary result and must be marked as 'granted' by your software,
as soon as the invoice amount has been paid in full for the Rewards to take effect and reported to the consumer as having been redeemed
(see *[POST baskets/{basketId}/grant](#reference/baskets/rewards-als-granted-makieren/post-baskets%2F%7Bbasketid%7D%2Fgrant%3Fredeemedinpos%3D%7Bredeemedinpos%7D)*)
If a *consumerIdentToken* or a *giftCardId* was specified with the call, the response can also contain information about
potentially available credit either on the consumer profile or on the gift card
As long as a basket is not 'granted', it can be updated as often as you like by calling this resource again,
e.g. because another item was added or deleted without further ado (a frequent case in the catering trade).
Each new call will trigger and deliver a new calculation of the rewards.
#### Parameters in request body
Since the meaning of most properties should be clear from the name, here are just a few explanations of the properties that require explanation.
| Name | Description |
| --- | --- |
|`Timestamp`|**DateTime : required** - here you should enter the time of billing in *[ISO8601 format](http://de.wikipedia.org/wiki/ISO_8601)* including time zone. Example: 2015-04-30T08:45:15+02:00 for 08:45:15 on April 30, 2015 in Berlin (CEST - daylight saving time)|
|`HasDiscounts`|**bool : required** - if true is specified here, no reward calculation will take place in the qnips system for this basket|
|`CurrencyISO`|**string : optional** - Enter the currency in which billing will be performed as a 3-character abbreviation according to *[ISO 4217](http://de.wikipedia.org/wiki/ISO_4217)*|
|`WaiterName`|**string : optional** - here should be the name of the operator/cashier who has significantly serviced/advised the customer|
|`BillPdf`|**Byte-Array : optional** - In order to be able to offer the features of the digital receipt to consumers without a smartphone, your software can send us a copy of the invoice as a PDF file, so that we can display it on the qnips Consumer Portal on the one hand, but also send it directly to the consumer via email. To do this, send the contents of the PDF file as a base64-encoded byte array here|
|`ContextIdentifiers`|**String-Array : optional** - If Coupon-Identifiers or a Profile-Identifier have been added to the basket (see *[Context-Identifiers](https://qnipsapi1draft.docs.apiary.io/#reference/contextidentifiers)*), then they should be specified here |
|`RegularGrossPrice`|**double : optional** - here the normal selling price for the article should be given|
|`CurrentGrossPrice`|**double : optional** - here should be the price under which this item is sold in this invoice, e.g. if any discounts (promotions, employee discounts etc.) have been applied to this item.
|`PositionId`|**int** - enter a unique number here, which makes the position referenceable This is required to reference any discount calculated by our system to the item that triggers the inh. |
|`ProductId`|**string : optional** - enter here the PLU of the product under which the product was submitted to our system so that we can correctly recognize it for the calculation of the product-based rewards. If you have not implemented support for product-based rewards in your software, you can omit this field|
|`OrderTime`|**DateTime : optional** - in the catering trade it is often the case that an invoice is open for a long period of time and items are posted one by one. If this is also the case for you, enter the exact booking time of the respective position here in *[ISO8601 format](http://de.wikipedia.org/wiki/ISO_8601)* (incl. time zone). This will allow us to calculate so called "Happy Hour" rewards on a position exactly. Example: 2015-04-30T08:45:15+02:00 for 08:45:15 on April 30, 2015 in Berlin (CEST - daylight saving time)|
|`Unit`|**int** - This is the unit of measure in Amount. 0 for quantity, 1 for kilogram. |
|`Amount`|**decimal** - Quantity of the article. Can be specified as number of pieces or kilograms (see Unit). |
|`ProductProps`|**dictionary[string, string] : optional** - If your products have special features that should be displayed in a structured way on the digital receipt, this list of key-value pairs is exactly the right place for these features|
#### Response
The response body contains a list of the price reductions (rewards) and loyalty points applicable to the submitted basket. The rewards list will be empty,
if no reward is applicable. Otherwise, it is a list of items, each of which represents one Reward per item or refers to the total invoice amount.
If a Reward was triggered by a combination of articles, this Reward will be split proportionally among all articles triggering it for tax purposes. Each Reward entry has a reference to the position of the basket to which it is assigned.
It is now the task of the cash desk to incorporate these price reductions into the invoice in a correct accounting manner. The calculated Reward amount is always based on the gross price of the respective position in the basket.
Each object has the following properties:
| Name | Description |
| --- | --- |
|`RewardType`|**int**: 1 = Reward on product. 2 = Reward on total invoice amount. With 1, the 'ProductId' is assigned the PLU of the product for which this reward was determined. With 2 the field 'ProductId' remains empty.
|`ProductId`|**string**: the PLU of the article transmitted in the basket data record on which a reward could be determined
|`GrossRewardValue`|**decimal**: this is the calculated value of the Reward based on the gross price of the respective position. |
|`RewardTriggeringPositionId`|**int**: PositionId of the position of the transmitted basket triggering the current reward.
|||||| CouponId|||**int**: Id of the coupon in the qnips system for documentation purposes.
|`Name`|**string**: Name of the coupon in the qnips system for documentation purposes.|
And here is an explanation of the properties of a LoyaltyInfo object:
| Name | Description |
| --- | --- |
||||| LoyaltyId|||**int**: Id of the loyalty point scheme in the qnips system for documentation purposes.
|`Name`|**string**: Name of the loyalty point scheme in the qnips system for documentation purposes.
|| || PointsInScheme|||**int**: Number of points that must be collected in order for a reward to be issued.
|| || PreviousPoints|||**int**: Number of points before the current purchase|
|| ||NewPoints||||int**: Number of new points generated with this purchase|
|`GrossRewardValue`|**decimal**: this is the calculated value of the Reward based on the gross price of the respective position. It is only set if PreviousPoints+NewPoints >= PointsInScheme is set.
|`RewardTriggeringPositionId`|**int**: PositionId of the position of the transmitted basket triggering the current reward.
+ Parameters
+ basketId (string, `ab12345`) ... A string that can be freely generated by your client, which uniquely identifies the basket. You can use the invoice number as 'basketId' here, for example.
+ token1 (optional, string, `member123`) ... If the consumer has already identified himself at the POS, e.g. by showing a customer card in which the 'token' linked to his consumer profile is stored, this 'token' should be entered here.
+ token2 (optional, string, `giftCardABC`) ... If the consumer had presented a gift card when making the purchase and this was recorded by your system, the ID stored in the card should be entered here
+ Request
+ Headers
Content-Type: application/json
DevKey: {Your Key}
TrackingUnitId: {trackingUnitId}
+ Body
{
"BillNumber": "1234."
"Timestamp": "2015-04-21T08:15:45,000+02:00"
"TotalValue":159.90,
"HasDiscounts":false,
"TableId": "123."
"WaiterName": "Max Mustermann",
"CurrencyISO": "EUR",
"Positions": [
{
"PositionId":1,
"ProductId": "20019",
"ProductName": "Coffee Large",
"Amount":1,
"Unit":0,
"HasDiscounts":false,
"CurrentGrossPrice":2.39,
"RegularGrossPrice":2.39,
"VatInPercent":19.0,
"OrderTime": "2015-04-21T08:15:45,000+02:00"
"ImageUrl": "http://abc.de/xyz"
"ProductProps":{
"Bean": "100% Arabica."
"Milk": "soya"
}
},
{
"PositionId":2,
"ProductId": "151"
"ProductName": "Vanilla Donut."
"Amount":1,
"Unit":0,
"HasDiscounts":false,
"CurrentGrossPrice":1.79,
"RegularGrossPrice":1.79
"VatInPercent":19.0,
"OrderTime": "2015-04-21T08:15:45,000+02:00"
}
],
"BillPdf": "98761238467129803470987809123489798172435980728347578091873645786..."
}
+ response 200
+ Headers
Content-Type: application/json
+ Body
{
"Rewards":[
{
"ProductId": "20019",
"Name": "30% off large coffee drink and a donut",
"GrossRewardValue": 0.72,
"CouponId": 683,
"RewardTriggeringPositionId": 1,
"RewardType": 1
},
{
"ProductId": "151"
"Name": "30% off large coffee drink and a donut",
"GrossRewardValue": 0.53,
"CouponId": 683,
"RewardTriggeringPositionId": 2,
"RewardType": 1
}
],
"LoyaltyInfo": [
{
"Name": "One point for each hot beverage."
"LoyaltyId": 171,
"Details": [
{
"PreviousPoints": 7,
"NewPoints": 2,
"PointsInScheme": 10,
"GrossRewardValue": 0,
"RewardTriggeringPositionId": 1
}
]
}
]
}
+ response 500
// HTTP-InternalServerError: An unknown problem occurred during processing
+ Response 401
// HTTP-Unauthorized: DevKey or trackingUnitId not specified or not available
+ response 403
// HTTP-Forbidden: trackingUnitId is not yet activated by the merchant
+ response 400
{
"ErrorId":123,
"ErrorText": "Details of the error"
}
// here all possible error codes incl. texts for this resource
// 1000: Body contains syntactical errors and cannot be deserialized
// 11004: consumerIdentToken not found Repeat if necessary without this token
// 11005: consumerIdentToken locked. Repeat if necessary without this token
// 11006: consumerIdentToken expired. Repeat if necessary without this token
// 11007: giftCardId not found. Repeat if necessary without this token
// 11008: giftCardId locked. Repeat if necessary without this token
// 11009: giftCardId expired. Repeat if necessary without this token
// 11010: this basket is 'granted' and therefore not changeable