Restaurant ordering systems and the myDATA API: every JSON example, from the order note to the card refund
Ten moments of a shift, ten complete request bodies for POST /invoices: the order note, the receipt that settles the notes, counter and take-away, the card on the terminal and at the door, mixed payment, cancellation, refund to the card, a treat on the house and a staff meal.
In one shift a restaurant ordering system issues ten different things: order notes at the table, receipts at the counter, card payments on the terminal, refunds, treats on the house. This page has all of them, in order, as complete JSON you send to POST /invoices.
Every example is a complete request body. Swap the ids for your own and send it. When each one is needed is explained in the guide to restaurant ordering systems and myDATA.
| Moment | Document |
|---|---|
| 1. Order at the table | 8.6 |
| 2. Paying the table | 11.1 |
| 3. Counter and take-away | 11.1 |
| 4. Card on the terminal | 11.1 |
| 5. Card at the door or on pick-up | 11.1 |
| 6. Cash and card on one bill | 11.1 and 8.4 |
| 7. Cancelling a receipt | 11.4 |
| 8. Refund to the card | 8.5 |
| 9. Treat on the house | 11.1 |
| 10. Staff meal | 6.1 |
Before you start
- Billing books: every type needs its own book. Take the
billing_book_idfromGET /billing_books. The test account comes with the main books set up, and any missing ones, such as 8.4 or 6.1, you create withPOST /billing_books. - Terminal:
pos_device_idis the id of the terminal as registered in Wrapp, fromGET /pos_devices. - Explicit amounts everywhere: every line carries its own
net_total_price,vat_totalandsubtotal, and the document its four totals. They are not computed from quantity and price. - Classifications: the revenue classifications in the examples are illustrative. Which one applies to the business is its accountant's call.
- A unique
external_id: put your order number in it and a repeat of the same call is refused instead of issuing a second document.
1. Order at the table: Catering Order Note 8.6
One note per round, on its table: catering_table_id is an open table from catering_tables. The note's lines take category1_95 with _, because the note classifies no revenue.
{
"invoice_type_code": "8.6",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"catering_table_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"counterpart": {
"name": "Τραπέζι 12",
"vat": "",
"city": "",
"street": "",
"number": "",
"postal_code": ""
},
"net_total_amount": 19.11,
"vat_total_amount": 2.99,
"total_amount": 22.10,
"payable_total_amount": 22.10,
"invoice_lines": [
{
"line_number": 1,
"name": "Μπριάμ",
"quantity": 2,
"quantity_type": 1,
"unit_price": 8.85,
"net_total_price": 17.70,
"vat_rate": 13,
"vat_total": 2.30,
"subtotal": 20.00,
"classification_category": "category1_95",
"classification_type": "_"
},
{
"line_number": 2,
"name": "Νερό 1lt",
"quantity": 1,
"quantity_type": 1,
"unit_price": 1.41,
"net_total_price": 1.41,
"vat_rate": 24,
"vat_total": 0.69,
"subtotal": 2.10,
"classification_category": "category1_95",
"classification_type": "_"
}
]
}
The note has 24 hours to be correlated with the receipt that settles it. Its lifecycle, cancellation and errors are covered in the guide to the Catering Order Note and the 24-hour rule.
2. Paying the table: an 11.1 receipt that settles the notes
Table 12 ordered two rounds of €22.10. The €44.20 receipt carries the ΜΑΡΚ of both notes in correlated_invoices, and the table in catering_table_id. If the bill is split across several receipts, the conservative implementation puts the note's ΜΑΡΚ on each.
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"correlated_invoices": ["400001xxxxxxxx1", "400001xxxxxxxx2"],
"catering_table_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 0,
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"invoice_lines": [
{
"line_number": 1,
"name": "Μπριάμ",
"quantity": 4,
"quantity_type": 1,
"unit_price": 8.85,
"net_total_price": 35.40,
"vat_rate": 13,
"vat_total": 4.60,
"subtotal": 40.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Νερό 1lt",
"quantity": 2,
"quantity_type": 1,
"unit_price": 1.41,
"net_total_price": 2.82,
"vat_rate": 24,
"vat_total": 1.38,
"subtotal": 4.20,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 38.22,
"vat_total_amount": 5.98,
"total_amount": 44.20,
"payable_total_amount": 44.20
}
The table does not close by itself. After the last receipt, you close it:
curl -X POST 'https://wrapp.ai/api/v1/catering_tables/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/close' \ -H 'Authorization: Bearer xxxxxxxxxxxxxx'
3. Counter and take-away: a direct 11.1 receipt
When the guest pays at the moment of ordering, at the counter, for take-away or delivery, the receipt goes out directly: no order note and no table.
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 0,
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"invoice_lines": [
{
"line_number": 1,
"name": "Γύρος χοιρινός μερίδα",
"quantity": 2,
"quantity_type": 1,
"unit_price": 10.62,
"net_total_price": 21.24,
"vat_rate": 13,
"vat_total": 2.76,
"subtotal": 24.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Αναψυκτικό 330ml",
"quantity": 2,
"quantity_type": 1,
"unit_price": 1.61,
"net_total_price": 3.22,
"vat_rate": 24,
"vat_total": 0.78,
"subtotal": 4.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 24.46,
"vat_total_amount": 3.54,
"total_amount": 28.00,
"payable_total_amount": 28.00
}
4. Card on the terminal: an 11.1 receipt with pos_device_id
With pos_device_id and payment_method_type: 3 the amount goes to the terminal. The response is pending and the receipt takes its ΜΑΡΚ once the payment is approved. The result arrives by webhook: the issued receipt on success, and a failure or cancellation on the terminal separately.
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 3,
"pos_device_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"external_id": "order-1042",
"invoice_lines": [
{
"line_number": 1,
"name": "Μπριάμ",
"quantity": 2,
"quantity_type": 1,
"unit_price": 8.85,
"net_total_price": 17.70,
"vat_rate": 13,
"vat_total": 2.30,
"subtotal": 20.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Νερό 1lt",
"quantity": 1,
"quantity_type": 1,
"unit_price": 1.41,
"net_total_price": 1.41,
"vat_rate": 24,
"vat_total": 0.69,
"subtotal": 2.10,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 19.11,
"vat_total_amount": 2.99,
"total_amount": 22.10,
"payable_total_amount": 22.10
}
The terminal has to be connected to Wrapp and registered on the account. On staging only Viva demo terminals work, as the guide to connecting Viva SoftPOS explains.
5. Card at the door or on pick-up: aade_preloaded
When the receipt has to exist before the guest pays, for delivery with the card at the door or payment on pick-up, add "aade_preloaded": true. The receipt is issued at once with its ΜΑΡΚ and the payment method "on credit", and the charge waits on the terminal.
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 3,
"pos_device_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"aade_preloaded": true,
"external_id": "order-1043",
"invoice_lines": [
{
"line_number": 1,
"name": "Μπριάμ",
"quantity": 2,
"quantity_type": 1,
"unit_price": 8.85,
"net_total_price": 17.70,
"vat_rate": 13,
"vat_total": 2.30,
"subtotal": 20.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Νερό 1lt",
"quantity": 1,
"quantity_type": 1,
"unit_price": 1.41,
"net_total_price": 1.41,
"vat_rate": 24,
"vat_total": 0.69,
"subtotal": 2.10,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 19.11,
"vat_total_amount": 2.99,
"total_amount": 22.10,
"payable_total_amount": 22.10
}
- Paid by card on that terminal: the payment method becomes card, with a new payment ΜΑΡΚ. No second webhook fires, so you read the card details with
GET /invoices/{id}. - Paid in cash: you cancel the charge on the terminal and the receipt stays "on credit". No credit note and no new receipt are needed.
6. Cash and card on one bill: 11.1 and 8.4
The API takes one payment method per document. The €44.20 bill is paid €20.00 in cash and €24.20 by card, in two calls. First the receipt for the full amount, "on credit":
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 1,
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"invoice_lines": [
{
"line_number": 1,
"name": "Μπριάμ",
"quantity": 4,
"quantity_type": 1,
"unit_price": 8.85,
"net_total_price": 35.40,
"vat_rate": 13,
"vat_total": 4.60,
"subtotal": 40.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Νερό 1lt",
"quantity": 2,
"quantity_type": 1,
"unit_price": 1.41,
"net_total_price": 2.82,
"vat_rate": 24,
"vat_total": 1.38,
"subtotal": 4.20,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 38.22,
"vat_total_amount": 5.98,
"total_amount": 44.20,
"payable_total_amount": 44.20
}
Then the POS Payment Receipt 8.4, for the card part only, with the receipt's ΜΑΡΚ in correlated_invoices. The terminal charges €24.20 and the 8.4 takes its ΜΑΡΚ once the payment is approved.
{
"invoice_type_code": "8.4",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"correlated_invoices": ["400001xxxxxxxx1"],
"payment_method_type": 3,
"pos_device_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"invoice_lines": [
{
"line_number": 1,
"name": "Είσπραξη με κάρτα",
"quantity": 1,
"quantity_type": 1,
"unit_price": 24.20,
"net_total_price": 24.20,
"vat_rate": 0,
"vat_total": 0.00,
"subtotal": 24.20,
"classification_category": "category1_95",
"classification_type": "_",
"vat_exemption_code": "0"
}
],
"net_total_amount": 24.20,
"vat_total_amount": 0.00,
"total_amount": 24.20,
"payable_total_amount": 24.20
}
The cash part needs no further document. If the receipt settles order notes, it carries their ΜΑΡΚ too, as in step 2.
7. Cancelling a receipt: retail credit note 11.4
A receipt that took a ΜΑΡΚ does not change. You reverse it with an 11.4 on its own book, with the same lines, the same payment method and the original's ΜΑΡΚ in correlated_invoices.
{
"invoice_type_code": "11.4",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 0,
"correlated_invoices": ["400001xxxxxxxx1"],
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"invoice_lines": [
{
"line_number": 1,
"name": "Γύρος χοιρινός μερίδα",
"quantity": 2,
"quantity_type": 1,
"unit_price": 10.62,
"net_total_price": 21.24,
"vat_rate": 13,
"vat_total": 2.76,
"subtotal": 24.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Αναψυκτικό 330ml",
"quantity": 2,
"quantity_type": 1,
"unit_price": 1.61,
"net_total_price": 3.22,
"vat_rate": 24,
"vat_total": 0.78,
"subtotal": 4.00,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
}
],
"net_total_amount": 24.46,
"vat_total_amount": 3.54,
"total_amount": 28.00,
"payable_total_amount": 28.00
}
8. Refund to the card: POS Refund Receipt 8.5
The money goes back to the card from the terminal. refund_invoice_id is the Wrapp id of the document that charged the card, here the 8.4 from step 6, not a ΜΑΡΚ. The 8.5's amount is the amount refunded, so one 8.4 also takes partial refunds.
{
"invoice_type_code": "8.5",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 3,
"pos_device_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"refund_invoice_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"counterpart": {
"name": "Retail customer",
"country_code": "GR"
},
"net_total_amount": 5.00,
"vat_total_amount": 0.00,
"total_amount": 5.00,
"payable_total_amount": 5.00,
"invoice_lines": [
{
"line_number": 1,
"name": "Επιστροφή στην κάρτα",
"quantity": 1,
"quantity_type": 1,
"unit_price": 5.00,
"net_total_price": 5.00,
"vat_rate": 0,
"vat_total": 0.00,
"subtotal": 5.00,
"classification_category": "category1_95",
"classification_type": "_",
"vat_exemption_code": "0"
}
]
}
- The 8.5 is issued once the terminal completes the refund.
- Reversing the sale is a separate 11.4 with no terminal, as in step 7.
- If the 11.1 itself charged the card, steps 4 and 5, one 11.4 with
pos_device_id,refund_invoice_idset to the 11.1's id and its ΜΑΡΚ incorrelated_invoicesdoes both at once: it credits the sale and refunds the card.
9. Treat on the house: a zero-value line on the 11.1
The treated item goes on the receipt with the menu price in unit_price, zero amounts, category1_95 with _, and the item's real VAT rate.
{
"invoice_type_code": "11.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 0,
"net_total_amount": 10.00,
"vat_total_amount": 1.30,
"total_amount": 11.30,
"payable_total_amount": 11.30,
"invoice_lines": [
{
"line_number": 1,
"name": "Μπιφτέκι μερίδα",
"quantity": 1,
"quantity_type": 1,
"unit_price": 10.00,
"net_total_price": 10.00,
"vat_rate": 13,
"vat_total": 1.30,
"subtotal": 11.30,
"classification_category": "category1_1",
"classification_type": "E3_561_003"
},
{
"line_number": 2,
"name": "Πατάτες κέρασμα",
"quantity": 1,
"quantity_type": 1,
"unit_price": 3.50,
"net_total_price": 0.00,
"vat_rate": 13,
"vat_total": 0.00,
"subtotal": 0.00,
"classification_category": "category1_95",
"classification_type": "_"
}
]
}
On the 8.6 order note a zero-value line cannot sit beside priced lines: myDATA rejects the note with error 222. The treated item goes on its own all-zero note, or only on the receipt, as above.
A treat can also be issued as a 6.1, like the staff meal in the next step. Which of the two applies is the business's accountant's call.
10. Staff meal: self-supply document 6.1
On its own book, with category1_6 and E3_595, the payment method "on credit", and the reason in notes, which prints under the remarks. The counterpart is optional. The VAT base is the accountant's call.
{
"invoice_type_code": "6.1",
"billing_book_id": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"payment_method_type": 1,
"notes": "Αιτιολογία: γεύμα προσωπικού",
"net_total_amount": 2.00,
"vat_total_amount": 0.26,
"total_amount": 2.26,
"payable_total_amount": 2.26,
"invoice_lines": [
{
"line_number": 1,
"name": "Μερίδα μπιφτέκι",
"quantity": 1,
"quantity_type": 1,
"unit_price": 2.00,
"net_total_price": 2.00,
"vat_rate": 13,
"vat_total": 0.26,
"subtotal": 2.26,
"classification_category": "category1_6",
"classification_type": "E3_595"
}
]
}
How to start
Sign up free at wrapp.ai with your VAT number and press "Try the API". You get a login email and an API key for staging.wrapp.ai, and you can send every example on this page with no tax effect. Where to find the key is in the guide to your test API key, and every endpoint is in the API documentation.
Frequently asked questions
Which documents does a restaurant ordering system issue through the API?
The 8.6 Catering Order Note for every round at the table, the 11.1 retail receipt that settles the notes or is issued directly at the counter and for take-away, the 8.4 POS Payment Receipt for the card part of a mixed payment, the 8.5 POS Refund Receipt for a refund to the card, the 11.4 retail credit note for cancelling a receipt, and the 6.1 self-supply document. All of them go to the same endpoint, POST /invoices.
How does the receipt settle the order notes?
The 11.1 receipt carries the ΜΑΡΚ of every note on the table in correlated_invoices and the table in catering_table_id. The correlation has to happen within 24 hours of the note being issued.
Does the table close by itself after the receipt?
No. After the last receipt you close it, with POST /catering_tables/:id/close.
How do I send a bill paid half in cash and half by card?
In two calls, because the API takes one payment method per document. First the 11.1 receipt for the full amount with payment_method_type 1, on credit. Then an 8.4 for the card amount only, with pos_device_id, payment_method_type 3 and the receipt's ΜΑΡΚ in correlated_invoices. The cash part needs no further document.
How do I refund money to the card through the API?
With an 8.5 carrying pos_device_id and refund_invoice_id set to the Wrapp id of the document that charged the card, not a ΜΑΡΚ. The 8.5's amount is the amount refunded, so partial refunds work too. If the 11.1 itself charged the card, one 11.4 with pos_device_id and refund_invoice_id credits the sale and refunds the card together.
Can the receipt be issued before the guest pays by card?
Yes, with "aade_preloaded": true alongside pos_device_id. The 11.1 is issued at once with its ΜΑΡΚ and the payment method on credit, and the charge waits on the terminal. Paid by card, the payment method switches to card. Paid in cash, you cancel the charge on the terminal and the receipt stays on credit, with no further document.
How do I put a treat on the house on the receipt?
As a zero-value line: unit_price at the menu price, zero amounts, category1_95 with _, and the item's real VAT rate. A treat can also be issued as a 6.1. Which of the two applies is the business's accountant's call.
Where can I try the examples?
Need help?
If you have a question about this topic or want to make sure everything is set up correctly, contact us and we will look at it together.