---
title: "Retrieve the current bill for a tab"
method: GET
path: "/poslink/v1/tabs/{tab_id}/bill"
tags: ["Pay at Table"]
---

# Retrieve the current bill for a tab

`GET /poslink/v1/tabs/{tab_id}/bill`

## Request

- Base URL: `https://api.teya.com`
- URL: `https://api.teya.com/poslink/v1/tabs/{tab_id}/bill`
- Auth: OAuth 2
  - Authorization code: `https://id.teya.com/oauth/v2/oauth-authorize`
  - Token URL: `https://id.teya.com/oauth/v2/oauth-token`
- TypeScript: <https://skmtc.dev/teya/apis/poslink-api/docs/poslink/v1/tabs/:tab_id/bill/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the current bill for a tab, including items, amounts, and bill image URL (if any). If the ePOS has reported a rejection via POST /v1/tabs/{tab_id}/errors before any bill content was posted, the response still returns 200 with the bill fields empty/zero and last_error_* populated so the terminal can surface the error to the user.

## Path parameters

- `tab_id` string, uuid, required

## Response `200`

Bill retrieved. `bill_file_url` is null when the ePOS POSTed the bill without a `print_model` (no print-receipt round-trip occurred), or when the ePOS reported an error and no bill content was posted (check `last_error_code`).

- BillDetailResponse: Detailed bill information for terminal
  - `tab_id` string, uuid, required: Tab identifier
  - `tab_name` string, required: Tab display name
  - `status` 'OPEN' | 'PAYING' | 'PAUSED' | 'COMPLETED' | 'CLOSED', required: Current tab status
  - `total_amount` TabAmountWithCurrency, required: Amount with currency for tab operations
    - `amount` integer, required: Amount in smallest currency unit (e.g., cents)
    - `currency` string, required: ISO 4217 currency code
  - `total_paid` integer, required: Total amount paid so far, in the same currency as total_amount
  - `remaining` integer, required: Remaining amount to be paid, in the same currency as total_amount
  - `merchant_reference` string, required: Merchant-assigned unique reference for the tab.
  - `bill_file_url` string, uri: Presigned URL to the bill file/image. Null when the ePOS POSTed the bill without a print_model (no print-receipt round-trip occurred).
  - `showing_bill_terminal_id` string: Terminal currently holding the show-bill intent. Null when no show-bill intent is active for the tab (e.g. bill_posted was reset, or the intent expired).
  - `show_bill_expires_at` string, date-time: ISO 8601 expiry timestamp for show-bill (in UTC). Null when no show-bill intent is active.
  - `last_error_code` string: Last ePOS-reported rejection on this tab. Present only when the ePOS POSTed /errors and no subsequent teardown event has cleared it.
  - `last_error_message` string: Human-readable error message paired with last_error_code.
  - `last_error_at` string, date-time: ISO 8601 timestamp when the rejection was recorded (in UTC).

## Other responses

- `400`: Bad request
- `401`: Lacks valid authentication credentials for the requested resource
- `403`: The server understands the request but refuses to authorize it
- `404`: Either the tab does not exist (TAB_NOT_FOUND) or it exists but no bill content has been POSTed and no error has been reported yet for the active show-bill intent (TAB_BILL_NOT_READY). Disambiguate via the body's code field.
- `408`: Request timeout
- `429`: Too many requests in a given amount of time
- `500`: Internal Server Error

---

[API](https://skmtc.dev/teya/apis/poslink-api.md) - [All operations](https://skmtc.dev/teya/apis/poslink-api/llms.txt) - [OpenAPI document](https://skmtc.dev/teya/apis/poslink-api/revisions/cc7c1bd11e93?raw)