Create Receipts
This section focuses on:
- Structure of POST requests to the /receipts endpoint
- Send receipt data to 7shifts
Creating sales data in 7shifts is handled through a POST
request to the 7shifts /receipts
endpoint.
Request URL
curl --request POST --url 'https://api.7shifts.com/v2/company/12345/receipts'
An example POST
request to the /receipts
endpoint to create a sales receipt looks as follows:
Request body
{
"receipt": {
"receipt_id": "rec_98765",
"location_id": 7890,
"receipt_date": "2021-12-01T10:00:15Z",
"net_total": 4399,
"status": "closed"
}
}
Here’s an explanation of each of the required fields required in the request body:
Parameter | Type | Description |
---|---|---|
receipt_id | string | ID of the sales receipt in your system (must be unique per 7shifts location) |
location_id | integer | 7shifts Location ID |
receipt_date | datetime | Receipt creation date/time. UTC in ISO8601 format. |
net_total | integer | The net total of the receipt pre tax, post-discounts, pre tips. In cents. |
status | string | Receipt status. Must be one of the following:open closed voided deleted |
Send receipts to 7shifts
Receipts need to be created in 7shifts as soon as they are opened in your system in order to ensure consistency between the two platforms.
As a result, as soon as a receipt is opened in your system, you will need to make a POST
request to 7shifts' /receipts
endpoint in your system following the request structure described above.
Expanded Receipt Support
7shifts supports optional receipt information including gross totals, discounts, tips, revenue centers, line items and tip details. Sending the expanded receipt information as part of the sales integration may unlock additional 7shifts features such as tip pooling. Please contact [email protected] to learn more about how to become a tip pool enabled POS.
The following fields are all optional:
Parameter | Type | Description |
---|---|---|
gross_total | integer | The gross total for the receipt. In cents. |
total_receipt_discounts | integer | The total discount of the receipts. In cents |
tips | integer | The total tips. In cents |
external_user_id | integer | ID of the user in your system who created the receipt. |
revenue_center | string | The revenue center |
order_type | string | The order type. Must be one of the following:dine_in delivery take_out |
dining_option | string | The dining option |
receipt_lines | array | Array of receipt_lines |
tip_details | array | Array of tip_details |
Example request body
{
"receipt_id": "rec_98765",
"location_id": 7890,
"receipt_date": "2022-05-01T13:36:52Z",
"net_total": 5990,
"gross_total": 7150,
"total_receipt_discounts": 1160,
"tips": 1160,
"external_user_id": "a4355",
"revenue_center": "828d",
"order_type": "dine_in",
"status": "closed",
"dining_option": "fbe1b33f0b11"
}
receipt_lines
If your POS supports line item details you can add an array of line_items
to the receipt payload.
Parameter | Type | Required | Description |
---|---|---|---|
external_item_id | string | Yes | ID of the item in your system. |
external_category_ids | array of strings | Yes | Array of ID's of the categories in your system. |
quantity | integer | Yes | The quantity of the item |
price | integer | Yes | The item price. In cents. |
gross_item_prices | integer | Yes | The item gross price. In cents. |
net_item_price | integer | Yes | The item net price pre tax, post-discount, pre tips. In cents |
item_discount | integer | Yes | The item discount. In cents |
status | integer | Yes | The item status. Must be one of the following:open closed voided deleted |
created | datetime | No | Item creation date/time. UTC in ISO8601 format |
tip_details
If your POS supports tip details details you can add an array of tip_details
to the receipt payload. When using tips_details ensure the sum of the values of tip_details
matches the tips
parameter. Each parameter is required in the payload.
Parameter | Type | Description |
---|---|---|
type | string | The tip type. Must be one of the following:cc cash declared net total gratuity |
value | integer | The tip value. In cents |
Example request body with receipt_lines
and tip_details
:
{
"receipt_id": "rec_98765",
"location_id": 7890,
"receipt_date": "2022-05-01T13:36:52Z",
"net_total": 5990,
"gross_total": 7150,
"total_receipt_discounts": 1160,
"tips": 1160,
"external_user_id": "a4355",
"revenue_center": "828d",
"order_type": "DINE_IN",
"status": "closed",
"dining_option": "fbe1b33f0b11",
"receipt_lines": [
{
"external_category_ids": [
"02a7-41b3"
],
"external_item_id": "fa6e064bc2e2",
"quantity": 5,
"price": 430,
"gross_item_price": 600,
"net_item_price": 430,
"item_discount": 0,
"status": "closed",
"created": "2022-05-01T13:36:55Z"
},
{
"external_item_id": "c9b91da6648a",
"quantity": 10,
"price": 3900,
"gross_item_price": 4655,
"net_item_price": 3900,
"item_discount": 0,
"status": "closed",
"created": "2022-05-01T13:36:55Z"
}
],
"tip_details": [
{
"type": "total",
"value": 1160
},
{
"type": "gratuity",
"value": 0
}
]
}
Errors
If an error message is returned stating "Duplicate receipt for this date/time" when trying to create a sales receipt, it could be because of one of the following scenarios:
- The
receipt_id
specified is the same as another receipt for the same location. - The
receipt_date
specified has the exact same date, hour, minute & second as an existing receipt at the same location:- This error will only be seen at high-volume restaurant locations where multiple receipts are being opened in the same second.
- If you face such an error, increment the second in the
receipt_date
by 1 and retry. - Have a 10-times retry limit in place so that the action doesn’t result in a deadlock.
- If a
receipt_date
still can't be found within a 10 second window, then grouping the two receipts together, sum up theirnet_total
field values, and send them as one receipt. - Please bear in mind that updating such receipts would be tricky in the future, as one such 7shifts receipt would represent two or more receipts from your system.
Updated about 2 years ago