---
title: "List tabs for a store"
method: GET
path: "/poslink/v1/tabs"
tags: ["Pay at Table"]
---

# List tabs for a store

`GET /poslink/v1/tabs`

## Request

- Base URL: `https://api.teya.com`
- URL: `https://api.teya.com/poslink/v1/tabs`
- 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/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns tabs for the specified store, cursor-paginated.

Supports optional filters:
- `status`: repeatable. When omitted, defaults to active tabs only
  (`OPEN`, `PAYING`, `PAUSED`). To include archived tabs, pass
  `status=COMPLETED` and/or `status=CLOSED` explicitly.
- `merchant_reference`: merchant-assigned reference. Unique per store, so the
  filtered response will contain at most one tab.

## Query parameters

- `store_id` string, uuid, required
- `status` string[]
- `merchant_reference` string
- `after` string
- `before` string
- `limit` integer

## Response `200`

Tabs retrieved successfully

- TabListResponse: Paginated list of tabs
  - `tabs` TabSummary[]: Page of tab summaries
    - `tab_id` string, uuid, required: Tab identifier
    - `tab_name` string, required: Tab display name
    - `merchant_reference` string, required: Merchant-assigned unique reference for the tab.
    - `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
    - `showing_bill_terminal_id` string: Terminal currently showing the bill. Present only while a bill is being displayed.
  - `paging` CursorPaging
    - `cursors` Cursors: Opaque cursors for paginating forward (after) and backward (before)
      - `before` string: Opaque cursor pointing to the first item of the current page
      - `after` string: Opaque cursor pointing to the last item of the current page
    - `paths` Paths: Relative paths for navigating to the previous and next pages
      - `previous` string: Relative path to retrieve the previous page
      - `next` string: Relative path to retrieve the next page

## 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
- `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)