API Reference

Integrate Payzo directly — manage customers, subscriptions, plans, and checkouts from your own systems. Generate a key from Settings → API in your dashboard.

Overview

The Payzo API is a REST API. It accepts and returns JSON, uses standard HTTP response codes, and is served over HTTPS from:

https://payzo.cc/api/v1

Every list, create, and update endpoint below is scoped to your organization automatically based on the API key you authenticate with — you never pass an organization id yourself.

Authentication

Pass your API key as a bearer token in the Authorization header on every request. Keys start with pz_ and are shown in full only once, at creation time — store it somewhere safe (a secrets manager, environment variable), not in client-side code.

curl https://payzo.cc/api/v1/customers \
  -H "Authorization: Bearer pz_your_api_key"

A missing or invalid key returns 401. Requests are rate limited per key — you'll get a 429 if you exceed it.

Errors & pagination

Errors are returned as JSON with an error field, and validation failures also include a details field:

{
  "error": "Invalid input",
  "details": { "fieldErrors": { "email": ["Invalid email"] } }
}

Every list endpoint accepts limit (default 20, max 100) and offset query params, and returns them back alongside data:

{ "data": [ ... ], "limit": 20, "offset": 0 }

Customers

A customer belongs to one of your connected merchant accounts. Creating one here records it in Payzo — it doesn't create anything on your processor.

GET/customers

List customers. Filter with ?email=... or ?accountId=...

Response

{
  "data": [
    {
      "id": "cst_123",
      "accountId": "acc_456",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "metadata": {},
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-01T12:00:00.000Z"
    }
  ],
  "limit": 20,
  "offset": 0
}

POST/customers

Create a customer under one of your merchant accounts.

Request body

{
  "accountId": "acc_456",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "metadata": { "externalId": "usr_1" }
}

Response

{ "data": { "id": "cst_123", "accountId": "acc_456", "email": "jane@example.com", "name": "Jane Doe", "metadata": { "externalId": "usr_1" }, "createdAt": "...", "updatedAt": "..." } }

GET/customers/:id

Retrieve a single customer.

Response

{ "data": { "id": "cst_123", "...": "..." } }

PATCH/customers/:id

Update a customer's email, name, or metadata.

Request body

{ "name": "Jane A. Doe" }

Response

{ "data": { "id": "cst_123", "name": "Jane A. Doe", "...": "..." } }

Subscriptions

Creating or updating a subscription through this API only records/updates the subscription — it never charges a card. Real charges only happen through a Payzo checkout, where the card is tokenized in the customer's browser.

GET/subscriptions

List subscriptions. Filter with ?customerId=... or ?status=...

Response

{
  "data": [
    {
      "id": "sub_123",
      "accountId": "acc_456",
      "customerId": "cst_123",
      "priceId": "prc_789",
      "status": "active",
      "currency": "usd",
      "unitAmount": 2900,
      "interval": "month",
      "intervalCount": 1,
      "currentPeriodStart": null,
      "currentPeriodEnd": null,
      "cancelAtPeriodEnd": false,
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "limit": 20,
  "offset": 0
}

POST/subscriptions

Record a subscription for an existing customer and plan.

Request body

{
  "customerId": "cst_123",
  "priceId": "prc_789",
  "status": "active"
}

Response

{ "data": { "id": "sub_123", "status": "active", "...": "..." } }

GET/subscriptions/:id

Retrieve a single subscription.

Response

{ "data": { "id": "sub_123", "...": "..." } }

PATCH/subscriptions/:id

Update status, cancellation flag/reason — e.g. cancel a subscription.

Request body

{ "status": "canceled", "cancellationReason": "Customer requested" }

Response

{ "data": { "id": "sub_123", "status": "canceled", "...": "..." } }

Plans

A plan is a price attached to a product under one of your merchant accounts.

GET/plans

List plans. Filter with ?accountId=... or ?active=true|false

Response

{
  "data": [
    {
      "id": "prc_789",
      "accountId": "acc_456",
      "productId": "prd_111",
      "productName": "Pro Membership",
      "unitAmount": 2900,
      "currency": "usd",
      "interval": "month",
      "intervalCount": 1,
      "active": true,
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "limit": 20,
  "offset": 0
}

POST/plans

Create a new plan (and its underlying product) on one of your merchant accounts.

Request body

{
  "accountId": "acc_456",
  "name": "Pro Membership",
  "unitAmount": 2900,
  "currency": "usd",
  "interval": "month",
  "intervalCount": 1
}

Response

{ "data": { "id": "prc_789", "productName": "Pro Membership", "...": "..." } }

GET/plans/:id

Retrieve a single plan.

Response

{ "data": { "id": "prc_789", "...": "..." } }

PATCH/plans/:id

Update a plan's active state or price.

Request body

{ "active": false }

Response

{ "data": { "id": "prc_789", "active": false, "...": "..." } }

Checkouts

A checkout is a hosted page your customers use to subscribe to a plan.

GET/checkouts

List checkouts.

Response

{
  "data": [
    {
      "id": "cko_123",
      "accountId": "acc_456",
      "priceId": "prc_789",
      "name": "Pro Membership Checkout",
      "slug": "pro-membership",
      "url": "https://payzo.cc/checkout/pro-membership",
      "enabled": true,
      "storeName": "Acme Inc",
      "logoUrl": null,
      "accentColor": "#1652fd",
      "createdAt": "...",
      "updatedAt": "..."
    }
  ],
  "limit": 20,
  "offset": 0
}

POST/checkouts

Create a new checkout page for an existing plan.

Request body

{
  "priceId": "prc_789",
  "name": "Pro Membership Checkout",
  "slug": "pro-membership",
  "storeName": "Acme Inc",
  "accentColor": "#1652fd"
}

Response

{ "data": { "id": "cko_123", "url": "https://payzo.cc/checkout/pro-membership", "...": "..." } }

GET/checkouts/:id

Retrieve a single checkout.

Response

{ "data": { "id": "cko_123", "...": "..." } }

PATCH/checkouts/:id

Update a checkout's name, enabled state, or branding.

Request body

{ "enabled": false }

Response

{ "data": { "id": "cko_123", "enabled": false, "...": "..." } }