In-Store API

The In-Store API (Orbit) is a local REST service for integrating kiosks, menu boards, and other in-store applications with the PAR POS register.

Register endpoints version: v1
Audience: IT administrators and integrators

Introduction

About Orbit

Orbit is the in-store REST API for PAR POS. It allows internal, network-connected hardware — such as self-service kiosks and digital menu boards — to communicate directly with the register (Primary Terminal) at a store. Through Orbit, connected devices can read live menu and pricing data, submit and retrieve orders, check item availability, and receive real-time notifications when Register data changes.

Orbit runs locally on the store network. Devices call the Primary Terminal directly rather than a cloud endpoint, which keeps order flow fast and functional even if the store's internet connection is degraded.

Who This Guide Is For

This guide is written for IT administrators and integration developers who are connecting to the in-store PAR POS ecosystem. It assumes familiarity with REST APIs, JSON, and HTTP authentication, but does not assume prior knowledge of PAR POS internals.

Supported Use Cases

Orbit is designed to support a range of in-store use cases. Typical integrations include:

• Self-service kiosks — Build and submit customer orders, calculate pricing and tax, and check whether menu items are currently available.
• Digital menu boards — Read current menu, pricing, and item-availability data, and stay in sync using real-time price-change notifications.

Note: Orbit is a local, in-store API. Each device connects to the register(s) at its own store and does not communicate with devices at other locations.

API Versions and Base Paths

Orbit endpoints are grouped under a few different base paths, reflecting different service areas within PAR POS. All paths below are relative to the base URL of the Primary Terminal (see Base URL).

Getting Started

Base URL

All Orbit requests are made to the Primary Terminal's local network address, for example:

https://<primary-terminal-ip>:<port>

Confirm the terminal's IP address and port with the store's network configuration or your PAR deployment contact. Orbit is served over HTTPS.

Authentication Overview

Every Orbit request (other than the authentication endpoints themselves) requires a bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are issued by one of the Authentication endpoints, and expire at the time returned in the response. Request a new token before the current one expires to avoid interrupted service.

Required Headers

Most register-facing endpoints (under /register/v1/) require a RequestId header. Orbit uses this value to trace an individual request through the system for diagnostics and support — it is not an order number or a value the register interprets.

Tip: Generate a fresh RequestId for every call. Reusing the same value across requests makes it harder to trace individual calls if you need to troubleshoot with PAR support.

Authentication

Orbit issues bearer tokens from three endpoints. Use the integrator endpoint for unattended hardware, username and password authentication for attended tools, and the admin endpoint to elevate an existing session.

POST /v2/local/Authentication/integrator

Authenticates an unattended device. This is the recommended authentication method for kiosks and other hardware.

Request body: LocalAuthenticationRequest

{
  "integratorId": "00000000-0000-0000-0000-000000000000"
}

POST /v2/local/Authentication/admin

Elevates a session to admin-level access.

Request body: LocalAdminAuthenticationRequest

This endpoint may return 428 Precondition Required when a precondition has not been met.

POST /api/Authentication/authenticate

Authenticates with a username and password.

Request body: AuthenticationRequest

Response body: AuthenticationResponse

Using the Access Token

Include the returned token on every subsequent request using the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Tokens are time-limited. Check the expirationTime field returned at login and refresh the token before it lapses. Calls made with an expired or missing token receive a 401 Unauthorized response.

Error Handling

Standard Error Response

When a request fails, most Orbit endpoints return a ProblemDetails object describing what went wrong:

{
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string"
}

HTTP Status Codes Reference

These status codes recur across Orbit endpoints, particularly the register-facing endpoints under /register/v1/, which depend on a live connection between the server and the store's Primary Register.

Note: 502, 503, and 504 responses generally indicate a connectivity issue between the server and the store's Primary Register rather than a problem with your request. Retry with backoff and escalate if the condition persists.

Connectivity and Health

Use these endpoints to confirm that Orbit is reachable and that your authentication is working, before building or troubleshooting a device integration.

GET /v1/Health

Returns a basic health check for the Orbit service. Does not require authentication.

GET /v1/Ping

A simple connectivity check. Does not require authentication.

GET /v1/Ping/testauth

Confirms that a bearer token is valid. Use this during setup to verify authentication before calling data endpoints.

Item Availability

Item availability endpoints let kiosks and menu boards check which menu items can currently be sold — for example, to gray out or hide items that are out of stock.

GET /register/v1/ItemAvailability

Returns availability information for menu items.

Parameters

Responses

GET /register/v1/ItemAvailability/unavailable

Returns the IDs of items that are currently unavailable, optionally filtered to a single destination (e.g. a specific menu, kitchen, or ordering channel).

Parameters

Responses

Settings

Settings endpoints expose the register's configuration entities — including menus, items, and pricing — that menu boards and kiosks need to render an accurate, current menu.

GET /register/v1/Settings

Returns one or more settings entities from the register.

Parameters

Responses

Tip: For menu boards, the Items, Menus, and PriceChanges entities are typically the most useful starting point. Combine this endpoint with the Price Change notification to keep displayed pricing current without polling.

GET /register/v1/Settings/lastmodifiedtime

Returns the last-modified time for settings entities, so integrators can poll efficiently and only re-fetch data that has actually changed.

Parameters

Responses

Orders

Order endpoints let kiosks build, price, and submit customer orders, and let order confirmation boards retrieve order status. Add Order and Calculate Order accept the same request body, described once in Order Request Object and referenced from both.

Order Request Object

Add Order and Calculate Order both accept the object below in the request body.

Top-Level Fields

CalculateOrderOptions Fields

Item Fields

Modifier Fields

Payment Fields

Promotion Fields

Future Order Data Fields

Include FutureOrderData for scheduled pickup or delivery orders.

A complete example of this request body is provided in Full Order Request Example.

POST /register/v1/Order

Submits a new order to the register. Use this from kiosks and other order-entry devices once the customer has finished building their order.

Parameters

Request body: the Order Request Object. See Full Order Request Example for a complete example.

Responses

POST /register/v1/Order/calculateOrder

Calculates pricing, tax, and totals for an order without submitting it to the register. Use this to show a live order total on a kiosk as the customer builds their order, before they confirm and submit it with Add Order.

Parameters

Request body: the same Order Request Object.

Responses

Tip: Call Calculate Order as customers modify their cart (adding items, applying a promotion code) so the on-screen total always reflects live pricing and tax. Call Add Order only once, when the customer confirms.

GET /register/v1/Order/GetOrder

Retrieves a single order by ID. Useful for an order confirmation board to display the details and status of a specific order.

Parameters

Responses

GET /register/v1/Order/getOrders

Retrieves a page of orders, optionally filtered to those modified since a given time. Useful for an order confirmation board to keep a rolling list of active orders in sync.

Parameters

Responses

Tip: Poll with the modifiedTime parameter set to the last time you fetched orders, so you only receive orders that are new or have changed since your last check.

GET /register/v1/Order/SummaryOrders

Returns summary-level information across orders, useful for dashboards and confirmation boards that need aggregate or lightweight order data rather than full order detail.

Parameters

Responses

Reporting

GET /register/v1/ReportingTills

Returns the tills currently configured on the register. A till represents a cash drawer or payment-tracking unit associated with a lane or terminal.

Parameters

Responses

Real-Time Notifications

Notification endpoints let devices subscribe to register events as they happen, instead of continuously polling for changes. Menu boards and order confirmation boards benefit most from these — for example, refreshing displayed pricing the moment it changes, or reacting immediately to a register connection drop.

Note: These endpoints establish a long-lived connection that streams events to the caller rather than returning a single response. Your HTTP client and any intermediate proxies must be configured to allow long-lived connections.

GET /api/Notifications/All

Subscribes to a real-time stream of all events published by the register.

GET /api/Notifications/LastModifiedTime

Subscribes to notifications emitted when the last-modified time of register data changes, signaling that dependent data (such as settings entities) should be refetched.

GET /api/Notifications/PriceChange

Subscribes to notifications emitted when item pricing changes on the register. Menu boards should subscribe to this to keep displayed prices accurate without polling Settings continuously.

GET /api/Notifications/System/{eventType}

Subscribes to system-level notifications from the register, such as connection status changes.

Parameters

Responses

Tip: Subscribe to "ConnectionStatus" events on order confirmation boards and menu boards so the device can show a clear offline state if the register connection drops, rather than silently displaying stale data.

Data Model Reference

This section lists the named schema objects referenced throughout this guide. Order-related objects (Item, Modifier, Payment, Promotion, FutureOrderData) are defined in Order Request Object and are not repeated here.

AuthenticationRequest

Used by POST /api/Authentication/authenticate.

AuthenticationResponse

Returned by POST /api/Authentication/authenticate.

LocalAuthenticationRequest

Used by POST /v2/local/Authentication/integrator.

LocalAdminAuthenticationRequest

Used by POST /v2/local/Authentication/admin.

ProblemDetails

Returned in the body of most error responses (400, 401, and others). See Standard Error Response for field descriptions.

Full Order Request Example

The example below shows a complete request body for Add Order (POST /register/v1/Order) and Calculate Order (POST /register/v1/Order/calculateOrder), using every field described in Order Request Object.

{
  "AdditionalData": {
    "key1": "value1"
  },
  "CalculateOrderOptions": {
    "CalculatePriceByPos": true
  },
  "DestinationId": 123,
  "IsTaxExempt": false,
  "Items": [
    {
      "AdditionalData": {
        "itemKey": "itemValue"
      },
      "ComboItems": [],
      "CompositeComponentId": null,
      "CompositeOrderItemId": null,
      "Description": "Sample Item",
      "Id": 1,
      "ItemId": 1001,
      "Modifiers": [
        {
          "Description": "Extra Cheese",
          "Id": 10,
          "ItemId": 2001,
          "ModifierCodeId": 3001,
          "ModifierGroupId": 4001,
          "Modifiers": [],
          "Price": 0.99
        }
      ],
      "Note": "No onions",
      "Price": 9.99
    }
  ],
  "LaneId": 1,
  "Name": "Test Order",
  "Payments": [
    {
      "Amount": 9.99,
      "AdditionalData": {
        "paymentKey": "paymentValue"
      },
      "Id": 1,
      "TenderId": 2,
      "TipAmount": 1.0
    }
  ],
  "Promotions": [
    {
      "Amount": 2.0,
      "Code": "PROMO2024",
      "ExternalOfferId": 1234,
      "Name": "New Year Promo",
      "PromotionId": 5678,
      "Upsells": [
        {
          "TargetOrderItemId": 1,
          "QualificationId": 101
        }
      ]
    }
  ],
  "ManualSend": true,
  "FutureOrderData": {
    "CustomerEmail": "customer@example.com",
    "CustomerPhone": "+1234567890",
    "PickupTime": "2024-01-02T14:30:00Z",
    "DeliveryDetails": {
      "DeliveryAddress": {
        "AddressLine1": "123 Main St",
        "AddressLine2": "Apt 4B",
        "City": "Springfield",
        "State": "IL",
        "PostalCode": "62701",
        "Country": "USA",
        "Company": "Acme Corp",
        "Notes": "Ring doorbell",
        "AddressType": "Residential"
      },
      "GeoCoordinate": {
        "Latitude": 39.7817,
        "Longitude": -89.6501
      }
    }
  }
}

Endpoint Quick Reference

Note: GET /register/v1/NoEndpoint is an internal diagnostic route the register uses to return a standardized error for unrecognized URLs. It is not intended for use by integrators and is omitted from the reference above.