> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagada.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the TagadaPay REST API

# 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://app.tagadapay.com/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](https://app.tagadapay.com).

```bash theme={null}
curl https://app.tagadapay.com/api/public/v1/auth/test \
  -H "Authorization: Bearer your-api-key"
```

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

### Authentication troubleshooting

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

```json theme={null}
{
  "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.

<Note>
  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.
</Note>

## Request format

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

```bash theme={null}
curl -X POST https://app.tagadapay.com/api/public/v1/payments \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"pagination": {"page": 1, "pageSize": 20}}'
```

## Rate limits

| Plan     | Requests/min | Burst |
| -------- | ------------ | ----- |
| Standard | 100          | 150   |
| Premium  | 500          | 750   |

Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header.

## 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:

```json theme={null}
{
  "code": "ERROR",
  "message": "Human-readable error description",
  "data": {}
}
```

## Pagination

List endpoints support pagination via request body parameters:

<Tabs>
  <Tab title="Offset pagination">
    Used by payments, orders, customers, and block rules.

    ```json theme={null}
    {
      "pagination": {
        "page": 1,
        "pageSize": 20
      },
      "sortBy": {
        "field": "createdAt",
        "direction": "desc"
      }
    }
    ```
  </Tab>

  <Tab title="Simple pagination">
    Used by subscriptions.

    ```json theme={null}
    {
      "page": 1,
      "per_page": 20,
      "sort": "subscriptions.createdAt",
      "sort_order": "desc"
    }
    ```
  </Tab>
</Tabs>

## Filtering

Most list endpoints accept a `filters` object. Common patterns:

```json theme={null}
{
  "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](/api-reference/webhooks) section.

## SDKs

<CardGroup cols={3}>
  <Card title="Node.js SDK" icon="node-js" href="/developer-tools/node-sdk/quick-start">
    Server-side SDK for Node.js / TypeScript
  </Card>

  <Card title="Plugin SDK" icon="puzzle-piece" href="/developer-tools/sdk/introduction">
    Build custom checkout plugins with React
  </Card>

  <Card title="Plugin CLI" icon="terminal" href="/developer-tools/cli/introduction">
    Deploy and manage plugins from the command line
  </Card>
</CardGroup>

## Need help?

* **Email**: [api-support@tagadapay.com](mailto:api-support@tagadapay.com)
* **Dashboard**: [app.tagadapay.com](https://app.tagadapay.com)