FAQs
Frequently Asked Questions
Getting Started & Access
Q: How do I get API credentials (CompanyCode, Location, PosLocation)? A: All integrations must be customer-sponsored. Contact the customer's Access account manager to initiate the integration request. After the discovery phase and NDA signature, the EPOS Product Team will provide test environment credentials including your API key, password, and the CompanyCode/Location values for testing.
Q: Is there a sandbox/test environment available? A: Yes. Test environment access and credentials are provided after you sign the Non-Disclosure Agreement (NDA). The sandbox environment allows full development and testing without affecting live customer data.
Q: What's the base URL for the API endpoints? A: The production base URL is https://api.accessepos.com/Access.Epos.Orders.API
Q: Do I need to register my app or get approval before integrating? A: Yes. The integration journey includes:
Customer-sponsored request through account manager
Discovery call with EPOS Product Team
NDA signature (required before test access)
Technical development with ongoing support
Technical sign-off meeting with test case validation
Handover to Professional Services for customer onboarding
Q: Is HTTPS required? A: Yes. All API endpoints use HTTPS for secure communication.
Authentication & Security
Q: What authentication method is used? A: JWT (JSON Web Token) authentication. You first call the /Token endpoint with your API key and password to obtain a token, which you then include in all subsequent requests.
Q: Where do I include authentication credentials in requests? A: Include the JWT token in the Authorization header using Bearer token format:
Q: How do I handle authentication errors? A: 401 Unauthorised responses indicate authentication failure. Common causes:
Expired token (tokens typically last 24 hours)
Invalid API credentials
Missing Authorization header
When you receive a 401, obtain a new token by calling /Token again with your credentials.
Q: What's the token lifetime? A: JWT tokens typically last 24 hours. Implement token refresh logic to obtain a new token before expiry or when you receive 401 errors.
Rate Limiting & API Usage
Q: Are there rate limits on API calls? A: The documentation explicitly states: "Do not poll API endpoints." The API is designed for event-driven integrations, not continuous polling. Excessive polling may result in your integration being restricted.
Q: Should I implement retry logic? A: Yes, but with caution. Implement exponential backoff for transient failures (network issues, server errors). However, do NOT retry by continuously polling. For order status checks, use the GetTransaction endpoint only when necessary, not on a schedule.
Error Handling
Q: What HTTP status codes should I expect? A: Common status codes:
200 OK: Request successful (always check
errorflag in response body)400 Bad Request: Invalid parameters or payload
401 Unauthorised: Authentication failure
404 Not Found: Company/location not found
500+ Server Error: POS terminal may be disconnected or server issue
Q: What does the error response format look like? A: All responses include an error flag and errorMessage:
Always check the error flag even on 200 responses.
Q: What happens if the POS terminal is offline? A: You'll receive a 500+ status code. Use the PingTerminal endpoint before sending orders to verify terminal connectivity. The response indicates connection status, POS software version, and terminal configuration.
Field Validations
Q: What's the valid format for datetime fields? A: Use these formats:
Dates:
YYYY-MM-DD(e.g., "2025-10-15")Times:
HH:mmin 24-hour format (e.g., "14:30", "19:00")DateTimes: ISO 8601 format where required
Q: Which fields are mandatory for each OrderType?
All OrderTypes require:
isOpenordertypetracktypetrackoffset
OrderType 4 (Kiosk) additionally require:
billnosaleprops.terminalidweborderdisplayno
OrderType 7 (WebOrder) additionally requires:
weborderdatewebordertimefromwebordertimetowebordernamecustomernowebordertypeweborderproductiontypeweborderdisplaynoweborderpayoncollectiondeliveryweborderlocationtimecatComplete
transactionitemsarraypaymentitemsarray (if pre-paid)
Menu & PLU Management
Q: How do I know which PLU IDs (offset values) are available for a location? A: Use the Menu endpoints:
Call
/api/Menu/Menusto get available menusCall
/api/Menu/MenuDetailswith the menuId to get complete menu structure including all PLU numbers in theplusarrays
Q: What happens if I submit an invalid/inactive PLU ID? A: You'll receive a validation error in the response:
Q: How do price levels work in practice? A: Price levels enable different pricing for the same items:
0: Standard pricing (default)
1+: Promotional, regional, time-based, or customer-type pricing
Set the priceLevel parameter when calling /api/Menu/MenuDetails to retrieve prices for specific tiers. In transactions, use useposprice: true to use POS pricing, or useposprice: false with a custom totalvalue to override.
Q: Should I cache menu data? A: Yes, absolutely. The documentation explicitly recommends: "Cache this data locally to reduce API calls and improve performance." Menu data doesn't change frequently, so fetch it once and refresh periodically (e.g., daily or when notified of menu updates).
Payment Processing
Q: How do I include card payment authorisation codes? A: Include payment processor details in the paymentitems array:
Q: Can I process multiple payment types in a single transaction? A: Yes. The paymentitems array supports multiple payments:
Q: How do I handle change given to customers? A: Use a separate payment item with ischange: true and negative totalvalue:
Webhook Setup
Q: How do I register webhook URLs? A: Use the /api/Notifications/UpdateWebOrdersNotificationSettings endpoint:
Q: How do I secure my webhook endpoint? A: Provide authentication details when registering:
authHeader: The header name (e.g., "Authorization", "X-API-Key")
authValue: The authentication value Access EPOS should send
Verify this authentication on your webhook endpoint before processing events.
Transaction Retrieval
Q: Can I poll GetTransaction to check order status? A: No. The API explicitly prohibits polling: "Do not poll API endpoints. The API is designed for event-driven integrations, not continuous polling." Use GetTransaction only when necessary (e.g., customer requests order status), not on a scheduled basis.
Q: What's the best practice for tracking orders? A: Store the order's tracking coordinates (ordertype, tracktype, trackoffset) and use GetTransaction only when needed. For real-time updates, implement webhooks using the Notifications endpoint.
Edge Cases & Scenarios
Q: What happens if the POS terminal goes offline during an order? A: You'll receive server errors (500+) when attempting API calls. Best practices:
Implement retry logic with exponential backoff for transient failures
Display clear error messages to users about terminal connectivity
Cache the terminal connectivity status and refresh periodically
Q: How do I handle order cancellations/abandoned orders? A: For OrderTypes 4, 7, and 8, set orderstatus: 6 (OrderCanceled) to mark the order as abandoned. For OrderType 3, simply don't close the order—staff can void it on the POS.
Q: What happens to pre-paid WebOrders if the customer doesn't collect? A: This is a business process question not covered by the API. Typically handled through customer support channels and refund processes outside the API scope.
Menu Condiments
Q: How do I identify which condiments are free vs chargeable? A: Condiments use "condiment pricing" which is separate from main item pricing. The same PLU can have both main item price and condiment price. When you fetch MenuDetails:
Look at the item's
condimentsarray for linked condiment listsEach condiment list contains
condPLUswith available optionsCondiment pricing applies when used as a condiment (not when ordered as main item)
Zero-priced condiments (like cooking instructions "Medium Rare") will have totalvalue: 0.00 in the pricing structure.
Split Bills & Multiple Payments
Q: How do I handle split bills? A: Use the transactionpos parameter:
0: First bill
1: Second bill
2: Third bill
etc.
When retrieving split bills, specify the transactionPos parameter in GetTransaction:
Kitchen Integration
Q: Do I need to worry about printgroupno and kitchen routing? A: Generally no. The POS handles kitchen routing automatically based on item configuration. The printgroupno is configured per PLU in the POS and determines which kitchen printer/station receives the order.
Q: How does itemheld work—can I control kitchen timing via the API? A: Yes. Set itemheld: true on transaction items to prevent them from being sent to the kitchen immediately:
Later, call UpdateOrder with itemheld: false to release the item to the kitchen.
Testing & Validation
Q: Is there a ValidateOrder endpoint I can use for testing? A: Yes. The /ValidateOrder endpoint validates order payloads without creating transactions. It's highly recommended for OrderType 7 (WebOrder) before calling AddOrder, but works for all order types. Use it to:
Verify required fields are present
Check PLU validity
Test voucher codes
Validate gift card balances
Confirm price calculations
Q: How do I test without creating real transactions? A: Use the sandbox/test environment provided after NDA signature. This isolated environment allows full testing without affecting live customer data.
Performance & Best Practices
Q: Should I cache menu data or fetch it fresh each time? A: Always cache menu data. The documentation explicitly recommends this: "Cache this data locally to reduce API calls and improve performance." Menu data changes infrequently, so:
Fetch MenuDetails on app startup or daily
Store locally (database, file system, memory cache)
Refresh when notified of menu changes or on a daily schedule
Q: What's the recommended approach for order status checks? A: Event-driven, not polling. The API prohibits continuous polling. Instead:
Implement webhooks via UpdateWebOrdersNotificationSettings
Use GetTransaction only when customer explicitly requests status
Store order state from API responses and update UI accordingly
Support & Documentation
Q: Where can I find the full API specification? A: The OpenAPI 3.0 specification provided in the integration documentation is the complete API reference. It includes all endpoints, schemas, parameters, and response structures.
Q: Where do I report bugs or request features? A: Contact the integration support team:
Integration queries: [email protected] (9am-9pm UK time)
Technical guidance: [email protected]
Commercial discussions: [email protected]
Q: What support is available during development? A: Throughout the development phase:
Email support via [email protected]
Additional technical calls arranged as needed
Technical guidance and documentation clarification
Test case support before sign-off
Specific Technical Clarifications
Q: When exactly should calcsubtotaladjustments and forceSubTotal be true? A: Set these flags before processing payment to trigger POS business rules:
calcsubtotaladjustments: true to apply:
Subtotal-configured discounts
Service charges
POS-configured promotions
forceSubTotal: true to calculate:
Deposit return scheme fees
Loyalty point calculations
Other business rule triggers
Typical flow:
Q: Can I update an OrderType 7 (WebOrder) after submission via AddOrder? A: No. The documentation is explicit: "UpdateOrder NOT SUPPORTED for OrderType 7 (WebOrder)." WebOrders must contain the complete order in the single AddOrder call. This is why ValidateOrder is highly recommended before submitting WebOrders.
Q: What headers are required for API requests? A: Required headers:
Last updated
Was this helpful?