Integration Flow

Step 1: Receive Callback

When a customer places an order and it becomes actionable, Cheers sends a callback to your configured URL:

POST https://your-system.com/callback?orderId=abc-123-def

Your system should acknowledge with 200 OK and proceed to fetch the order.

Step 2: Fetch Order Details

API: GET /v1/integrations/counter-orders/{orderId}

curl -X GET https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def \
  -H "X-API-Key: YOUR_API_KEY"

Response:

{
  "id": "abc-123-def",
  "createdAt": "2026-03-15T14:30:00Z",
  "orderNumber": "A-42",
  "status": "APPROVABLE",
  "transactionStatus": "CAPTURED",
  "paymentProcessor": "BARION",
  "currencyCode": "HUF",
  "orderSource": "MOBILE",
  "tip": {
    "tip": 200,
    "externalPayment": 0
  },
  "desk": {
    "id": "desk-001",
    "name": "Counter 1",
    "type": "COUNTER"
  },
  "invoicingType": "PLACE_RECEIPT",
  "items": [
    {
      "productId": "beer-500ml",
      "unitPrice": 800,
      "discount": 200,
      "externalPayment": 0,
      "vat": 27,
      "isTakeaway": false,
      "modifiers": [
        {
          "productId": "extra-lemon",
          "unitPrice": 100,
          "discount": 0,
          "externalPayment": 0,
          "vat": 27
        }
      ]
    }
  ]
}

Key fields to process:

Field	Usage
orderNumber	Display to the customer / call out when ready
status	Current lifecycle state
transactionStatus	Payment state -- determines if you need to handle payment
paymentProcessor	If EXTERNAL_MANUAL, you must handle payment at the counter
items	Products with prices, discounts, VAT, modifiers, and takeaway flag
items[].externalPayment	Amount per item to collect externally (if split payment)
tip	Tip amount and how much of it is paid externally
deliveryOption	Delivery fee, VAT, and type (if applicable)
desk	Which counter/table the order is associated with
userComment	Free-text note from the customer
metadata	Custom key-value pairs (if configured)

Step 3: Handle Payment (EXTERNAL_MANUAL only)

Only when paymentProcessor is EXTERNAL_MANUAL does your system need to handle payment directly. In all other cases, payment is handled by the Cheers system.

Finalize external payment:

API: PUT /v1/integrations/counter-orders/{orderId}/finalize-external-payment

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/finalize-external-payment \
  -H "X-API-Key: YOUR_API_KEY"

Cancel external payment:

API: PUT /v1/integrations/counter-orders/{orderId}/cancel-external-payment

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/cancel-external-payment \
  -H "X-API-Key: YOUR_API_KEY"

Step 4: Approve or Reject

API: PUT /v1/integrations/counter-orders/{orderId}/status

Approve:

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "APPROVED"}'

Reject (with optional message):

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "REJECTED", "rejectionMessage": "Item is out of stock"}'

Step 5: Mark as Done

Once the order is prepared and ready for pickup:

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "DONE"}'

The customer receives a notification that their order is ready.

Step 6: Complete or Mark as Left

Complete (customer picked up):

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "COMPLETED"}'

Left (customer didn't pick up):

curl -X PUT https://api.dev.votesess.com/v1/integrations/counter-orders/abc-123-def/status \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "LEFT"}'

info

LEFT can be set from either APPROVED or DONE status -- use it whenever the customer abandons their order regardless of preparation state.