TagadaPay API

The TagadaPay API is a REST API that lets you process payments, manage subscriptions, handle customers, deploy plugins, and orchestrate checkout funnels — all programmatically.

Base URL

https://api.tagada.io/api/public/v1

A sandbox environment is available for testing:

https://app.tagadapay.dev/api/public/v1

Authentication

Authenticate every request with a Bearer token in the Authorization header. Get your API key from the TagadaPay Dashboard.

curl https://api.tagada.io/api/public/v1/auth/test \
  -H "Authorization: Bearer your-api-key"

Keep your API keys secure. Never expose them in client-side code, public repositories, or logs.

Authentication troubleshooting

A missing, empty, or malformed Authorization header returns 401 with a message explaining what was wrong:

{
  "code": "NOT_AUTHORIZED",
  "message": "Missing or invalid API key. No `Authorization` header (or an empty Bearer token) was provided. Authenticate by sending your API key as a Bearer token: `Authorization: Bearer <your-api-key>`. ..."
}

Common causes:

Empty shell variable — Authorization: Bearer $KEY with $KEY unset sends an empty token. Verify with echo ${#KEY} before calling.
Wrong header — the key must be in Authorization: Bearer <key>, not in a custom header.
Wrong key type — public API endpoints accept dashboard API keys (Settings → API Keys) and TPA-restricted tp_sk_… partner keys.

Older API versions surfaced this situation as a confusing 500 mentioning Clerk: auth() was called but Clerk can't detect usage of clerkMiddleware(). If you see that error, it means the same thing: your API key did not reach the server — fix the Authorization header.

Request format

All requests must use HTTPS
Set Content-Type: application/json for POST/PUT requests
All responses return JSON

curl -X POST https://api.tagada.io/api/public/v1/payments \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"page": 1, "pageSize": 20}}'

Rate limits

Each account can make up to 600 requests per minute, counted across all of its API keys. The counter resets at the start of every clock minute. Exceeding it returns 429 Too Many Requests with a Retry-After header: the number of seconds until the counter resets. These endpoints are not counted against that limit: /stores, /stores/{id}/payment-setup, /plugins/*, /payments/export, /processing/enroll, /chargeblast/*, /atp/* and /funnels/republish-runtime. Separately, our network edge caps each source IP address at 200 requests per minute. A 429 from that cap carries no Retry-After and no x-request-id. Other 429 responses, such as the one returned after repeated invalid API keys, carry no Retry-After either. Whenever Retry-After is missing, back off exponentially. Apart from that edge 429, every API response carries an x-request-id header. Include it when you contact support about a specific call.

Error codes

Code	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions
404	Resource not found
409	Conflict with another request
429	Rate limited
500	Server error

Error responses follow this structure:

{
  "code": "ERROR",
  "message": "Human-readable error description",
  "data": {}
}

Pagination

List endpoints support pagination via request body parameters:

Offset pagination
Simple pagination

Used by payments, orders, customers, and block rules.

{
  "pagination": {
    "page": 1,
    "pageSize": 20
  },
  "sortBy": {
    "field": "createdAt",
    "direction": "desc"
  }
}

Used by subscriptions.

{
  "page": 1,
  "per_page": 20,
  "sort": "subscriptions.createdAt",
  "sort_order": "desc"
}

Filtering

Most list endpoints accept a filters object. Common patterns:

{
  "filters": {
    "status": ["active", "trialing"],
    "currency": ["USD", "EUR"],
    "date": {
      "condition": "is-after-date",
      "value": ["2024-01-01"]
    },
    "email": {
      "condition": "contains",
      "value": "john@"
    }
  }
}

Date filter conditions: is-equal-date, is-between-date, is-after-date, is-before-date.

Webhooks

Register webhook endpoints to receive real-time event notifications for payments, orders, subscriptions, and more. See the Webhooks API section.

SDKs

Node.js SDK

Server-side SDK for Node.js / TypeScript

Plugin SDK

Build custom checkout plugins with React

Plugin CLI

Deploy and manage plugins from the command line

Need help?

Email: api-support@tagadapay.com
Dashboard: app.tagada.io

​TagadaPay API

​Base URL

​Authentication

​Authentication troubleshooting

​Request format

​Rate limits

​Error codes

​Pagination

​Filtering

​Webhooks

​SDKs

Node.js SDK

Plugin SDK

Plugin CLI

​Need help?

TagadaPay API

Base URL

Authentication

Authentication troubleshooting

Request format

Rate limits

Error codes

Pagination

Filtering

Webhooks

SDKs

Need help?