Skip to main content

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.

​
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 SDK wraps the entire API with full type safety. It handles authentication, request signing, idempotency keys, and webhook verification automatically. 
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

HeaderRequiredDescription
Content-TypeYesAlways application/json
X-Store-SlugConditionalStore slug (for public checkout flows)
X-EnvironmentConditionaltest or prod (required with Store Slug auth, not needed for API Key)
X-Idempotency-KeyOptionalUnique ID for write operations (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}.
PrefixEntityExample
MERMerchantMER_2D5F8G3H1K4M6N9P
STOStoreSTO_3bVzrkD0FJjFdZNLk8Ualx
PRODProduct / VersionPROD_4cWAslE1GKkGeaOMl9Vbmy
ORDOrderORD_5dXBtmF2HLlHfbPNm0Wcnz
PAYPaymentPAY_6eYCunG3IMmIgcQOnaXdoA
REFRefundREF_7fZDvoH4JNnJhdRPobYepB
TKTTicketTKT_8gAEwpI5KOoKieSQL1ZfqC
KEYAPI KeyKEY_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

CodeDescription
200Success
400Bad Request — invalid parameters
401Unauthorized — authentication failed
403Forbidden — insufficient permissions
404Not Found
409Conflict — idempotent request already in progress
429Rate Limited — too many requests
500Internal Server Error
501Not Implemented
502Bad Gateway

​
Environments

API Key authentication determines the environment automatically based on which key verifies successfully. Store Slug authentication requires the X-Environment header:
EnvironmentHeader ValueDescription
TestX-Environment: testNo real charges, isolated data
ProductionX-Environment: prodReal transactions

​
Idempotency

Prevent duplicate write operations by including an X-Idempotency-Key header:
ItemSpecification
HeaderX-Idempotency-Key
Max length256 characters
Allowed charsLetters, numbers, hyphens (-), underscores (_)
Cache duration24 hours
ScenarioBehaviorStatus
First requestExecutes normally, caches 2xx responseOriginal
Duplicate (completed)Returns cached response without re-executingOriginal
Duplicate (in progress)Returns conflict error409
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