> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Reference
> Integrate Waffo Pancake into your application
## Overview
The Waffo Pancake API lets you programmatically manage your entire payment infrastructure:
* Create and manage stores
* Create products (one-time and subscription)
* Generate checkout sessions and process orders
* Manage subscriptions and billing
* Query data via GraphQL
* Handle refunds
## Base URL
All API requests are made to:
```
https://api.waffo.ai/v1
```
## Architecture
The API uses a hybrid approach:
* **REST endpoints** (`/v1/actions/...`) for all write operations (create, update, delete)
* **GraphQL** (`/v1/graphql`) for all read operations (queries)
All REST endpoints use `POST` method exclusively. There are no GET, PUT, PATCH, or DELETE methods.
## TypeScript SDK
The official [`@waffo/pancake-ts`](https://www.npmjs.com/package/@waffo/pancake-ts) SDK wraps the entire API with full type safety. It handles authentication, request signing, idempotency keys, and webhook verification automatically.
```bash theme={"system"}
npm install @waffo/pancake-ts
```
```typescript theme={"system"}
import { WaffoPancake } from "@waffo/pancake-ts";
const client = new WaffoPancake({
merchantId: process.env.WAFFO_MERCHANT_ID!,
privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
```
Every endpoint documented below includes an SDK example alongside the REST/cURL examples. [Full SDK documentation ->](/integrate/sdks)
***
## Authentication
Waffo Pancake uses **API Key authentication** for all programmatic API access. API Key authentication is handled automatically by the SDK.
For public-facing checkout flows, use **Store Slug** authentication with the `X-Store-Slug` header.
[Learn more about authentication ->](/api-reference/authentication)
***
## Common Headers
| Header | Required | Description |
| ------------------- | ----------- | ------------------------------------------------------------------------ |
| `Content-Type` | Yes | Always `application/json` |
| `X-Store-Slug` | Conditional | Store slug (for public checkout flows) |
| `X-Environment` | Conditional | `test` or `prod` (required with Store Slug auth, not needed for API Key) |
| `X-Idempotency-Key` | Optional | Globally unique ID per write operation (cached 24h) |
API Key authentication headers (`X-Merchant-Id`, `X-Timestamp`, `X-Signature`) are handled automatically by the SDK. You only need to provide your Merchant ID and private key when initializing the client.
***
## Request Format
* **Method**: All write endpoints use `POST`
* **Body**: JSON
* **Timestamps**: ISO 8601 UTC (e.g., `2026-01-23T00:00:00.000Z`)
* **Amounts**: Display format strings (e.g., `"29.00"` = \$29.00 USD)
* **Currencies**: ISO 4217 codes (e.g., `USD`, `EUR`, `JPY`)
* **Status values**: Always lowercase (e.g., `active`, not `ACTIVE`)
### ID Formats
All externally-facing entity IDs use **Short ID** format: `{PREFIX}_{base62}`.
| Prefix | Entity | Example |
| ------ | ----------------- | ----------------------------- |
| `MER` | Merchant | `MER_2D5F8G3H1K4M6N9P` |
| `STO` | Store | `STO_3bVzrkD0FJjFdZNLk8Ualx` |
| `PROD` | Product / Version | `PROD_4cWAslE1GKkGeaOMl9Vbmy` |
| `ORD` | Order | `ORD_5dXBtmF2HLlHfbPNm0Wcnz` |
| `PAY` | Payment | `PAY_6eYCunG3IMmIgcQOnaXdoA` |
| `REF` | Refund | `REF_7fZDvoH4JNnJhdRPobYepB` |
| `TKT` | Ticket | `TKT_8gAEwpI5KOoKieSQL1ZfqC` |
| `KEY` | API Key | `KEY_4F7H0I5J3K6M8N1P` |
Checkout Session IDs use a special format: `cs_` + UUID (e.g., `cs_550e8400-e29b-41d4-a716-446655440000`). They are not part of the Short ID system.
***
## Response Format
### Success
```json theme={"system"}
{
"data": {
"store": {
"id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
"name": "My Store",
"status": "active",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
}
```
### Error
```json theme={"system"}
{
"data": null,
"errors": [
{
"message": "Store slug already exists",
"layer": "store"
}
]
}
```
In the `errors` array, `errors[0]` is the **root cause** of the failure. Subsequent entries represent higher-level callers in the request chain.
### Error `layer` Field
Each error includes a `layer` string indicating which part of the system produced the error. Use this to identify the root cause when debugging. The value is always one of the predefined layer names (e.g., `"gateway"`, `"store"`, `"product"`).
***
## HTTP Status Codes
| Code | Description |
| ---- | -------------------------------------------------- |
| 200 | Success |
| 400 | Bad Request -- invalid parameters |
| 401 | Unauthorized -- authentication failed |
| 403 | Forbidden -- insufficient permissions |
| 404 | Not Found |
| 409 | Conflict -- idempotent request already in progress |
| 429 | Rate Limited -- too many requests |
| 500 | Internal Server Error |
| 501 | Not Implemented |
| 502 | Bad Gateway |
***
## Environments
API Key authentication determines the environment automatically based on which key verifies successfully. Store Slug authentication requires the `X-Environment` header:
| Environment | Header Value | Description |
| ----------- | --------------------- | ------------------------------ |
| Test | `X-Environment: test` | No real charges, isolated data |
| Production | `X-Environment: prod` | Real transactions |
***
## Idempotency
Prevent duplicate write operations by including an `X-Idempotency-Key` header:
| Item | Specification |
| -------------- | -------------------------------------------------------- |
| Header | `X-Idempotency-Key` |
| Uniqueness | Globally unique per request within your merchant account |
| Max length | 256 characters |
| Allowed chars | Letters, numbers, hyphens (`-`), underscores (`_`) |
| Cache duration | 24 hours |
Let the SDK generate the key when you can -- it derives a deterministic hash from `merchantId` + path + body, so it is unique per request by construction. If you build the key yourself, combine your `merchantId` with a UUID:
```
X-Idempotency-Key: MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67
```
A short, guessable key can match one already used by a different request, in which case you receive that request's cached response. See [Errors -> Idempotency for Safe Retries](/api-reference/errors#idempotency-for-safe-retries) for the full requirement.
| Scenario | Behavior | Status |
| ------------------------- | -------------------------------------------- | -------- |
| First request | Executes normally, caches 2xx response | Original |
| Duplicate (completed) | Returns cached response without re-executing | Original |
| Duplicate (in progress) | Returns conflict error | 409 |
| Original failed (non-2xx) | Same key can be retried | -- |
***
## Endpoint Groups
Issue session tokens for checkout flows
Create, update, and delete stores
Create and manage one-time purchase products
Create tiered subscription products and groups
Create checkout sessions and orders
Manage subscription lifecycle
Request and process refunds
Query all data with GraphQL