POS Tickets

Aggregate and indexed ticket information from your POS system. Tickets are marked as sale, void, refund, or overring, reflected in the type attribute.

Overview

Tickets include comprehensive information about purchased items, modifications to those items, discounts, surcharges, and payments. This data provides a complete picture of all transactions processed through your POS system.

Models

The ticket data structure includes the following models:

Ticket - Main ticket/check record
Ticket V2 - Enhanced ticket format with additional fields
TicketSurcharge - Additional charges applied to tickets
TicketPayment - Payment information for tickets
TicketDiscount - Discounts applied at ticket or item level
TicketGratuity - Tips and gratuities
TicketItem - Individual items on the ticket
TicketItem V2 - Enhanced item format
TicketItemModifier - Item modifications (e.g., "no onions", "extra cheese")
TicketItemModifier V2 - Enhanced modifier format
TicketMetadata - Additional metadata for tickets
TicketTax - Tax information

Capabilities

Developers can:

Retrieve aggregated ticket information using the export ticket functionality
Submit new tickets using the online ordering open ticket functionality

Ticket Dependencies

Tickets have a hierarchical structure with the following relationships:

Ticket contains multiple:
- TicketSurcharge (0 or more)
- TicketMetadata (0 or more)
- TicketDiscount (0 or more, applied at ticket level)
- TicketPayment (0 or more)
- TicketGratuity (0 or more)
- TicketTax (0 or more)
- TicketItem (0 or more)
TicketItem contains multiple:
- TicketItemModifier (0 or more)
- TicketDiscount (0 or more, applied at item level)

Ticket Types

Open Tickets

Type: open

Open tickets occur when completedAt is NULL and open is true. These represent tickets that haven't been finalized yet.

Use Case: Open Items on Check

The ticket is not closed and remains open for additional items or modifications.

SaleRef: #1 (Ticket.type:open)
+ Item #1 qty: 1 $5.00 (TicketItem.type:open)
+ Item #2 qty: 2 $7.00 (TicketItem.type:open)
ItemTotal: $19.00
PaymentTotal: $0.00

Sale Records

Type: sale

Sale records represent regular "sale" transactions when a check is already finalized and closed in the POS. Some POS brands allow adjustments of closed checks, so data should be re-synced at the end of the business day/session.

Use Case: Void Item on Check

Voids an item or items from the check. This typically happens when a server made a mistake, added the item/modifier to the check, sent it to the kitchen, and then realized it was a mistake.

Important notes:

"VOID" items/modifiers are not included in sale-level totals
"VOID" may happen on item or modifier level
Items are sent to the kitchen before being voided
Voided items may have a "voidReason"

SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty: 1 $5.00 (TicketItem.type:void)
+ Item #2 qty: 2 $7.00 (TicketItem.type:sale)
ItemTotal: $7.00
PaymentTotal: $7.00

Use Case: Negative Sale

The server wants to give money back after the day/session is closed. The server may add an "Open Item" with a negative amount, which will be marked as "REFUND".

SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:-1 $-10.00 (TicketItem.type:refund)
+ Item #2 qty:2 $5.00 (TicketItem.type:sale)
+ Item #3 qty:1 $7.00 (TicketItem.type:void)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

Overring Records

Type: overring

Overring records reverse the original sales to balance them if the server/manager made a mistake and wants to adjust it. Some POS brands don't allow adjustments of the original sale—instead they create an "overring" record to reverse and balance the original sale to 0. The check adjustment is then represented by a new "sale" record.

Important notes:

Overring records are taken as a "mistake" for finalized checks
Overring records may have only items/modifiers that are marked as "overring"
Overring records mostly balance the original sale to zero (Original Sale + Overring record = 0), however this is not a strict rule—in some cases they can be partially balanced
Some brands generate three records: (Original Sale, Overring Record, Adjusted Sale) if the check has been re-opened and adjusted in POS
To know "How many sales were there during the day?", subtract the "overring" records count from the "sale" records count
Overring records will generally have negative numbers like "guestCount" and total amounts; they can simply be aggregated across "sale" and "refund" records

Use Case: Item Adjustment

The server/manager made an item adjustment same-day on the finalized check.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (etc VISA)

###
### Overring record
###
SaleRef: #2 (Ticket.type:overring)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:overring)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:overring)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

###
### Adjusted sale
###
SaleRef: #3 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
ItemTotal: $1.00
PaymentTotal: $1.00 (CASH)

Use Case: Void a Transaction

The server paid the "wrong check" with a diner's credit card.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (etc VISA)

###
### Overring record
###
SaleRef: #2 (Ticket.type:overring)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:overring)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:overring)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

###
### Adjusted sale
###
SaleRef: #3 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
ItemTotal: $5.00
PaymentTotal: $5.00 (CASH)

Refund Records

Type: refund

The "refund" sale type is used to reverse the original check by items that should be refunded.

Important notes:

Refund records will generally have negative numbers for totals
They can simply be aggregated across "sale" and "overring" records

Use Case: Partial Refund

The diner paid for the check and later requested their money back for some items.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
+ Item #3 qty:1 $5.00 (TicketItem.type:sale)
ItemTotal: $10.00
PaymentTotal: $10.00 (etc VISA)

###
### Refund record
###
SaleRef: #2 (Ticket.type:refund)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:refund)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:refund)
ItemTotal: $-5.00
PaymentTotal: $-5.00 (etc VISA)

Use Case: Full Refund

The diner paid for the check and then requested their money back for all of the items.

###
### Original Sale
###
SaleRef: #1 (Ticket.type:sale)
+ Item #1 qty:1 $1.00 (TicketItem.type:sale)
+ Item #2 qty:2 $4.00 (TicketItem.type:sale)
+ Item #3 qty:1 $5.00 (TicketItem.type:sale)
ItemTotal: $10.00
PaymentTotal: $10.00 (etc VISA)

###
### Refund record
###
SaleRef: #2 (Ticket.type:refund)
+ Item #1 qty:-1 $-1.00 (TicketItem.type:refund)
+ Item #2 qty:-2 $-4.00 (TicketItem.type:refund)
+ Item #3 qty:-1 $-5.00 (TicketItem.type:refund)
ItemTotal: $-10.00
PaymentTotal: $-10.00 (etc VISA)

Lookup Tickets

Lookup specific tickets by their references.

Method: POST

Endpoint: /pos/v2/lookup/tickets

Note: This feature is currently available only for SkyTab POS. All other POS systems are not supported.

Use this endpoint to query tickets by specific criteria and return only the properties you need. This is more efficient than retrieving full ticket details when you only need specific fields.

Request Properties

The request body allows you to specify which properties to return in the response.

Request

POST

/pos/v2/lookup/tickets

curl -X POST https://conecto-api.shift4payments.com/pos/v2/lookup/tickets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "filter": {
      "refs": [
        {
          "locationId": 0,
          "posRef": "string"
        }
      ]
    },
    "properties": [
      {
        "name": "type"
      },
      {
        "name": "posRef"
      },
      {
        "name": "locationId"
      }
    ]
  }'

Response (Some Properties)

{
  "results": [
    {
      "type": "sale",
      "posRef": "string",
      "locationId": "string"
    }
  ]
}

Example: All Properties Request

When you need complete ticket information including all nested objects:

You can request all available properties including nested relationships like ticket items, modifiers, discounts, payments, surcharges, and gratuities.

The properties array allows you to specify nested properties using dot notation.

Request

POST

/pos/v2/lookup/tickets

{
  "filter": {
    "refs": [
      {
        "locationId": 0,
        "posRef": "string"
      }
    ]
  },
  "properties": [
    { "name": "posRef" },
    { "name": "type" },
    { "name": "voidReason" },
    { "name": "customerName" },
    { "name": "customerRef" },
    { "name": "orderTypename" },
    { "name": "orderNumber" },
    { "name": "revenueCenterName" },
    { "name": "tableName" },
    { "name": "guestCount" },
    { "name": "totalItems" },
    { "name": "totalSurcharges" },
    { "name": "totalTax" },
    { "name": "totalGrand" },
    { "name": "totalTips" },
    { "name": "totalDiscounts" },
    { "name": "totalGratuities" },
    {
      "name": "metadata",
      "properties": [
        { "name": "string" },
        { "value": "string" },
        { "type": "STRING" }
      ]
    },
    { "name": "openedAt" },
    { "name": "openedByEmployee" },
    { "name": "openedByEmployeeRef" },
    { "name": "closedAt" },
    { "name": "closedByEmployee" },
    { "name": "closedByEmployeeRef" },
    { "name": "locationId" },
    { "name": "orderTypeRef" },
    { "name": "tableRef" },
    { "name": "displayTaxTotal" },
    { "name": "onlineOrderAppRef" },
    { "name": "onlineOrderAppKey" },
    { "name": "saleTicketParentRef" },
    { "name": "splitTicketParentRef" },
    { "name": "combinedTicketParentRef" },
    {
      "name": "ticketItems",
      "properties": [
        { "name": "posRef" },
        { "name": "type" },
        { "name": "voidReason" },
        { "name": "name" },
        { "name": "itemRef" },
        { "name": "revenueClassRef" },
        { "name": "isNonSalesRevenue" },
        { "name": "departmentName" },
        { "name": "quantity" },
        { "name": "unitPrice" },
        { "name": "itemAmount" },
        { "name": "modifierAmount" },
        { "name": "discountAmount" },
        { "name": "price" },
        { "name": "tax" },
        { "name": "addedAt" },
        { "name": "upc" },
        { "name": "sku" },
        { "name": "displayPrice" },
        { "name": "specialRequests" },
        { "name": "kitchenSentAt" },
        { "name": "isOnHold" },
        { "name": "departmentRef" }
      ]
    },
    {
      "name": "ticketPayments",
      "properties": [
        { "name": "posRef" },
        { "name": "type" },
        { "name": "tenderName" },
        { "name": "cardType" },
        { "name": "amount" },
        { "name": "tipAmount" },
        { "name": "total" },
        { "name": "addedAt" }
      ]
    }
  ]
}

Retrieve Tickets

Retrieve historical tickets for a specific location.

Method: GET

Endpoint: /pos/v2/{locationId}/tickets

Important: This endpoint returns only historical tickets that have been finalized and closed.

Use query parameters to filter tickets by date range, business day, or other criteria.

Request

GET

/pos/v2/{locationId}/tickets

curl -X GET https://conecto-api.shift4payments.com/pos/v2/12345/tickets?startDate=2024-01-01&endDate=2024-01-31 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "results": [
    {
      "posRef": "12345",
      "type": "sale",
      "customerName": "John Doe",
      "guestCount": 2,
      "totalGrand": 45.50,
      "totalTax": 3.50,
      "totalTips": 8.00,
      "openedAt": "2024-01-15T18:30:00Z",
      "closedAt": "2024-01-15T19:15:00Z",
      "locationId": 12345,
      "ticketItems": [
        {
          "name": "Burger",
          "quantity": 2,
          "price": 24.00,
          "type": "sale"
        }
      ],
      "ticketPayments": [
        {
          "type": "CARD",
          "tenderName": "Visa",
          "amount": 45.50,
          "tipAmount": 8.00
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 50,
    "totalCount": 150
  }
}

Models

Ticket

The main ticket/check record containing all transaction information.

Name
posRef
Type
string
Description
Unique POS system reference ID for the ticket
Name
type
Type
string
Description
Ticket type: open, sale, refund, or overring
Name
voidReason
Type
string
Description
Reason for voiding the ticket, if applicable
Name
customerName
Type
string
Description
Name of the customer associated with the ticket
Name
customerRef
Type
string
Description
Reference to the customer record in the POS
Name
orderTypename
Type
string
Description
Type of order (e.g., "Dine In", "Takeout", "Delivery")
Name
orderNumber
Type
string
Description
Order number displayed to staff and customers
Name
revenueCenterName
Type
string
Description
Name of the revenue center (e.g., "Bar", "Restaurant")
Name
tableName
Type
string
Description
Table identifier for dine-in orders
Name
guestCount
Type
integer
Description
Number of guests on the ticket
Name
totalItems
Type
number
Description
Total amount for all items before discounts and taxes
Name
totalSurcharges
Type
number
Description
Total amount of all surcharges
Name
totalTax
Type
number
Description
Total tax amount
Name
totalGrand
Type
number
Description
Final total including all charges, taxes, and tips
Name
totalTips
Type
number
Description
Total tips/gratuities amount
Name
totalDiscounts
Type
number
Description
Total discount amount
Name
totalGratuities
Type
number
Description
Total automatic gratuities amount
Name
openedAt
Type
datetime
Description
When the ticket was opened/created
Name
openedByEmployee
Type
string
Description
Name of employee who opened the ticket
Name
openedByEmployeeRef
Type
string
Description
Reference to the employee who opened the ticket
Name
closedAt
Type
datetime
Description
When the ticket was closed/finalized
Name
closedByEmployee
Type
string
Description
Name of employee who closed the ticket
Name
closedByEmployeeRef
Type
string
Description
Reference to the employee who closed the ticket
Name
locationId
Type
integer
Description
Location ID where the ticket was created
Name
orderTypeRef
Type
string
Description
Reference to the order type in the POS
Name
tableRef
Type
string
Description
Reference to the table in the POS
Name
displayTaxTotal
Type
number
Description
Tax total as displayed to customer
Name
onlineOrderAppRef
Type
string
Description
Reference to the online ordering app, if applicable
Name
onlineOrderAppKey
Type
string
Description
Online ordering app key
Name
saleTicketParentRef
Type
string
Description
Reference to parent ticket for split/combined tickets
Name
splitTicketParentRef
Type
string
Description
Reference to original ticket if this is a split ticket
Name
combinedTicketParentRef
Type
string
Description
Reference to original ticket if this is a combined ticket
Name
ticketItems
Type
array
Description
Array of TicketItem objects
Name
ticketPayments
Type
array
Description
Array of TicketPayment objects
Name
ticketDiscounts
Type
array
Description
Array of TicketDiscount objects applied at ticket level
Name
ticketSurcharges
Type
array
Description
Array of TicketSurcharge objects
Name
ticketGratuities
Type
array
Description
Array of TicketGratuity objects
Name
ticketTaxes
Type
array
Description
Array of TicketTax objects
Name
ticketMetadata
Type
array
Description
Array of TicketMetadata objects with custom data

TicketItem

Individual items on a ticket, including menu items and open items.

Name
posRef
Type
string
Description
Unique POS reference for the ticket item
Name
type
Type
string
Description
Item type: open, sale, void, refund, or overring
Name
voidReason
Type
string
Description
Reason for voiding the item
Name
name
Type
string
Description
Display name of the item
Name
itemRef
Type
string
Description
Reference to the menu item in the POS
Name
revenueClassRef
Type
string
Description
Reference to the revenue class
Name
isNonSalesRevenue
Type
boolean
Description
Whether this item represents non-sales revenue
Name
departmentName
Type
string
Description
Name of the department (e.g., "Kitchen", "Bar")
Name
departmentRef
Type
string
Description
Reference to the department in the POS
Name
quantity
Type
number
Description
Quantity ordered
Name
unitPrice
Type
number
Description
Price per unit
Name
itemAmount
Type
number
Description
Total item amount before modifiers
Name
modifierAmount
Type
number
Description
Total amount added by modifiers
Name
discountAmount
Type
number
Description
Total discount amount for this item
Name
price
Type
number
Description
Final price including modifiers and discounts
Name
tax
Type
number
Description
Tax amount for this item
Name
addedAt
Type
datetime
Description
When the item was added to the ticket
Name
kitchenSentAt
Type
datetime
Description
When the item was sent to the kitchen
Name
upc
Type
string
Description
Universal Product Code
Name
sku
Type
string
Description
Stock Keeping Unit identifier
Name
displayPrice
Type
number
Description
Price as displayed to customer
Name
specialRequests
Type
string
Description
Special requests or notes for the item
Name
isOnHold
Type
boolean
Description
Whether the item is on hold
Name
ticketItemModifiers
Type
array
Description
Array of TicketItemModifier objects
Name
ticketItemDiscounts
Type
array
Description
Array of discounts applied to this item
Name
ticketItemTaxes
Type
array
Description
Array of taxes applied to this item

TicketItemModifier

Modifications to ticket items (e.g., "extra cheese", "no onions").

Name
posRef
Type
string
Description
Unique POS reference for the modifier
Name
type
Type
string
Description
Modifier type: sale, void, refund, or overring
Name
voidReason
Type
string
Description
Reason for voiding the modifier
Name
name
Type
string
Description
Display name of the modifier
Name
resourceType
Type
string
Description
Type of resource (e.g., "MODIFIER", "ITEM")
Name
itemRef
Type
string
Description
Reference to the item if modifier is an item
Name
modifierRef
Type
string
Description
Reference to the modifier in the POS
Name
revenueClassRef
Type
string
Description
Reference to the revenue class
Name
isNonSalesRevenue
Type
boolean
Description
Whether this represents non-sales revenue
Name
quantity
Type
number
Description
Quantity of the modifier
Name
unitPrice
Type
number
Description
Price per unit of the modifier
Name
price
Type
number
Description
Total price for the modifier
Name
sku
Type
string
Description
Stock Keeping Unit identifier
Name
addedAt
Type
datetime
Description
When the modifier was added
Name
specialRequests
Type
string
Description
Special requests or notes

TicketPayment

Payment information for tickets.

Name
posRef
Type
string
Description
Unique POS reference for the payment
Name
type
Type
string
Description
Payment type (e.g., "CARD", "CASH", "GIFT_CARD")
Name
tenderName
Type
string
Description
Name of the tender (e.g., "Visa", "Cash")
Name
cardType
Type
string
Description
Type of card used (e.g., "Visa", "Mastercard")
Name
amount
Type
number
Description
Payment amount
Name
tipAmount
Type
number
Description
Tip amount included in this payment
Name
total
Type
number
Description
Total amount including tip
Name
addedAt
Type
datetime
Description
When the payment was added

TicketDiscount

Discounts applied at ticket or item level.

Name
posRef
Type
string
Description
Unique POS reference for the discount
Name
name
Type
string
Description
Display name of the discount
Name
amount
Type
number
Description
Discount amount
Name
addedAt
Type
datetime
Description
When the discount was applied

TicketSurcharge

Additional charges applied to tickets.

Name
posRef
Type
string
Description
Unique POS reference for the surcharge
Name
name
Type
string
Description
Display name of the surcharge
Name
surchargeAmount
Type
number
Description
Base surcharge amount
Name
discountAmount
Type
number
Description
Discount amount applied to the surcharge
Name
price
Type
number
Description
Final price after discounts
Name
tax
Type
number
Description
Tax amount for the surcharge
Name
addedAt
Type
datetime
Description
When the surcharge was added
Name
ticketDiscounts
Type
array
Description
Array of discounts applied to this surcharge

TicketGratuity

Tips and gratuities on tickets.

Name
posRef
Type
string
Description
Unique POS reference for the gratuity
Name
name
Type
string
Description
Display name of the gratuity
Name
type
Type
string
Description
Gratuity type (e.g., "AUTO", "MANUAL")
Name
amount
Type
number
Description
Base gratuity amount
Name
price
Type
number
Description
Final price
Name
addedAt
Type
datetime
Description
When the gratuity was added

TicketTax

Tax information for tickets.

Name
taxRef
Type
string
Description
Reference to the tax in the POS
Name
name
Type
string
Description
Display name of the tax
Name
amount
Type
number
Description
Tax amount
Name
rate
Type
number
Description
Tax rate (e.g., 0.08 for 8%)
Name
isFlat
Type
boolean
Description
Whether this is a flat tax amount
Name
isHidden
Type
boolean
Description
Whether this tax is hidden from display

TicketMetadata

Custom metadata for tickets.

Name
name
Type
string
Description
Metadata field name
Name
value
Type
string
Description
Metadata field value
Name
type
Type
string
Description
Data type (e.g., "STRING", "NUMBER", "BOOLEAN")