# Introduction

The Open API lets your systems (ERP, website, accounting software, internal tools) read and write a shop's data on Pancake POS: orders, products, stock, customers, purchases, exports, promotions and reports.

## API address

Every endpoint lives under:

```text
https://pos.pages.fm/api/v1
```

Paths in these docs are relative to that address: `GET /shops/{SHOP_ID}/orders` means `https://pos.pages.fm/api/v1/shops/{SHOP_ID}/orders`. `{SHOP_ID}` is the shop's numeric ID.

## Your first request

1. Create an API key as described in [Authentication](/developers/api/en/authentication).
2. List the shops the key can access, with their IDs:

```bash
curl "https://pos.pages.fm/api/v1/shops?api_key=API_KEY"
```

3. Get a shop's 20 most recent orders:

```bash
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY&page_size=20&page_number=1"
```

4. Create an order by sending JSON in the request body:

```bash
curl -X POST "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bill_full_name": "Jane Doe", "bill_phone_number": "0912345678", "items": [{"variation_id": "VARIATION_ID", "quantity": 1}]}'
```

The fields of each endpoint are in the reference, for example [Orders](/developers/api/en/order).

## Data format

- Requests and responses are JSON (`Content-Type: application/json`), UTF-8 encoded.
- Responses carry `success` (`true` or `false`); data usually sits in `data`. Each endpoint documents its exact shape.
- Times use ISO 8601 in UTC, for example `2026-01-15T03:20:00`.
- Amounts are integers in POS storage units, which are hundredths for most currencies: see [Money amounts](#money-amounts).
- Array query parameters repeat the name with `[]`: `filter_status[]=1&filter_status[]=2`.

## Money amounts

Money amounts are integers in the storage unit of their currency. The API does not convert them: responses return the stored value, and order, product and purchase endpoints store the value you send as-is.

- Whole-unit currencies: `VND`, `TWD`, `LAK`, `PHP`, `MMK`, `JPY`, `INR`, `COP`, `IDR`, `CLP`, `PYG`. The amount equals the value shown in POS.
- Every other currency (`USD`, `CAD`, `EUR`, `THB`, `KRW`…) is multiplied by 100. Divide by 100 to get the value shown in POS; multiply by 100 before sending.
- A shop's `currency` and an order's `order_currency` can be `VND100` or `PHP100`: POS-internal codes (not ISO 4217) storing amounts in hundredths of a dong or peso, so they are multiplied by 100 too. The matching ISO codes are `VND` and `PHP`. An order sent with `order_currency` `VND` to a `VND100` shop is stored as a foreign-currency VND order.

Example: a price of CAD 12.50 is returned as `1250` and must be sent as `1250`, not `12.5`.

Which currency an amount uses:

- Order amounts (items, totals, fees, payments, COD) use the order's `order_currency`. An order created without it gets the shop currency.
- Product and variation prices, cost and import prices, purchases and shop settings use the shop `currency` (`GET /shops`). This includes cost prices in order items and `cost_surcharge`, even when the order is in another currency.
- `retail_price_by_currency[].retailPriceByCurrency` uses the `currency` of the same entry.

So in a `VND` shop, an order in `USD` stores USD 10.00 as `1000`, while product prices stay in whole dong.

Not multiplied: percentages and rates (`tax_rate`, `discount_each_product` when `is_discount_percent` is `true`), quantities and weights. Money fields inside e-invoice items (`items[].variation_info` of `/list_einvoices`) are returned in display units.

## Pagination

List endpoints take `page_size` together with `page_number` or `page` (see each endpoint's parameters) and return:

| Field | Meaning |
|---|---|
| `data` | Records on this page |
| `page_number` | Current page, starting at 1 |
| `page_size` | Records per page |
| `total_entries` | Total number of records |
| `total_pages` | Total number of pages |

Read a whole list by increasing `page_number` up to `total_pages`. For periodic syncs, read only what changed instead of everything. For orders: `updateStatus=updated_at` with `startDateTime` and `endDateTime` (unix timestamps).

## Reading the reference

- Endpoints are grouped by business area in the sidebar: Shop, Sales, Products & inventory, Customers & promotions, Finance, Reports & ads.
- Each endpoint lists its parameters, request body, responses by HTTP status and a `curl` example. Expand an attribute to see its children.
- Shared objects (orders, products, webhook payloads…) are in [Data models](/developers/api/en/schemas).
- Every page has a Markdown version; [llms.txt](/developers/api/llms.txt) helps AI tools read the right docs.

## Related

- [POS Apps](/developers/apps/en) call this same Open API from inside POS, with an app token issued by POS instead of an API key.
- [MCP](/developers/mcp/en) lets Claude, Codex and Cursor use the Open API through plain-language requests.
