These docs are for v2.2022.0501. Click to read the latest docs for v2.2023.0501.

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:

ParameterTypeDescription
receipt_idstringID of the sales receipt in your system (must be unique per 7shifts location)
location_idinteger7shifts Location ID
receipt_datedatetimeReceipt creation date/time. UTC in ISO8601 format.
net_totalintegerThe net total of the receipt pre tax, post-discounts, pre tips. In cents.
statusstringReceipt 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:

ParameterTypeDescription
gross_totalintegerThe gross total for the receipt. In cents.
total_receipt_discountsintegerThe total discount of the receipts. In cents
tipsintegerThe total tips. In cents
external_user_idintegerID of the user in your system who created the receipt.
revenue_centerstringThe revenue center
order_typestringThe order type. Must be one of the following:
dine_in
delivery
take_out
dining_optionstringThe dining option
receipt_linesarrayArray of receipt_lines
tip_detailsarrayArray 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.

ParameterTypeRequiredDescription
external_item_idstringYesID of the item in your system.
external_category_idsarray of stringsYesArray of ID's of the categories in your system.
quantityintegerYesThe quantity of the item
priceintegerYesThe item price. In cents.
gross_item_pricesintegerYesThe item gross price. In cents.
net_item_priceintegerYesThe item net price pre tax, post-discount, pre tips. In cents
item_discountintegerYesThe item discount. In cents
statusintegerYesThe item status. Must be one of the following:
open
closed
voided
deleted
createddatetimeNoItem 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.

ParameterTypeDescription
typestringThe tip type. Must be one of the following:
cc
cash
declared
net
total
gratuity
valueintegerThe 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 their net_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.