Store Receipt Details From POS

This API call requires the API key as well as the business key to be sent in the HTTP Authorization header in the following format:

Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE

where

LOCATION_KEY_GOES_HERE is the API key (which is unique for a location) and BUSINESS_KEY_GOES_HERE is the business key (which is unique for a business).

See cURL examples for more details.

1. The receipt_details endpoint can store the same receipt multiple times. If the POS client sends the same receipt (same punchh_key, same location_key) many times, we store all the versions of that same receipt, provided that the time between HTTP requests is 1 second or more. However, if the same receipt is received via multiple HTTP calls in about the same time (less than 1 second), the last one overwrites the previous version of that receipt.

2. The endpoint accepts parameters in JSON as well.

3. “isl receipt details” endpoint for ALL transactions.

4. “checkins” for registered Punchh users wanting credit at the register via email, phone, QR code, or card number

5. All transactions generate the barcode / Punchh key.

6. All transactions print a barcode (?) on the receipt with that Punchh key.

7. In the event of a network outage, we expect data that was to be sent to the ISL and check-in endpoints to be queued and sent later. We do not expect the redemptions to work in that case as there is no way to receive the amount from Punchh.

Headers

Authorization
Type: string
required

This is a combination of unique API key as well as business key (UUID) as the Authorization header.

Body

application/json

amount
Type: numberFormat: double
required

Order amount before any taxes (sum of all amounts minus any discounts). Same as receipt_amount and subtotal_amount.
menu_items
Type:
required

The array contains one or more menu item objects added to an order. You send one of these arrays per API call. See How To Send Menu Items to Punchh

Properties: 8
payable
Type: numberFormat: double
required

Amount paid after applying discounts and adding any taxes or service charges. For example, if the order amount is $10, the values of the receipt_amount and subtotal_amount parameters will be $10. If a $2 discount is applied, subtotal_amount becomes $8. However, if there are $3 service charges and $1 tax, the value of the payable parameter becomes $12 (10 – 2 + 3 + 1 = 12).
pos_type
Type: string
required

Name of the POS client that is sending the receipts.

Possible values: A1 POS, Adora POS, Aloha, Aloha (Secure), Appetize, Auphan, Bite Kiosk, Brink, Comtrex, DataPoint, EPoint, Focus, Focus POS Systems, FoodTec, FoodTec V2, Gilbarco, GJS Kiosk, Granbury, Grubburr Kiosk, HoneyBakedHam POS, Hooters Hoa, HungerRush POS (Formerly Revention), InfoKING, Itwercs POS, iVend POS, Maitre’D, Marble Kiosk, Marblepos, Micros RES 3700, Micros Simphony, NCR ISS45 POS, NCR kiosk, NCR RPOS, NCR Silver, NCR Silver Essential, NCR Silver Pro, NCR Storepoint, Nextep kiosk, Onetap, PAR, PiZMET, Plum POS, Positouch, PosNet, Proprietary POS, Punchh Kiosk, Punchh Secure, QikServe Kiosk, Quardzilla, QuBeyond POS (Formerly Gusto), QuickServe, Ready (Pay-on-the-GO), Revel, SICOM, SpeedLine, Squirrel, Steak n Shake, TCPOS, Tevalis POS, Toast, Toast V3, Tray POS, Treatware, Verifone, VisualTouch POS, XPO Pay@Table, Xchangexec (Task retail), Xenial Cloud, Xpient, Xpient (Secure), Zonal POS
pos_version
Type: string
required

Version of the client software
punchh_key
Type: string
required

Punchh key (barcode without parity bit) of the receipt as generated by the POS. Should be 11 or 12, 20 digits
receipt_amount
Type: numberFormat: double
required

Order amount before taxes, calculated as the sum of item_amount for M line items in menu_items minus the item_amount for D line items; S, T, and P line items are excluded. See the description of the D, S, T, and P items in the menu_items.menu_item_type request parameter. The value of this parameter should match subtotal_amount.

⚠️ Important: During create check-in, loyalty points and visits are calculated based on the individual item amounts in the menu_items array, not directly from receipt_amount. To ensure discounts are reflected correctly in loyalty calculations, include the discount as a separate line item in menu_items with a menu_item_type: D. The system evaluates D line items as negative amounts when calculating the order total. If the discount line item is omitted, points will be calculated based on the original item prices, resulting in more points being awarded than intended.

For example, if a guest purchases an item for $12.99 and a $3.00 discount is applied, receipt_amount should be $9.99, and a discount line item of $3.00 must be included in menu_items. If the discount line item is omitted, the system will calculate points based on $12.99 instead of $9.99.
receipt_datetime
Type: string
required

Timestamp of the receipt per ISO 8601 format including TZ offset from UTC (e.g., YYYY-MM-DDThh:mm:ss-±hh:mm)
subtotal_amount
Type: numberFormat: double
required

Order amount before taxes, calculated as the sum of item_amount for M line items in menu_items minus the item_amount for D line items; S, T, and P line items are excluded. See the description of the D, S, T, and P items in the menu_items.menu_item_type request parameter. Same as receipt_amount. For historical reasons, include this parameter along with receipt_amount in the API request.
transaction_no
Type: integer
required

Transaction number of the receipt
cc_last4
Type: integer

Last 4 digits of the user's credit card number
channel
Type: string

Channel through which the check-in was requested. Possible values are: online_order, pos, web, mobile, dashboard, chatbot, kiosk. Optional, though if not provided in the receipt details request, defaults to the value used in the associated check-in call.

Responses

application/json
application/json
application/json

post/receipt_details

curl https://SERVER_NAME_GOES_HERE.punchh.com/receipt_details \
  --request POST \
  --header 'Authorization: Token token=LOCATION_KEY_GOES_HERE, btoken=BUSINESS_KEY_GOES_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
  "transaction_no": 20095,
  "vendor_transaction_no": 1095,
  "employee_id": "5208",
  "employee_name": "EMPLOYEE_NAME_GOES_HERE",
  "revenue_id": "Dine In",
  "revenue_code": "4",
  "amount": 15.99,
  "receipt_datetime": "2015-03-20T15:23:20+05:30",
  "cc_last4": 4321,
  "receipt_amount": 15.99,
  "subtotal_amount": 15.99,
  "payable": 17.27,
  "pos_version": "V03",
  "menu_items": [
    {
      "item_name": "Capastrami",
      "item_qty": 1,
      "item_amount": "15.99",
      "menu_item_type": "M",
      "menu_item_id": "1015",
      "menu_family": "52",
      "menu_major_group": "52",
      "serial_number": "1"
    },
    {
      "item_name": "Drink",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "M",
      "menu_item_id": "1234",
      "menu_family": "800",
      "menu_major_group": "152",
      "serial_number": "1"
    },
    {
      "item_name": "Free Drink with White Rice",
      "item_qty": 1,
      "item_amount": 2.86,
      "menu_item_type": "D",
      "menu_item_id": "5678",
      "menu_family": "801",
      "menu_major_group": "153",
      "serial_number": "1"
    }
  ],
  "punchh_key": "PUNCHH_KEY_GOES_HERE",
  "pos_type": "Aloha",
  "channel": "POS"
}'

Show Schema

{}