Get started

Introduction

API address, data format, pagination and your first request.

View Markdown

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.
  2. List the shops the key can access, with their IDs:
Terminal
curl "https://pos.pages.fm/api/v1/shops?api_key=API_KEY"
  1. Get a shop's 20 most recent orders:
Terminal
curl "https://pos.pages.fm/api/v1/shops/SHOP_ID/orders?api_key=API_KEY&page_size=20&page_number=1"
  1. Create an order by sending JSON in the request body:
Terminal
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.

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.
  • 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.
  • Every page has a Markdown version; llms.txt helps AI tools read the right docs.
  • POS Apps call this same Open API from inside POS, with an app token issued by POS instead of an API key.
  • MCP lets Claude, Codex and Cursor use the Open API through plain-language requests.

Explore the docs