> ## Documentation Index > Fetch the complete documentation index at: https://help.atlas.kitchen/llms.txt > Use this file to discover all available pages before exploring further. # Cash voucher list > Lists cash vouchers for the merchant. Use `status` to filter active, expired, or redeemed vouchers, and `code` to search by voucher code. Cash voucher values are monetary amounts in minor currency units (cents). For example, `5000` means $50.00. Redemption happens through the existing POS cash voucher flow. This endpoint does not register redemption webhooks. ## OpenAPI ````yaml get /cash_vouchers openapi: 3.1.0 info: title: Atlas Admin API version: 1.0.0 description: '' servers: - url: https://api.atlas.kitchen/admin/v1 description: Admin API security: - apiKey: [] merchantId: [] tags: - name: Introduction description: > The Atlas Admin API provides server-to-server access to merchant operations — menu management, order lifecycle, user sync, and inventory. ### Who uses this API - **Integration partners** syncing menus, orders, or users from external systems - **POS integrations** creating dine-in carts with payment - **Aggregator platforms** pushing orders from external channels ### Base URL ``` https://api.atlas.kitchen/admin/v1 ``` All endpoints are under `/admin/v1`. Each merchant has their own API endpoint (e.g. `https://api.merchant-name.atlas.kitchen/admin/v1`). ### Conventions **Monetary values** — All monetary fields (`price_cents`, `subtotal`, `amount`, etc.) are integers in **minor currency units** (cents). `790` = $7.90. **Dates and times:** - Dates — ISO 8601 format: `2026-04-11` - Timestamps — Unix epoch (seconds): `1775882963` - Timeslots — Seconds since midnight: `36000` = 10:00 AM **Pagination** — List endpoints support `page` and `per_page` query parameters (max 200 per page). **Errors** — All errors follow a consistent format: ```json { "type": "Invalid Parameter", "message": "Human-readable description", "error_hash": { "field_name": "Specific error" } } ``` | Status | Type | Meaning | |--------|------|---------| | 401 | Unauthorized | Invalid or missing API key | | 404 | Not Found | Resource doesn't exist | | 422 | Invalid Parameter | Validation failed | | 500 | Server Error | Unexpected error | - name: Authentication description: > Every request requires two headers: | Header | Description | |--------|-------------| | `X-Api-Key` | Your API key | | `X-Merchant-Id` | Your merchant ID | ### Example ```bash curl https://api.atlas.kitchen/admin/v1/menus \ -H "X-Api-Key: your-api-key" \ -H "X-Merchant-Id: your-merchant-id" ``` ### Credential security - Never expose credentials in public repositories or client-side code - Store credentials securely (environment variables, secret managers) - If credentials are compromised, contact support immediately for replacement ### Error response Invalid or missing credentials return `401 Unauthorized`: ```json { "type": "Unauthorized", "message": "You did not provide valid credentials for this request.", "error_hash": { "api_key": "Check if the API Key is set correctly in the X-Api-Key header." } } ``` - name: Menus description: > Manage merchant menus with full hierarchy — sections, items, modifier groups, and modifiers. The `POST /menus` endpoint is an **upsert by identifier** — it creates a new menu or updates an existing one, syncing the entire hierarchy in a single call. Orphaned sections and items are automatically removed. - name: Orders description: > Create, retrieve, and update orders. Orders are created through a channel link (outlet + channel configuration) and support 3-level item nesting with payment breakdown overrides. - name: Users description: > Sync user records from external systems. Creates or updates users with support for guest users, external ID linking, and account creation. - name: Stocks description: | Item stock levels for an outlet on a given serving date. - name: Tables description: | Table layouts for outlets. - name: Carts description: | Create POS carts for dine-in orders with optional upfront payment. - name: Cash Vouchers description: > Create and inspect prepaid cash vouchers for external gift-card or voucher integrations. paths: /cash_vouchers: get: tags: - Cash Vouchers summary: Cash voucher list description: > Lists cash vouchers for the merchant. Use `status` to filter active, expired, or redeemed vouchers, and `code` to search by voucher code. Cash voucher values are monetary amounts in minor currency units (cents). For example, `5000` means $50.00. Redemption happens through the existing POS cash voucher flow. This endpoint does not register redemption webhooks. operationId: listCashVouchers parameters: - name: status in: query schema: type: string enum: - active - expired - redeemed description: Filter by voucher status. - name: code in: query schema: type: string description: Partial, case-insensitive voucher code search. responses: '200': description: Cash vouchers content: application/json: schema: type: object properties: object: type: string example: cash_voucher items: type: array items: $ref: '#/components/schemas/CashVoucher' '422': $ref: '#/components/responses/ValidationError' components: schemas: CashVoucher: type: object properties: id: type: integer description: Atlas cash voucher ID. example: 123 label: type: string description: Display label for the voucher. example: External gift voucher description: type: string description: Optional note or campaign description for the voucher. nullable: true example: Issued by external gift-card platform code: type: string description: >- Customer-facing redemption code. Atlas stores codes in uppercase without whitespace. example: EXT-ABC123 value: type: integer description: >- Voucher value in minor currency units (cents). For example, `5000` means $50.00. example: 5000 expires_after: type: string format: date description: > Last valid service date for redemption, in ISO 8601 date format. A voucher with `expires_after: 2026-12-31` is redeemable on 2026-12-31 and expires on 2027-01-01. example: '2026-12-31' unique: type: boolean description: >- Whether the voucher can only be redeemed once. Defaults to `true` when omitted on create. example: true status: type: string enum: - active - expired - redeemed description: >- Computed voucher state. `expired` wins when `expires_after` is in the past; `redeemed` applies to non-expired unique vouchers with a captured redemption; otherwise the voucher is `active`. example: active redemptions_count: type: integer description: >- Number of redeemed voucher units, excluding fully refunded cash voucher payments. example: 0 created_at: type: integer description: Unix epoch timestamp in seconds. example: 1781615664 updated_at: type: integer description: Unix epoch timestamp in seconds. example: 1781615664 Error: type: object properties: type: type: string message: type: string error_hash: type: object responses: ValidationError: description: Validation failed content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: X-Api-Key description: Your API key provided during onboarding. Example `c2fb5ae6ea99c37d...` merchantId: type: apiKey in: header name: X-Merchant-Id description: Your numeric merchant ID. Example `1` ````