API Reference

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

api.waffo.ai currently resolves over IPv4 only (A records, no AAAA). From an IPv6-only host, give the process an IPv4 route (dual-stack networking or NAT64/DNS64); otherwise DNS resolution fails before any request is sent.

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 SDK wraps the entire API with full type safety. It handles authentication, request signing, and webhook verification automatically. Idempotency keys are the one thing it leaves to you — pass one per call when a retry must not duplicate the write (see Idempotency).

npm install @waffo/pancake-ts

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 ->

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 ->

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). The SDKs do not set it for you; pass it per call — see Idempotency

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

{
  "data": {
    "store": {
      "id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
      "name": "My Store",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
}

Error

{
  "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

A write operation is deduplicated only when it carries an X-Idempotency-Key header.

The SDKs do not set this header for you. They used to derive a key from merchantId + path + body; they no longer do, on any credential. Nothing is deduplicated unless you supply a key, so a write retried after a timeout executes twice.In the SDKs, pass it per call — client.stores.create(params, { idempotencyKey }) in TypeScript, pancake.WithIdempotencyKey(key) in Go, or the trailing options object of a @waffo/pancake-nextjs server action. Calling REST directly, set the header yourself. Either way the requirements below are the ones to meet.

The key itself, however you send it:

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

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 for the full requirement.

Scenario	Behavior	Status
No key sent	Executes normally, nothing cached or deduplicated	Original
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

Authentication

Issue session tokens for checkout flows

Stores

Create, update, and delete stores

One-Time Products

Create and manage one-time purchase products

Subscription Products

Create tiered subscription products and groups

Orders

Create checkout sessions and orders

Subscriptions

Manage subscription lifecycle

Refunds

Request and process refunds

GraphQL

Query all data with GraphQL

Overview

Auth

Merchant API (API Key)

Customer Portal API (Session Token)

GraphQL

Overview

Base URL

Architecture

TypeScript SDK

Authentication

Common Headers

Request Format

ID Formats

Response Format

Success

Error

Error `layer` Field

HTTP Status Codes

Environments

Idempotency

Endpoint Groups

Authentication

Stores

One-Time Products

Subscription Products

Orders

Subscriptions

Refunds

GraphQL

​Overview

​Base URL

​Architecture

​TypeScript SDK

​Authentication

​Common Headers

​Request Format

​ID Formats

​Response Format

​Success

​Error

​Error layer Field

​HTTP Status Codes

​Environments

​Idempotency

​Endpoint Groups

Authentication

Stores

One-Time Products

Subscription Products

Orders

Subscriptions

Refunds

GraphQL

Overview

Base URL

Architecture

TypeScript SDK

Authentication

Common Headers

Request Format

ID Formats

Response Format

Success

Error

Error `layer` Field

HTTP Status Codes

Environments

Idempotency

Endpoint Groups