> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/epos-api-reference/access-epos-orders-api/faqs.md). # 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: 1. Customer-sponsored request through account manager 2. Discovery call with EPOS Product Team 3. NDA signature (required before test access) 4. Technical development with ongoing support 5. Technical sign-off meeting with test case validation 6. 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: ``` Authorization: Bearer {your-jwt-token} ``` **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 `error` flag 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`: ```json { "error": true, "errorMessage": "PLU not found: 99999", "order": null } ``` 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:mm` in 24-hour format (e.g., "14:30", "19:00") * **DateTimes**: Pass local date/time values - The hour/minute you send is used as‑is as the local order time. **Q: Which fields are mandatory for each OrderType?** **All OrderTypes** require: * `isOpen` * `ordertype` * `tracktype` * `trackoffset` **OrderType 4 (Kiosk)** additionally require: * `billno` * `saleprops.terminalid` * `weborderdisplayno` **OrderType 7 (WebOrder)** additionally requires: * `weborderdate` * `webordertimefrom` * `webordertimeto` * `webordername` * `customerno` * `webordertype` * `weborderproductiontype` * `weborderdisplayno` * `weborderpayoncollectiondelivery` * `weborderlocationtimecat` * Complete `transactionitems` array * `paymentitems` array (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: 1. Call `/api/Menu/Menus` to get available menus 2. Call `/api/Menu/MenuDetails` with the menuId to get complete menu structure including all PLU numbers in the `plus` arrays **Q: What happens if I submit an invalid/inactive PLU ID?** A: You'll receive a validation error in the response: ```json { "error": true, "errorMessage": "PLU not found: 99999" } ``` **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: ```json { "paymentitems": [ { "totalvalue": 25.50, "paymenttype": 2, "description": "Card Payment", "authcode": "AUTH123456", "cardscheme": "Visa", "cardno": "****1234", "transactionref": "TXN789" } ] } ``` **Q: Can I process multiple payment types in a single transaction?** A: Yes. The `paymentitems` array supports multiple payments: ```json { "paymentitems": [ { "totalvalue": 15.00, "paymenttype": 0, "description": "Cash" }, { "totalvalue": 10.50, "paymenttype": 2, "description": "Card" } ] } ``` **Q: How do I handle change given to customers?** A: Use a separate payment item with `ischange: true` and negative totalvalue: ```json { "paymentitems": [ { "totalvalue": 30.00, "paymenttype": 0, "ischange": false, "description": "Cash" }, { "totalvalue": -5.00, "paymenttype": 0, "ischange": true, "description": "Change" } ] } ``` *** ### Webhook Setup **Q: How do I register webhook URLs?** A: Use the `/api/Notifications/UpdateWebOrdersNotificationSettings` endpoint: ```javascript POST /api/Notifications/UpdateWebOrdersNotificationSettings ?companyCode=ACME &URL=https://your-domain.com/webhooks/epos &authHeader=Authorization &authValue=Bearer your-secret-token ``` **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: 1. Implement retry logic with exponential backoff for transient failures 2. Display clear error messages to users about terminal connectivity 3. 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: 1. Look at the item's `condiments` array for linked condiment lists 2. Each condiment list contains `condPLUs` with available options 3. Condiment 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: ```javascript GET /GetTransaction ?searchType=2 &offset=15 &transactionPos=1 // Get the second split bill ``` *** ### 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: ```json { "transactionitems": [ { "offset": 50003, "itemheld": true, "description": "Dessert - hold until requested" } ] } ``` 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: 1. Fetch MenuDetails on app startup or daily 2. Store locally (database, file system, memory cache) 3. 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: 1. Implement webhooks via UpdateWebOrdersNotificationSettings 2. Use GetTransaction only when customer explicitly requests status 3. 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**: (9am-9pm UK time) * **Technical guidance**: * **Commercial discussions**: **Q: What support is available during development?** A: Throughout the development phase: * Email support via * 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: ```javascript // Step 1: Add items UpdateOrder({ transactionitems: [...] }); // Step 2: Calculate totals (before payment) UpdateOrder({ calcsubtotaladjustments: true, forceSubTotal: true }); // Step 3: Apply payment and close UpdateOrder({ isOpen: false, paymentitems: [...] }); ``` **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: ``` Authorization: Bearer {your-jwt-token} Content-Type: application/json ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.hos.accessacloud.com/epos-api-reference/access-epos-orders-api/faqs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.