Introduction

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.

The Churning Tracker API is a JSON REST API for your buying group orders, gift card orders, shipments, and 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`	List buying group orders
`POST`	`/buying-group-orders`	Create a buying group order
`GET`	`/buying-group-orders/{id}`	Get one buying group order
`PATCH`	`/buying-group-orders/{id}`	Update a buying group order
`GET`	`/gift-card-orders`	List gift card orders
`POST`	`/gift-card-orders`	Create a gift card order
`GET`	`/gift-card-orders/{id}`	Get one gift card order
`PATCH`	`/gift-card-orders/{id}`	Update a gift card order
`POST`	`/shipments`	Add tracking numbers to buying group orders
`GET`	`/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.

Generate credentials

Go to Settings → Security and click Generate API credentials under API Access.

Copy the secret

The secret is shown once. Copy it somewhere safe before leaving the page. The key stays visible in Settings.

Make a request

curl https://app.churningtracker.com/api/v1/buying-group-orders \
  -H "x-api-key: ct_key_..." \
  -H "x-api-secret: ct_secret_..."

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.

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

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

{
  "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.

{
  "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.

{
  "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`

Getting started

Buying group orders

Gift card orders

Shipments

Credit cards

Base URL

Endpoints

Authentication

Conventions

Updating orders

Errors

Rate limits

Buying group IDs

​Base URL

​Endpoints

​Authentication

​Conventions

​Updating orders

​Pagination

​Errors

​Rate limits

​Buying group IDs

Base URL

Endpoints

Authentication

Conventions

Updating orders

Pagination

Errors

Rate limits

Buying group IDs