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

# Introduction

> Read and write your orders and shipments from your own scripts and tools.

<Info>
  The API is available on the **Enthusiast** and **Whale** plans. If you downgrade to Free, requests return `403` until you upgrade again. See [Plans and limits](/plans-and-limits).
</Info>

The Churning Tracker API is a JSON REST API for your [buying group orders](/orders/buying-group-orders), [gift card orders](/orders/gift-card-orders), [shipments](/shipments), and [credit cards](/cards/credit-cards). Orders you create through it show up in the app like any other, with the source set to `api`.

## Base URL

```
https://app.churningtracker.com/api/v1
```

## Endpoints

| Method | Path | What it does |
| - | - | - |
| `GET` | [`/buying-group-orders`](/api-reference/buying-group-orders/list-buying-group-orders) | List buying group orders |
| `POST` | [`/buying-group-orders`](/api-reference/buying-group-orders/create-a-buying-group-order) | Create a buying group order |
| `GET` | [`/buying-group-orders/{id}`](/api-reference/buying-group-orders/get-a-buying-group-order) | Get one buying group order |
| `PATCH` | [`/buying-group-orders/{id}`](/api-reference/buying-group-orders/update-a-buying-group-order) | Update a buying group order |
| `GET` | [`/gift-card-orders`](/api-reference/gift-card-orders/list-gift-card-orders) | List gift card orders |
| `POST` | [`/gift-card-orders`](/api-reference/gift-card-orders/create-a-gift-card-order) | Create a gift card order |
| `GET` | [`/gift-card-orders/{id}`](/api-reference/gift-card-orders/get-a-gift-card-order) | Get one gift card order |
| `PATCH` | [`/gift-card-orders/{id}`](/api-reference/gift-card-orders/update-a-gift-card-order) | Update a gift card order |
| `POST` | [`/shipments`](/api-reference/shipments/add-shipments) | Add tracking numbers to buying group orders |
| `GET` | [`/credit-cards`](/api-reference/credit-cards/list-credit-cards) | List credit cards and their sub-cards |

Resale and cashback orders, payouts, deleting orders, and changing credit cards aren't in the API yet.

## Authentication

Every request needs two headers: `x-api-key` and `x-api-secret`.

<Steps>
  <Step title="Generate credentials">
    Go to **Settings → Security** and click **Generate API credentials** under **API Access**.
  </Step>

  <Step title="Copy the secret">
    The secret is shown once. Copy it somewhere safe before leaving the page. The key stays visible in Settings.
  </Step>

  <Step title="Make a request">
    ```bash theme={null}
    curl https://app.churningtracker.com/api/v1/buying-group-orders \
      -H "x-api-key: ct_key_..." \
      -H "x-api-secret: ct_secret_..."
    ```
  </Step>
</Steps>

If you lose the secret, click **Refresh secret** to get a new one with the same key. **Revoke** deletes both, and every request using them fails from then on. Both take effect immediately.

<Warning>
  The key and secret give full read and write access to your orders. Keep them out of client-side code and public repositories.
</Warning>

## Conventions

* **Money is in cents.** `59999` means \$599.99. The one exception is a redemption code's `value`, which is in dollars.
* **Dates** are `YYYY-MM-DD` and **times** are `HH:mm` or `HH:mm:ss`, in your local time.
* **Unknown fields are rejected** in request bodies and query strings, so a typo returns `400` instead of being ignored.
* **Order numbers are unique** across your orders. Creating a second order with the same number returns `409`.
* **Redemption codes are write-only.** You can send them when creating or updating an order, but responses don't include them.
* **Tracking numbers** are for buying group orders only, and are added through [`POST /shipments`](/api-reference/shipments/add-shipments) rather than on the order itself.

## Updating orders

`PATCH` changes only the fields you send. Send `null` to clear `orderTime`, `creditCardId`, `subCreditCardId`, `retailerAccount`, or `notes`.

`orderLineItems` and `redemptionCodes` replace the whole list when sent. Within `orderLineItems`, include a line item's `id` to keep it and change only the fields you list. Leave the `id` out to add a new line item. Any existing line item you don't include is removed.

```json theme={null}
{
  "orderLineItems": [
    { "id": "c2d0a8f4-1b7e-4f0a-8a3e-5b6c7d8e9f01", "quantity": 3 },
    { "description": "Apple Pencil", "unitPrice": 12900, "quantity": 1 }
  ]
}
```

## Pagination

List endpoints take `limit` (1 to 100, default 25) and `offset` (default 0) and return a `pagination` object. Keep increasing `offset` by `limit` until it reaches `totalCount`.

```json theme={null}
{
  "data": [ ... ],
  "pagination": { "limit": 25, "offset": 0, "totalCount": 112 }
}
```

## Errors

Errors always have the same shape. Validation errors add an `issues` array that points at each bad field.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "issues": [{ "path": "orderLineItems.0.unitPrice", "message": "Unit price must be a whole number of cents." }]
  }
}
```

| Status | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | The body or query string failed validation. See `issues`. |
| 400 | `bad_request` | The body isn't valid JSON. |
| 400 | `invalid_input` | The change isn't allowed, such as editing amounts on an order entered as no purchase. |
| 401 | `unauthorized` | A header is missing, or the key and secret don't match. |
| 403 | `plan_required` | Your plan doesn't include API access. Upgrade to Enthusiast or Whale. |
| 404 | `not_found` | The order, line item, or credit card doesn't exist or isn't yours. |
| 409 | `duplicate_order_number` | Another of your orders already has this order number. |
| 429 | `rate_limited` | Too many requests. Wait and retry. |
| 500 | `internal_error` | Something went wrong on our side. |

## Rate limits

Requests are rate limited per account. When you hit it, back off and retry after a short wait.

## Buying group IDs

Refer to these featured buying group IDs when creating buying group orders.

| Buying group | ID |
| - | - |
| BuyForMeRetail (BFMR) | `bfmr` |
| Buying Group | `buying_group` |
| Points 4 Days | `points_4_days` |
| Max Out Deals | `max_out_deals` |
| MVP Buying Group | `mvp_buying_group` |
| Earn From Buying | `earn_from_buying` |
| Points Cash Back | `points_cash_back` |
| Buy Get Rewards | `buy_get_rewards` |
| U Earn Points | `u_earn_points` |
| Buyers For Points | `buyers_for_points` |
| PowerBuy Network | `power_buy_network` |
| Big Deal Points | `big_deal_points` |
| Buy Get Paid | `buy_get_paid` |
| U Buy We Pay | `u_buy_we_pay` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.