Getting Started

The Palm API provides programmatic access to your organization's order data. Use it to build integrations, sync with external systems, or power custom dashboards.

Base URL

All API requests are made to:

https://lite-dev.palmnet.co/v1

The API is versioned via the URL path. The current version is v1.

Make Your First Request

Once you have an API key, try fetching your most recent orders:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lite-dev.palmnet.co/v1/orgs/{orgId}/orders?page_size=5"

A successful response looks like:

{
  "orders": [
    {
      "id": "cfa605d4-1ec6-4e32-87c5-4db875801639",
      "storeId": "00000000-0000-0000-0000-000000000001",
      "paymentStatus": "paid",
      "totalCents": 1375,
      "createdAt": "2024-06-15T14:30:00Z"
    }
  ],
  "hasMore": true
}

Endpoints

List Orders

GET /v1/orgs/{orgId}/orders

Returns orders across all stores in your organization, newest first. Requires the orders:read scope.

Query Parameters

Parameter	Type	Default	Description
store_id	string	—	Filter by a specific store
view	string	all	active, all, or history
payment_status	string	—	Comma-separated: paid, unpaid, partial, refunded
fulfillment_status	string	—	Comma-separated: pending, accepted, preparing, ready, completed,cancelled
source	string	—	Comma-separated: pos, kiosk, online
from	string	—	Start date/time (RFC 3339 or YYYY-MM-DD)
to	string	—	End date/time (date-only values are treated as end-of-day)
amount_min	integer	—	Minimum totalCents, inclusive
amount_max	integer	—	Maximum totalCents, inclusive
page_size	integer	200	1–200. Capped to 50 when expand includes items
before	string	—	Cursor for pagination — pass createdAt of the last order from the previous page
expand	string	—	Sub-resources to inline: items, payments, refunds, tax_breakdown

Expanding Sub-resources

By default, the list endpoint returns order headers only. Use expand to include related data inline — this avoids making a separate detail request for each order.

curl -H "X-Api-Key: $KEY" \
  "https://lite-dev.palmnet.co/v1/orgs/$ORG_ID/orders?expand=items,payments"

Value	Effect
items	Includes line items. Caps page_size to 50
payments	Includes payment records
refunds	Includes refunds with their line items and payment breakdown
tax_breakdown	Includes per-rate tax breakdown

tip

When syncing order data in bulk, use expand=items,payments to fetch everything in a single paginated loop rather than calling the detail endpoint per order.

Pagination

The API uses cursor-based pagination.

1. Make the first request without before.
2. If hasMore is true, pass the createdAt of the last order as before in the next request.
3. Repeat until hasMore is false.

Get Order

GET /v1/orgs/{orgId}/orders/{orderId}

Returns full details of a single order — items, payments, refunds, tax breakdown, and applied promotions. Requires the orders:read scope.

See the API Reference for the complete response schema.

---

Conventions

Amounts

All monetary values are integers in cents (the smallest currency unit). totalCents: 1250 means 12.50 in the store's configured currency.

Timestamps

All timestamps are RFC 3339, UTC. Example: 2024-06-15T14:30:00Z.

Localized Strings

Some fields (e.g. productName, paymentMethodName) are localized string objects. Each key is a locale code; _base is the fallback.

{
  "_base": "Latte",
  "en": "Latte",
  "zh": "拿铁"
}

Display the user's preferred locale, falling back to _base if unavailable.

---

Next Steps

• Authentication — Create and manage API keys
• API Reference — Interactive endpoint documentation
• OpenAPI Spec — Download for Postman, Insomnia, or code generation