# API Reference

The PaymentKit API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes and authentication.

## Base URL

All API requests should be made to:

```
https://api.paymentkit.com/api
```

For example, to list customers: `https://api.paymentkit.com/api/customers`

## Authentication

The PaymentKit API uses API keys to authenticate requests. You can view and manage your API keys in the [Dashboard](https://app.paymentkit.com).

Authentication is performed via HTTP Bearer token. Include your secret token in the `Authorization` header:

```bash
curl https://api.paymentkit.com/api/customers \
  -H "Authorization: Bearer st_prod_your_secret_token"
```

PaymentKit provides two types of tokens:

| Token type        | Prefix | Usage                                                               |
| ----------------- | ------ | ------------------------------------------------------------------- |
| Secret token      | `st_`  | Server-side API calls. Keep secure, never expose in client code.    |
| Publishable token | `pt_`  | Client-side code (e.g., PaymentKit.js). Safe to expose in browsers. |

Your secret tokens carry many privileges, so keep them secure. Do not share them in publicly accessible areas such as GitHub, client-side code, or browser requests.

## Request format

Send request data as JSON with the `Content-Type: application/json` header:

```bash
curl https://api.paymentkit.com/api/customers \
  -H "Authorization: Bearer st_prod_your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@example.com", "name": "Jane Smith"}'
```

## Errors

PaymentKit uses conventional HTTP response codes to indicate the success or failure of an API request.

| Code  | Description                                    |
| ----- | ---------------------------------------------- |
| `200` | Success                                        |
| `400` | Bad Request — Invalid parameters               |
| `401` | Unauthorized — Invalid or missing API key      |
| `403` | Forbidden — Access denied to this resource     |
| `404` | Not Found — Resource doesn't exist             |
| `422` | Unprocessable Entity — Validation error        |
| `429` | Too Many Requests — Rate limit exceeded        |
| `500` | Server Error — Something went wrong on our end |

Error responses include a JSON body with details:

```json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Customer email is required",
  "instance": "/api/customers",
  "request_id": "req_abc123"
}
```

The `request_id` can be used when contacting support to help diagnose issues.

## Pagination

List endpoints return paginated results. Use `limit` and `offset` query parameters:

```bash
curl "https://api.paymentkit.com/api/customers?limit=20&offset=0" \
  -H "Authorization: Bearer st_prod_your_secret_token"
```

Paginated responses include metadata:

```json
{
  "items": [...],
  "total": 150,
  "has_more": true
}
```

| Parameter | Default | Max | Description               |
| --------- | ------- | --- | ------------------------- |
| `limit`   | 50      | 100 | Number of items to return |
| `offset`  | 0       | —   | Number of items to skip   |

## Expanding responses

Some endpoints support expanding related data. Use the `expand` query parameter:

```bash
curl "https://api.paymentkit.com/api/customers/cus_prod_abc123?expand=custom_fields" \
  -H "Authorization: Bearer st_prod_your_secret_token"
```

Available expansions vary by endpoint. Common expansions include `custom_fields` for entities that support custom field values.

## IDs

All objects have a unique identifier prefixed with the object type and environment:

| Object           | Prefix   | Example               |
| ---------------- | -------- | --------------------- |
| Account          | `acc_`   | `acc_prod_a1b2c3d4`   |
| Customer         | `cus_`   | `cus_prod_x9y8z7w6`   |
| Subscription     | `sub_`   | `sub_prod_m3n4o5p6`   |
| Invoice          | `in_`    | `in_prod_q1r2s3t4`    |
| Product          | `prod_`  | `prod_prod_u5v6w7x8`  |
| Price            | `price_` | `price_prod_a9b8c7d6` |
| Checkout Session | `cs_`    | `cs_prod_f1g2h3i4`    |

The environment segment is `prod` for production or `stg` for staging.