API Docs

The Purchase Order API. Generate signed PDFs from any language with a single POST request. Credit-metered, rate-limited, idempotent.

Authentication

All requests require a bearer token. Create keys in your dashboard. Each call consumes 1 credit; new accounts start with 10.

Authorization: Bearer sk_live_...

Create a purchase order

POST https://potemplate.com/api/public/v1/purchase_orders

curl -X POST https://potemplate.com/api/public/v1/purchase_orders \
  -H "Authorization: Bearer $POTEMPLATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3c-2b1a-9d44" \
  -d '{
    "template": "north-america",
    "po_number": "PO-1042",
    "vendor_name": "Acme Logistics",
    "items": [
      { "description": "Fiber Cable (2m)", "quantity": 50, "unit_price": 12.00 }
    ]
  }'
Try it live

Sign in and create a key in the dashboard, then paste it below.

Response

{
  "id": "b3e2...",
  "object": "purchase_order",
  "template": "north-america",
  "po_number": "PO-1042",
  "vendor_name": "Acme Logistics",
  "total_cents": 60000,
  "currency": "USD",
  "pdf_url": "https://.../po-pdfs/...signed...",
  "expires_at": "2026-07-19T12:00:00Z",
  "credits_remaining": 9,
  "request_id": "req_..."
}

Response headers include X-Request-Id, X-RateLimit-Limit, and X-RateLimit-Remaining. The PDF URL is a signed URL valid for 24 hours — cache the file, not the URL.

Rate limits

60 requests per minute per API key. When exceeded you get HTTP 429 with a Retry-After: 60 header.

Idempotency

Send an Idempotency-Key header on any POST. If you retry with the same key within 24 hours, we return the original response verbatim (no extra credit spent). Use a UUID per logical operation.

Errors

401 unauthorized

Missing or invalid Bearer token.

402 insufficient_credits

Account is out of credits. Top up in the dashboard.

422 invalid_request

Body failed validation. `issues` array explains what.

429 rate_limited

Exceeded 60 requests / minute on this key. Retry after 60s.

5xx pdf_generation_failed / persist_failed / storage_failed

Transient — retry with the same Idempotency-Key.

Other endpoints

  • GET /api/public/v1/purchase_orders/{id} — retrieve a PO and get a fresh signed URL.
  • GET /api/public/v1/usage — check remaining credits and last-30-day request counts programmatically.

Templates

Pass any of these template IDs:

  • north-america
  • europe
  • asia-pacific

Connect to Claude, ChatGPT and other AI assistants

poTemplate ships an MCP server, so an AI assistant can create and look up purchase orders in your account after you sign in once. For step-by-step setup in Claude, ChatGPT and Cursor, see the AI agents guide. The MCP server below is for AI assistants; the REST API documented above is for direct system integrations — both draw on the same monthly pool.

https://potemplate.com/mcp

You will be sent to poTemplate to sign in and approve the connection. No API key is needed, and the assistant only ever sees your own data.

Available actions:

  • get_my_account — plan, monthly allowance used and remaining, saved company details
  • create_purchase_order — create and save a PO, returns a 24-hour PDF link; missing fields come from your saved company profile
  • list_purchase_orders — search recent POs by number, vendor or folder
  • get_purchase_order — full detail plus a fresh PDF link
  • list_folders / create_folder — organise saved POs

Purchase orders created through an assistant draw on the same monthly pool as API calls and dashboard saves.