Guides
Conventions
Dates, pagination, money and errors.
Dates and times
The newer endpoints (content, stores, Shopify, apps, payouts, Meta ads, applications, sample requests, TikTok Shop) take start_date and end_date as YYYY-MM-DD. Days are UTC and both ends count, so 2026-10-01 to 2026-10-31 is all of October. Times in answers are ISO 8601 with a zone, such as 2026-10-31T18:04:11Z.
The older /stats/* endpoints take MM/DD/YYYY and read the brand's own calendar days.
Pagination
Lists take page (from 1) and per_page. The answer's meta says which page you are on and whether more follow (has_more), or the page count (page_count) on older endpoints. A few TikTok Shop lists page with a token instead: pass nextPageToken back as page_token, or nextCursor as cursor.
Money
Fields ending in _cents are whole cents. Other money fields are either a number in the currency's main unit or a formatted string, and the field list says which. Amounts are in the brand's currency; a sale in another currency is left out of money totals rather than added at face value. Meta's own figures (spend, purchase value) are in the ad account's currency and appear only for ad accounts billed in the brand's currency.
Errors
An error is a non-2xx status with a JSON body that has an error field and usually message. The Meta ads endpoints add success: false; the TikTok Shop ones a code.
| Status | Meaning |
|---|---|
| 401 | Missing or wrong key |
| 403 | A view-only key tried to change something |
| 404 | The record does not exist or belongs to someone else |
| 422 | A bad parameter, or an action the record's state does not allow |
| 429 | Rate limited; see rate limits |
| 5xx | A fault on our side; retry with backoff |
Data that arrives with a connector
TikTok Shop, Meta's own reporting and the app store numbers come from connections a brand switches on. Until then those endpoints answer empty results in the documented shape, never an error; their reference pages are marked Connector. Meta ads created through the API are stored and queued right away and reach Meta once the brand's Meta connection is live (Queued).