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