---
title: "Affiliate order lines: creator, content and commission per order"
method: POST
path: "/affiliate/transactions"
tags: ["Affiliate Orders"]
---

# Affiliate order lines: creator, content and commission per order

`POST /affiliate/transactions`

## Request

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

One row per order x SKU from Affiliate Center -> Orders: which creator drove it, through which content (video / LIVE / showcase), under which commission model and rates, and the estimated vs actual commission side by side. Filter by an order-created date window, creator handle, content ID or type, product, SKU, order status or settled state — the same filters as the Affiliate Center UI. Estimated amounts are set when the order is created; actual amounts and ``commission_paid_at`` fill in as TikTok settles, typically weeks later, so recent windows keep moving — read ``data_status`` for freshness. Defaults to the last 30 complete days.

## Request body

- AffiliateTransactionsRequest: POST /affiliate/transactions request body — order x SKU affiliate lines.
  - `start_date` string, date, nullable: Inclusive window start on the order CREATED date (YYYY-MM-DD), in the shop's Affiliate Center timezone. Defaults to 30 days before end_date.
  - `end_date` string, date, nullable: Inclusive window end (YYYY-MM-DD). Defaults to yesterday — the current day is still accumulating.
  - `creator_handle` string, nullable: Filter to one creator by TikTok username. A leading '@' is ignored; case-insensitive.
  - `content_id` string, nullable: Filter to the video, LIVE or showcase that drove the sale (TikTok content ID).
  - `content_type` string, nullable: Filter by content type, case-insensitive. Values TikTok ships: Video, Livestream, Showcase, Affiliate Product Page.
  - `product_id` string, nullable: Filter to one product.
  - `sku_id` string, nullable: Filter to one SKU.
  - `order_status` string, nullable: Filter by TikTok's own commission status, case-insensitive. Values seen: Pending, Settled, Ineligible, Awaiting payment.
  - `settled` boolean, nullable: True = only lines whose commission has settled, False = everything else (pending, ineligible, awaiting payment). Unsettled amounts still move.
  - `limit` integer: Page size.
  - `offset` integer: Page offset. Capped at 100,000: deeper pages still scan and sort everything before them, so narrow the date window instead.

## Response `200`

Successful Response

- AffiliateTransactionsResponse: Paginated order x SKU affiliate lines.
  - `shop_id` integer, required
  - `seller_id` string, required
  - `start_date` string, required: Resolved inclusive window start (order-created date).
  - `end_date` string, required: Resolved inclusive window end.
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `pagination` PublicApiCorePaginationPaginationMeta: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required
  - `data` AffiliateTransactionOut[]
    - `order_id` string, required
    - `sku_id` string, required
    - `product_id` string, nullable
    - `product_name` string, nullable
    - `quantity` integer, nullable
    - `price` number, nullable: Unit price at order time.
    - `payment_amount` number, nullable: What the buyer paid for this line, after discounts.
    - `currency` string, required
    - `fully_refunded` boolean, nullable: TikTok's 'Fully returned or refunded' flag.
    - `payment_method` string, nullable
    - `order_status` string, nullable: TikTok's commission status for the line: Pending | Settled | Ineligible | Awaiting payment.
    - `is_settled` boolean, required: True when order_status is Settled and actual amounts are final.
    - `creator_handle` string, nullable: TikTok username of the creator credited with the sale.
    - `content_type` string, nullable: Video | Livestream | Showcase | Affiliate Product Page.
    - `content_id` string, nullable: ID of the video, LIVE or showcase that drove the sale.
    - `commission_model` string, nullable: e.g. 'fixed commission' or 'By order volume'.
    - `standard_commission_rate` number, nullable: Standard commission rate as a ratio (0.2 = 20%).
    - `shop_ads_commission_rate` number, nullable: Shop Ads commission rate as a ratio; null when not a Shop Ads order.
    - `estimated` AffiliateCommissionAmounts, required: One side (estimated or actual) of an affiliate line's commission.
      - `commission_base` number, nullable: Product price x quantity the commission is computed on.
      - `standard_commission` number, nullable: Standard (plan) commission payment.
      - `shop_ads_commission` number, nullable: Shop Ads commission payment, when the order came through Shop Ads.
      - `cofunded_creator_bonus` number, nullable: Co-funded creator bonus, when a campaign applied.
    - `actual` AffiliateCommissionAmounts, required: One side (estimated or actual) of an affiliate line's commission.
      - `commission_base` number, nullable: Product price x quantity the commission is computed on.
      - `standard_commission` number, nullable: Standard (plan) commission payment.
      - `shop_ads_commission` number, nullable: Shop Ads commission payment, when the order came through Shop Ads.
      - `cofunded_creator_bonus` number, nullable: Co-funded creator bonus, when a campaign applied.
    - `order_created_at` string, nullable: ISO timestamp with offset, in the export timezone.
    - `paid_at` string, nullable
    - `delivered_at` string, nullable
    - `commission_paid_at` string, nullable: When TikTok paid the creator; null until then.
    - `platform` string, nullable: 'TTS' for TikTok Shop.
  - `transactions` AffiliateTransactionOut[]: Deprecated alias of `data`; use `data`.
    - `order_id` string, required
    - `sku_id` string, required
    - `product_id` string, nullable
    - `product_name` string, nullable
    - `quantity` integer, nullable
    - `price` number, nullable: Unit price at order time.
    - `payment_amount` number, nullable: What the buyer paid for this line, after discounts.
    - `currency` string, required
    - `fully_refunded` boolean, nullable: TikTok's 'Fully returned or refunded' flag.
    - `payment_method` string, nullable
    - `order_status` string, nullable: TikTok's commission status for the line: Pending | Settled | Ineligible | Awaiting payment.
    - `is_settled` boolean, required: True when order_status is Settled and actual amounts are final.
    - `creator_handle` string, nullable: TikTok username of the creator credited with the sale.
    - `content_type` string, nullable: Video | Livestream | Showcase | Affiliate Product Page.
    - `content_id` string, nullable: ID of the video, LIVE or showcase that drove the sale.
    - `commission_model` string, nullable: e.g. 'fixed commission' or 'By order volume'.
    - `standard_commission_rate` number, nullable: Standard commission rate as a ratio (0.2 = 20%).
    - `shop_ads_commission_rate` number, nullable: Shop Ads commission rate as a ratio; null when not a Shop Ads order.
    - `estimated` AffiliateCommissionAmounts, required: One side (estimated or actual) of an affiliate line's commission.
      - `commission_base` number, nullable: Product price x quantity the commission is computed on.
      - `standard_commission` number, nullable: Standard (plan) commission payment.
      - `shop_ads_commission` number, nullable: Shop Ads commission payment, when the order came through Shop Ads.
      - `cofunded_creator_bonus` number, nullable: Co-funded creator bonus, when a campaign applied.
    - `actual` AffiliateCommissionAmounts, required: One side (estimated or actual) of an affiliate line's commission.
      - `commission_base` number, nullable: Product price x quantity the commission is computed on.
      - `standard_commission` number, nullable: Standard (plan) commission payment.
      - `shop_ads_commission` number, nullable: Shop Ads commission payment, when the order came through Shop Ads.
      - `cofunded_creator_bonus` number, nullable: Co-funded creator bonus, when a campaign applied.
    - `order_created_at` string, nullable: ISO timestamp with offset, in the export timezone.
    - `paid_at` string, nullable
    - `delivered_at` string, nullable
    - `commission_paid_at` string, nullable: When TikTok paid the creator; null until then.
    - `platform` string, nullable: 'TTS' for TikTok Shop.
  - `data_status` AffiliateOrdersDataStatus, required: Freshness of the affiliate orders export, with its own vocabulary. Separate from `PnlDataStatus` rather than widening it: nine P&L responses share that model, and the affiliate rollout states and `detail` copy mean nothing there — advertising them on P&L would be documentation that is wrong for the endpoint returning it (Codex).
    - `state` union, required: Export-run status, or why no run exists: not_enabled | awaiting_first_export | never_run | pending | parsed | empty | failed. `not_enabled` means the export has not been switched on for this shop — the usual reason this page is empty, and not a fault with the shop, its TikTok connection or its onboarding.
      - 'never_run' | 'not_enabled' | 'awaiting_first_export' | 'pending' | 'parsed' | 'empty' | 'failed'
      - string
    - `last_synced_at` string, nullable: ISO timestamp of the newest successfully parsed run.
    - `last_window` PnlDateWindow: The date window an export run requested.
      - `start_date` string, nullable
      - `end_date` string, nullable
    - `detail` string, nullable: Why the data looks the way it does, in a sentence written to be relayed to the end user verbatim. Read this before explaining an empty page; it is present whenever the state alone would not.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-06** `8a05d3dfc50a`: 2 warning, 2 info
  - added the new `awaiting_first_export` enum value to the `data_status/state/anyOf[subschema #1]/` response property for the response status `200`
  - added the new `not_enabled` enum value to the `data_status/state/anyOf[subschema #1]/` response property for the response status `200`
  - added the optional property `data_status/detail` to the response with the `200` status
  - removed the `no_permission` enum value from the `data_status/state/anyOf[subschema #1]/` response property for the response status `200`
- **2026-09-19** `291230805105`: 2 breaking, 5 info
  - the response property `transactions` became optional for the status `200`
  - the `data_status/state` response's property type changed from `string` to no type for status `200`
  - added the optional property `data` to the response with the `200` status
  - added the optional property `pagination` to the response with the `200` status
  - …3 more
- **2026-09-05** `643422c93bd8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/affiliate/transactions/post.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)