---
title: "Marketing and other fees by day or statement"
method: GET
path: "/finance/marketing-costs"
tags: ["Finance"]
---

# Marketing and other fees by day or statement

`GET /finance/marketing-costs`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/finance/marketing-costs`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

What TikTok charged the shop, from the settled statement lines, in six buckets: gmv_max, affiliate, referral, smart_promotion, campaign (campaign-period, flash-sale, co-funded and promotion-programme fees) and other (every remaining fee, including any TikTok adds later). The buckets always sum to fee_total; marketing_total is the first five; referral is TikTok's per-sale commission, listed because Seller Center's marketing cost view lists it. Amounts keep TikTok's sign, so a cost is negative. One row per day or per statement and currency, newest first; totals cover the whole window. Only settled lines count: check data_status.covered_until before reading a recent day as complete.

## Query parameters

- `start_date` string, date, nullable: Inclusive statement-date window start (UTC). Defaults to 29 days before end_date.
- `end_date` string, date, nullable: Inclusive statement-date window end (UTC). Defaults to yesterday.
- `group_by` 'day' | 'statement': One row per statement date, or per statement.
- `limit` integer: Page size.
- `offset` integer: Page offset.

## Response `200`

Successful Response

- FinanceMarketingCostsResponse: Marketing and other fees for one shop in a window, newest first, from the settled statement lines.
  - `shop_id` integer, required
  - `tts_shop_id` string, required
  - `start_date` string, required
  - `end_date` string, required
  - `group_by` 'day' | 'statement', required
  - `pagination` PublicApiCorePaginationPaginationMeta, required: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required
  - `lines_scanned` integer, required: Statement lines in the whole window, before paging; 0 means nothing has landed.
  - `unparsed_fee_values` integer, required: Fee values TikTok sent without a column that could not be read as amounts; non-zero means other is understated.
  - `totals` FinanceMarketingCostAmounts[], required: The whole window per currency, before paging.
    - `currency` string, required
    - `lines` integer, required: Statement lines summed into these amounts.
    - `gmv_max` number, required: GMV Max ad fees and GMV Max coupon fees.
    - `affiliate` number, required: Creator, partner (TAP) and affiliate-ads commissions, deposits and releases.
    - `referral` number, required: TikTok's referral fee: its per-sale commission, counted here as Seller Center's marketing cost view does.
    - `smart_promotion` number, required: Smart promotion fees.
    - `campaign` number, required: Campaign-period, flash-sale, brand, category-led, co-funded, growth-package, brand-amplification and other promotion-programme fees, with any tax TikTok files as a fee line on them.
    - `other` number, required: Every other fee: platform commission, per-item and fulfilment service fees, and any fee column or key TikTok added after this was written. Not counted as marketing; here so the buckets add up to fee_total.
    - `marketing_total` number, required: gmv_max + affiliate + referral + smart_promotion + campaign.
    - `fee_total` number, required: All six buckets: every fee on these lines.
    - `tax_total` number, required: TikTok's tax_* lines. Tax TikTok files as a fee line (e.g. on campaign fees) is in that fee's bucket instead.
    - `fee_tax_amount` number, required: TikTok's own fee-and-tax total for these lines. It can differ from fee_total + tax_total by components TikTok does not itemise.
  - `bucket_columns` object, required: The statement-line fee columns each bucket sums, so any amount can be traced.
  - `data` FinanceMarketingCostOut[], required
    - `currency` string, required
    - `lines` integer, required: Statement lines summed into these amounts.
    - `gmv_max` number, required: GMV Max ad fees and GMV Max coupon fees.
    - `affiliate` number, required: Creator, partner (TAP) and affiliate-ads commissions, deposits and releases.
    - `referral` number, required: TikTok's referral fee: its per-sale commission, counted here as Seller Center's marketing cost view does.
    - `smart_promotion` number, required: Smart promotion fees.
    - `campaign` number, required: Campaign-period, flash-sale, brand, category-led, co-funded, growth-package, brand-amplification and other promotion-programme fees, with any tax TikTok files as a fee line on them.
    - `other` number, required: Every other fee: platform commission, per-item and fulfilment service fees, and any fee column or key TikTok added after this was written. Not counted as marketing; here so the buckets add up to fee_total.
    - `marketing_total` number, required: gmv_max + affiliate + referral + smart_promotion + campaign.
    - `fee_total` number, required: All six buckets: every fee on these lines.
    - `tax_total` number, required: TikTok's tax_* lines. Tax TikTok files as a fee line (e.g. on campaign fees) is in that fee's bucket instead.
    - `fee_tax_amount` number, required: TikTok's own fee-and-tax total for these lines. It can differ from fee_total + tax_total by components TikTok does not itemise.
    - `date` string, required: Statement date (UTC), YYYY-MM-DD.
    - `statement_id` string, nullable: Set when group_by=statement.
  - `data_status` FinanceDataStatus, required: Freshness and reachability of this shop's finance statements. ``scope_missing`` means the shop's TikTok grant refused the finance scope on the last sync; the fix is to re-authorize, not to retry.
    - `state` union, required: Latest statements-sync status: never_run | ok | empty | partial | scope_missing | unsupported | failed.
      - 'never_run' | 'ok' | 'empty' | 'partial' | 'scope_missing' | 'unsupported' | 'failed'
      - string
    - `last_synced_at` string, nullable: ISO timestamp of the last completed statements window.
    - `covered_from` string, nullable: ISO timestamp where the unbroken run of synced windows begins; nothing before it is known.
    - `covered_until` string, nullable: ISO timestamp up to which data is known to be complete (exclusive); the end of that same unbroken run.
    - `transactions_backlog` integer: Statements whose line items have not fully landed yet.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-20** `19bd89c85d71`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/finance/marketing-costs/get.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)