API Documentation: S2S POS API V 1.6

Interactive Swagger-style documentation and testing consoles for each API area.

POS Retrieval API

Check API connectivity, validate cards, browse retail inventory, browse delivery options, and retrieve dispense orders.

GET /v1/connection/status GET /v1/dispenses/getRetailDispenseInventory GET /v1/dispenses/GetRetailDispenseDeliveryOptions GET /v1/dispenses/{cardId}/validate GET /v1/dispenses/{identifier}

Open documentation →

POS Dispense API

Check out in-store and delivery retail dispenses with multiple items, and void tickets.

POST /v1/dispenses POST /v1/dispenses/{ticketId}/void

Open documentation →

Common Conventions

Common Request Fields

Every internal request must include the following fields in the request body:

Field	Type	Required	Description
`posApiInternalServiceToken`	String	Yes	Shared server-to-server token used to authenticate the POS API service.
`internalRequestId`	UUID string	Yes	Unique request identifier. Generate a new UUID for each call unless an operation specifically documents idempotent retry behavior.

Response Envelopes

Successful internal calls use the following response envelope:

{
    "status": "ok",
    "message": "",
    "data": {}
}

Business, authorization, validation, and processing errors use the following response envelope:

{
    "status": "error",
    "errorCode": "ERROR_CODE",
    "message": "Description of the error.",
    "data": null
}

The application normally returns HTTP status 200 for both successful responses and handled errors. The POS API service must inspect the response status field rather than assuming that every HTTP 200 response represents a successful operation. Use errorCode for programmatic handling; the message field provides a readable explanation and may contain more specific information.

Common Error Codes

The following errors may be returned by any internal POS API call:

Error code	Message	Description
`UNAUTHORIZED_INTERNAL_SERVICE`	Unauthorized.	The internal service token was missing or invalid.
`INVALID_INTERNAL_REQUEST_ID`	A valid internal request ID is required.	`internalRequestId` was missing or was not a valid UUID.
`INTERNAL_CONFIGURATION_ERROR`	The internal POS API is not configured.	A required internal configuration value or system user is missing or invalid.
`INTERNAL_AUTHORIZATION_ERROR`	Unable to authorize internal POS API request.	An unexpected error occurred while authorizing the request.
`ACTIVE_LOCATION_LICENSE_REQUIRED`	Unable to process request. This location does not have an active, non-expired license or valid temporary access for this activity.	The location does not currently have an eligible license for the requested operation.
`LOCATION_LICENSE_CHECK_FAILED`	Unable to verify location license.	An unexpected error occurred while validating the location license.