Reacher Data API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Access your Reacher affiliate data programmatically. Use your API key in the x-api-key header and shop ID in the x-shop-id header.

Base URLs:

• https://api.reacherapp.com/public/v1

Authentication

• API Key (ApiKeyAuth)

  • Parameter Name: x-api-key, in: header. Your Reacher API key (starts with rk_live_)

• API Key (ShopId)

  • Parameter Name: x-shop-id, in: header. The shop ID to query. Accepts a single integer, a comma-separated list of integers (e.g. '101,202,303'), or 'all' to query every shop your API key has access to. Multi-shop responses include a 'shops_queried' field and use USD as the default currency. Detail endpoints (e.g. GET /creators/{handle}, GET /automations/{id}) require a single shop ID.

Shops

Discover your shops and their regions.

List your shops

GET /shops

Returns all active shops accessible to this API key. Use the returned shop_id values in the x-shop-id header for other endpoints.

Example responses

200 Response

{
  "data": [
    {
      "shop_id": 0,
      "shop_name": "string",
      "region": "string",
      "affiliate_market_region": "string",
      "business_region": "string",
      "currency": "string",
      "status": "string",
      "customer_id": 0,
      "primary_category": "string"
    }
  ]
}

Responses

Creators

Affiliates who have worked with your shop.

List creators

POST /creators/list

List affiliate creators for your shop with pagination, sorting, and filtering. GMV represents the creator's lifetime revenue for this shop. Data updates approximately every hour.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "shop_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "status": "string",
  "creator_handle": "string",
  "min_shop_gmv": 0,
  "min_overall_gmv": 0,
  "min_videos": 0,
  "min_followers": 0,
  "group_id": "string",
  "tags": [
    "string"
  ],
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "follower_count": 0,
      "status": "string",
      "shop_gmv": 0,
      "overall_gmv": 0,
      "creator_level": "string",
      "overall_fulfillment_rate": 0,
      "shop_units_sold": 0,
      "shop_video_count": 0,
      "video_views": 0,
      "sample_received": 0,
      "commission_rate": 0,
      "est_commission": 0,
      "fulfillment_rate": 0,
      "tags": [
        "string"
      ],
      "product_id": "string",
      "product_title": "string",
      "updated_at": "string",
      "created_at": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Creator performance (date-filtered)

POST /creators/performance

Top creators ranked by GMV earned within a specific date range. Unlike /creators/list (which shows lifetime GMV), this endpoint uses daily performance data and matches the dashboard's 'Top Creators' section exactly. Defaults to the last 30 days. Use this for period-specific rankings and reports.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "creator_handle": "string",
  "min_gmv": 0
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_id": "string",
      "creator_handle": "string",
      "gmv": 0,
      "units_sold": 0,
      "order_count": 0,
      "est_commission": 0,
      "follower_count": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Creator activity totals for a window

POST /creators/summary

Four headline totals for the shop over a date window: creators added, affiliate GMV earned, videos posted, and orders placed. Runs the same aggregate query that backs the summary cards above the portal's My Creators table, over the same trailing-28-day default window (TikTok reporting day, GMT-7).

gmv_generated and video_posts are scoped to the shop's CRM-tracked creators, which makes them narrower than their whole-shop namesakes on POST /metrics/summary (gmv, videos_posted) — the two will not agree, by design.

Aggregates cover the whole shop — there is no filter parameter in v1. Defaults to the trailing 28 days. Requires a single shop.

No prior-period comparison is included; for a period-over-period delta, call twice with adjacent windows and subtract. Returns 503 when the aggregate times out — back off and retry rather than treating it as a failure.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": {
    "new_creators": 0,
    "gmv_generated": 0,
    "video_posts": 0,
    "orders": 0
  },
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  }
}

Responses

Daily series per creator

POST /creators/trends

Daily time series for up to 100 named creators — affiliate GMV, video GMV, videos posted, video views, units sold, and commission. Backs sparklines and per-creator trend comparisons.

Every series is aligned positionally with the days axis and zero-filled, so index i of any array corresponds to days[i]. Creators with no activity in the window appear with all-zero arrays rather than being omitted; handles that don't exist in this shop are listed in unresolved_handles instead.

Defaults to the trailing 28 days. Requires a single shop.

Body parameter

{
  "creator_handles": [
    "string"
  ],
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": {
    "property1": {
      "affiliate_gmv": [
        0
      ],
      "video_gmv": [
        0
      ],
      "videos_posted": [
        0
      ],
      "total_video_views": [
        0
      ],
      "units_sold": [
        0
      ],
      "commission": [
        0
      ]
    },
    "property2": {
      "affiliate_gmv": [
        0
      ],
      "video_gmv": [
        0
      ],
      "videos_posted": [
        0
      ],
      "total_video_views": [
        0
      ],
      "units_sold": [
        0
      ],
      "commission": [
        0
      ]
    }
  },
  "days": [
    "string"
  ],
  "unresolved_handles": [
    "string"
  ],
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  }
}

Responses

Weekly outreach funnel by creator tier

POST /creators/tier-performance

The outreach funnel — messages sent, sample requests, samples approved, videos posted — rolled up per creator GMV tier, one block per week.

Weeks run Sunday to Saturday and are labelled by the Saturday they end on (week_ending), matching how weekly client reports are cut. A week with no activity is still returned, as zeros.

All eight tiers L0-L7 are always present. A creator's tier comes from their ALL-TIME platform-wide GMV — the same basis as the Top Creators level badges — not from the GMV attributed inside the window. The gmv field on each row IS the windowed figure.

touches is outreach messages: three DMs to one creator counts three. reached is distinct creators. Single shop only — set x-shop-id to one shop ID.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "weeks": [
    {
      "week_start": "string",
      "week_ending": "string",
      "total": {
        "creators": 0,
        "reached": 0,
        "converted": 0,
        "conversion_rate": 0,
        "touches": 0,
        "sample_requests": 0,
        "samples_approved": 0,
        "videos_posted": 0,
        "gmv": 0
      },
      "tiers": [
        {
          "tier": "string",
          "creators": 0,
          "reached": 0,
          "converted": 0,
          "conversion_rate": 0,
          "touches": 0,
          "sample_requests": 0,
          "samples_approved": 0,
          "videos_posted": 0,
          "gmv": 0
        }
      ]
    }
  ]
}

Responses

Creator distribution by GMV level

GET /creators/levels

Distribution of creators by GMV tier (L0-L7). Matches the dashboard's 'Creators by Level' pie chart. Uses active creators from the date range (defaults to last 30 days). Pass start_date and end_date query params (YYYY-MM-DD) to customize the window. L0=$0, L1=<$5k, L2=$5k-$25k, L3=$25k-$60k, L4=$60k-$150k, L5=$150k-$400k, L6=$400k-$1M, L7=>$1M.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Get creator detail

GET /creators/{creator_handle}

Get detailed information for a single creator, including groups, products, and latest 10 videos (for full video list, use POST /creators/{creator_handle}/videos).

Parameters

Example responses

200 Response

{
  "data": {
    "creator_handle": "string",
    "follower_count": 0,
    "status": "string",
    "shop_gmv": 0,
    "overall_gmv": 0,
    "creator_level": "string",
    "overall_fulfillment_rate": 0,
    "shop_units_sold": 0,
    "shop_video_count": 0,
    "video_views": 0,
    "sample_received": 0,
    "commission_rate": 0,
    "est_commission": 0,
    "fulfillment_rate": 0,
    "tags": [
      "string"
    ],
    "product_id": "string",
    "product_title": "string",
    "updated_at": "string",
    "created_at": "string"
  },
  "groups": [],
  "products": [],
  "videos": [],
  "currency": "string"
}

Responses

List creator's videos

POST /creators/{creator_handle}/videos

Paginated list of videos by this creator in your shop.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "creator_id": "string",
      "title": "string",
      "video_url": "string",
      "tiktok_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

List creator's products

POST /creators/{creator_handle}/products

Products this creator is affiliated with in your shop.

Body parameter

{
  "page": 1,
  "page_size": 50
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_title": "string",
      "commission_rate": 0,
      "shop_units_sold": 0,
      "shop_gmv": 0,
      "status": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "shops_queried": [
    "string"
  ]
}

Responses

Products

Your products and their affiliate performance.

List products

POST /products/list

Product performance metrics aggregated over a date range. Defaults to the last 7 days if no dates are specified. Data is typically 2-3 days behind the current date. Each product also carries its TikTok Seller Center per-product metrics as sc_* fields: all-channel GMV with its per-channel breakdown (affiliate, seller video, seller live, product card, shop tab), plus orders, units sold, customers, impressions, clicks, CTR, conversion, AOV, GMV per 1,000 impressions, add-to-cart, and refunds. The sc_* fields are null for products not yet on the Seller Center sync.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "product_name": "string"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_name": "string",
      "gmv": 0,
      "units_sold": 0,
      "refund_units": 0,
      "video_count": 0,
      "sample_count": 0,
      "live_count": 0,
      "est_commission": 0,
      "product_status": "string",
      "sc_total_gmv": 0,
      "sc_orders": 0,
      "sc_units_sold": 0,
      "sc_customers": 0,
      "sc_aov": 0,
      "sc_impressions": 0,
      "sc_clicks": 0,
      "sc_ctr": 0,
      "sc_conversion": 0,
      "sc_gmv_per_1k_impr": 0,
      "sc_add_to_cart": 0,
      "sc_affiliate_gmv": 0,
      "sc_seller_video_gmv": 0,
      "sc_seller_live_gmv": 0,
      "sc_product_card_gmv": 0,
      "sc_shop_tab_gmv": 0,
      "sc_refunds": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

List product catalog with inventory

POST /products/catalog

The shop's merchandising catalog with current stock — for syncing products into an external CRM or ordering system. Sourced from TikTok's product catalog (refreshed roughly every 6 hours), NOT the affiliate performance data in POST /products/list.

Each product carries its product-level inventory (total_inventory, sku_count, out_of_stock_sku_count) and, by default, a nested skus[] array with per-SKU stock and variant attributes. Set include_skus=false for a lighter product-only payload.

All money is reported as integer minor currency units (cents) in the product's currency. Prices and stock are passed through exactly as TikTok reports them: product-level total_inventory and per-SKU inventory can legitimately differ during a sync, so do not assume total_inventory equals the sum of SKU inventories. There is no warehouse-level stock breakdown — inventory exists only at the product and SKU grain.

For incremental syncs, pass updated_since and key off each row's updated_at. Soft-deleted products are excluded.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "title",
  "sort_dir": "asc",
  "product_name": "string",
  "product_status": "string",
  "in_stock_only": false,
  "updated_since": "2019-08-24T14:15:22Z",
  "include_skus": true
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "shop_id": 0,
      "product_id": "string",
      "title": "string",
      "description": "string",
      "brand_name": "string",
      "category_chain": [
        null
      ],
      "primary_image_url": "string",
      "image_urls": [
        null
      ],
      "currency": "string",
      "price_min_cents": 0,
      "price_max_cents": 0,
      "total_inventory": 0,
      "sku_count": 0,
      "out_of_stock_sku_count": 0,
      "product_status": "string",
      "affiliate_status": 0,
      "is_cod_allowed": true,
      "tiktok_created_at": "string",
      "tiktok_updated_at": "string",
      "updated_at": "string",
      "skus": [
        {
          "sku_id": "string",
          "seller_sku": "string",
          "inventory": 0,
          "variants": [
            {
              "name": "string",
              "value_name": "string",
              "value_id": "string",
              "image_url": "string"
            }
          ],
          "updated_at": "string"
        }
      ]
    }
  ],
  "pagination": null,
  "shops_queried": [
    "string"
  ]
}

Responses

List product's creators

POST /products/{product_id}/creators

Creators affiliated with this product.

Body parameter

{
  "page": 1,
  "page_size": 50
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "follower_count": 0,
      "commission_rate": 0,
      "gmv": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "shops_queried": [
    "string"
  ]
}

Responses

List product's videos

POST /products/{product_id}/videos

Videos featuring this product.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "creator_id": "string",
      "title": "string",
      "video_url": "string",
      "tiktok_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Videos

Affiliate videos and performance metrics.

List videos

POST /videos/list

Affiliate videos and their performance metrics. Values represent lifetime totals per video (total views, total GMV, etc.). Data can be up to three days stale, given the delay in affiliate center.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "creator_id": "string",
  "creator_handle": "string",
  "product_id": "string",
  "product_ids": [
    "string"
  ],
  "min_gmv": 0,
  "min_views": 0
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "creator_id": "string",
      "title": "string",
      "video_url": "string",
      "tiktok_url": "string",
      "creator_handle": "string",
      "product_id": "string",
      "product_name": "string",
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "share_count": 0,
      "units_sold": 0,
      "video_gmv": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Creator video leaderboard

POST /videos/leaderboard

Creator-level shoppable-video leaderboard for a campaign window. Aggregates attributed video GMV and units per creator over a posted-date range (optionally restricted to specific product_ids), each with a per-product breakdown, ranked by total video GMV (default). Use this instead of paginating /videos/list + joining by hand: one row per creator with total_video_gmv, total_units_sold, qualifying_video_count (DISTINCT videos), and a products[] breakdown. min_gmv is a per-video-row threshold consistent with /videos/list. Multi-shop requests (x-shop-id: all or comma-separated) aggregate creators across shops, but only when every shop shares one currency — GMV cannot be summed across currencies, so a mixed-currency shop set is rejected (400); scope x-shop-id to a single currency/region.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "total_video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "product_ids": [
    "string"
  ],
  "min_gmv": 0
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_id": "string",
      "creator_handle": "string",
      "total_video_gmv": 0,
      "total_units_sold": 0,
      "qualifying_video_count": 0,
      "products": [
        {
          "product_id": "string",
          "product_name": "string",
          "video_gmv": 0,
          "units_sold": 0,
          "video_count": 0
        }
      ]
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Top videos with creative breakdown

POST /videos/creative

The shop's top videos ranked by GMV earned in the date range (defaults to the last 30 days, same ranking as /videos/performance), each enriched with the AI creative breakdown: hook, sell points, product niche, shot style, and videography. Use this to analyze WHY the top videos perform — not just how much they earned. Videos that haven't been analyzed yet keep their metrics and list the unavailable breakdown fields in creative.missing_fields; render those as 'not analyzed' rather than blank. Multi-shop requests (x-shop-id: all or comma-separated) mirror /videos/performance's semantics: one ranking across shops with a single top-level currency (USD fallback) — use a single shop when per-shop currency precision matters.

Body parameter

{
  "limit": 10,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "creator_handle": "string",
      "tiktok_url": "string",
      "video_gmv": 0,
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "order_count": 0,
      "posted_date": "string",
      "rank": 0,
      "creative": {
        "analyzed": true,
        "hook": {
          "text": "string",
          "classification": "string",
          "reasoning": "string"
        },
        "sell_points": [
          "string"
        ],
        "product_niche": "string",
        "shot_style": [
          "string"
        ],
        "videography": {
          "locations": [
            "string"
          ],
          "lighting": [
            "string"
          ],
          "product_showcase": [
            "string"
          ],
          "notes": "string"
        },
        "missing_fields": [
          "string"
        ]
      }
    }
  ],
  "currency": "string",
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "coverage": {
    "videos_returned": 0,
    "with_creative_analysis": 0
  },
  "total_count": 0,
  "message": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

Video performance (date-filtered)

POST /videos/performance

Top videos ranked by GMV or views earned within a specific date range. Unlike /videos/list (which shows lifetime totals), this endpoint uses daily performance data and matches the dashboard's 'Top Videos' section exactly. Defaults to the last 30 days. Use this for period-specific rankings, trend analysis, and correlating video performance with product sales.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "video_gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "creator_handle": "string",
  "min_gmv": 0,
  "min_views": 0
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "title": "string",
      "creator_handle": "string",
      "tiktok_url": "string",
      "video_gmv": 0,
      "views": 0,
      "like_count": 0,
      "comment_count": 0,
      "order_count": 0,
      "posted_date": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

List videos with retention / hook-quality metrics

GET /videos/retention

Your shop's videos with per-video completion rate (watch_finish_rate), exposure (impressions), views, CTR and engagement — the organic hook-quality signal.

TikTok exposes a 2-second view rate only for GMV Max ad creatives (video_view_rate_2s on /campaigns/{id}/creative-metrics); for organic videos the retention metric is completion, so use watch_finish_rate as the quality bar (min_watch_finish_rate filters to it). Ordered strongest-hook first.

Scope: videos in the shop's own Seller Center analytics (posted for the shop).

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "video_url": "string",
      "video_name": "string",
      "video_duration_s": 0,
      "publish_time": "2019-08-24T14:15:22Z",
      "creator_handle": "string",
      "creator_alias": "string",
      "views": 0,
      "impressions": 0,
      "clicks": 0,
      "ctr_rate": 0,
      "watch_finish_rate": 0,
      "likes": 0,
      "comments": 0,
      "shares": 0,
      "new_followers": 0,
      "gpm": 0,
      "revenue": 0,
      "currency": "string",
      "products": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  ],
  "pagination": {
    "total_count": 0,
    "page": 0,
    "page_size": 0,
    "total_pages": 0
  }
}

Responses

Video Intelligence

Per-video transcripts and AI creative analysis: how a video opens, its structure, on-screen text, detected products, scored creative features, and its bottom-of-funnel verdict.

Get one video's creative analysis

GET /videos/{video_id}/analysis

Reacher's AI analysis of a single video: the spoken transcript, a hook_summary of how it opens, the structure_outline of its beats, the on-screen text (OCR), the visual tags, the products detected on screen, and the scored creative features (hook in the first three seconds, product demo present, voiceover present, pace, and a content summary).

video_id is the value returned by POST /videos/list, POST /videos/performance and GET /crm/content.

Coverage is partial and grows over time: a video this shop owns that has not been analyzed yet returns 200 with analyzed: false and null fields, so absence is distinguishable from a bad id. Thumbnail-source analyses (analysis_source: thumbnail) carry no transcript and no motion features.

Set include_experimental=true to additionally receive features_experimental, the analyzer's full scored-feature block — richer, but unstable across analyzer versions.

Only videos belonging to the calling key's shop are readable; any other video_id returns 404. Single-shop only — set x-shop-id to one shop ID.

Parameters

Example responses

200 Response

{
  "data": {
    "video_id": "string",
    "analyzed": true,
    "analysis_source": "string",
    "analysis_version": 0,
    "analyzed_at": "2019-08-24T14:15:22Z",
    "transcript": "string",
    "transcript_language": "string",
    "transcript_duration_s": 0,
    "transcript_source": "string",
    "hook_summary": "string",
    "structure_outline": [
      "string"
    ],
    "on_screen_text": "string",
    "vision_tags": {},
    "detected_products": {},
    "features": {},
    "features_experimental": {}
  }
}

Responses

Get creative analysis for several videos

GET /videos/analysis

The batch form of GET /videos/{video_id}/analysis — same payload per video, up to 100 ids per call. Pass video_ids once per id (?video_ids=A&video_ids=B).

Unlike the single-video route this never 404s: ids that do not belong to this shop are listed in not_found, while owned-but-unanalyzed videos appear in data with analyzed: false. Use it to check analysis coverage across a set of videos in one round trip.

Only videos belonging to the calling key's shop are readable; any other video_id returns 404. Single-shop only — set x-shop-id to one shop ID.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "video_id": "string",
      "analyzed": true,
      "analysis_source": "string",
      "analysis_version": 0,
      "analyzed_at": "2019-08-24T14:15:22Z",
      "transcript": "string",
      "transcript_language": "string",
      "transcript_duration_s": 0,
      "transcript_source": "string",
      "hook_summary": "string",
      "structure_outline": [
        "string"
      ],
      "on_screen_text": "string",
      "vision_tags": {},
      "detected_products": {},
      "features": {},
      "features_experimental": {}
    }
  ],
  "not_found": [
    "string"
  ]
}

Responses

Get one video's bottom-of-funnel verdict

GET /videos/{video_id}/bof

Whether a video is bottom-of-funnel content — direct-response creative that pushes the viewer to buy now (discount, urgency, explicit call to action) rather than building awareness.

bof_status is the raw verdict (bof, not_bof, needs_review, pending) and bof_confidence scores it 0-100; is_bof is the displayable answer, true only for a bof verdict at confidence >= 90 — the same threshold behind the BOF badge and filter in the Reacher portal, so the API and the portal can never disagree about a video. matched_keywords, matched_patterns and matched_signals explain the verdict.

A video this shop owns that the classifier has no verdict for returns 200 with classified: false and is_bof: false; classification_status then says why (pending, no_transcript, or not_analyzed) — classified: false is a coverage state, not an error.

Only videos belonging to the calling key's shop are readable; any other video_id returns 404. Single-shop only — set x-shop-id to one shop ID.

Parameters

Example responses

200 Response

{
  "data": {
    "video_id": "string",
    "classified": true,
    "classification_status": "classified",
    "bof_status": "string",
    "bof_confidence": 0,
    "is_bof": true,
    "matched_signals": [
      "string"
    ],
    "matched_keywords": [
      "string"
    ],
    "matched_patterns": [
      "string"
    ],
    "classified_at": "2019-08-24T14:15:22Z"
  }
}

Responses

Samples

Sample request tracking and per-product breakdowns.

List sample requests

POST /samples/list

Track sample requests from creators in your shop. Shows only sample-related statuses. Data updates approximately every hour.

Each row includes the requesting creator's bio, categories, and email (sourced from the same regional creators table the AI Creator Search API reads), so consumers can score sample requests on brand/niche fit without a second API call. These fields are null when the creator has no row in the regional creators table.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "updated_at",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "status": "string",
  "creator_handle": "string",
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "product_id": "string",
      "product_title": "string",
      "status": "string",
      "gmv": 0,
      "units_sold": 0,
      "sample_received": 0,
      "updated_at": "string",
      "bio": "string",
      "categories": [
        "string"
      ],
      "email": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Sample metrics by product

POST /samples/by-product

Sample performance breakdown by product. Shows requests, approvals, and GMV per product. Data can be up to three days stale, given the delay in affiliate center.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "total_requests",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "product_id": "string",
      "product_name": "string",
      "total_requests": 0,
      "approved": 0,
      "sample_gmv": 0,
      "videos_from_samples": 0
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ]
}

Responses

Sample request stat cards

GET /samples/metrics

The four stat cards above the sample-request table: pendingReview (how many requests await a decision, plus how many of those are expiring soon), approvedInAutoProcess (samples auto-approved by an automation), completionRate (share of approved samples that produced content), and approvalTarget (usage against the shop's approval quota). The change metrics compare against the immediately preceding period of equal length.

dataFreshness reports how current the underlying sample data is — TikTok's sample feed lags, so surface it rather than presenting the counts as real-time.

Under a sku_ids filter, notScopableBySku names the cards that could not be narrowed — approvedInAutoProcess and approvalTarget, whose counters are product-grain — so treat those as unscoped rather than filtered.

date_from/date_to must be given together and bound request creation date. Single-shop only.

Parameters

Example responses

200 Response

{
  "pendingReview": {
    "count": 0,
    "expiringSoon": 0
  },
  "approvedInAutoProcess": {
    "count": 0,
    "changePct": 0,
    "changeDirection": "up"
  },
  "completionRate": {
    "rate": 0,
    "changePct": 0,
    "changeDirection": "up"
  },
  "approvalTarget": {
    "monthlyLimit": 0,
    "monthlyUsed": 0,
    "dailyTarget": 0,
    "dailyCurrent": 0,
    "dailyPct": 0,
    "onTrack": true
  },
  "dataFreshness": {
    "lastSyncedAt": "string",
    "isStale": false,
    "isRefreshing": false
  },
  "notScopableBySku": [
    "string"
  ]
}

Responses

Sample request pipeline funnel counts

GET /samples/pipeline-counts

How many sample requests sit at each stage of the fulfilment funnel: toReview → readyToShip → shipped → pendingContent → completed, plus cancelled. Also returns the shop's completionRate, its approvalTarget usage, the archivedCount, and expiringCount (requests about to lapse if no decision is made). approvalTarget is always shop-wide: it ignores product_ids and sku_ids.

Counts honour the same filters as the portal table, so a filtered funnel and a filtered list agree. They EXCLUDE requests hidden because the creator is archived (archivedCount.total is how many those are, and archivedCounts is unset here); for stage counts that include them, and so match TikTok's Affiliate Center, use GET /funnel/v2/counts. The portal's advanced numeric creator filters (GMV / views / post-rate bands) are not exposed here — use POST /samples/list and aggregate if you need those.

date_from/date_to must be given together. Single-shop only.

Parameters

Example responses

200 Response

{
  "counts": {
    "toReview": 0,
    "readyToShip": 0,
    "shipped": 0,
    "pendingContent": 0,
    "completed": 0,
    "cancelled": 0,
    "all": 0,
    "inShipment": 0,
    "posted": 0,
    "allApproved": 0,
    "overdue": 0,
    "rejected": 0,
    "expired": 0,
    "ignored": 0
  },
  "archivedCounts": {
    "toReview": 0,
    "readyToShip": 0,
    "shipped": 0,
    "pendingContent": 0,
    "completed": 0,
    "cancelled": 0,
    "all": 0,
    "inShipment": 0,
    "posted": 0,
    "allApproved": 0,
    "overdue": 0,
    "rejected": 0,
    "expired": 0,
    "ignored": 0
  },
  "completionRate": 0,
  "approvalTarget": {
    "limit": 0,
    "used": 0
  },
  "archivedCount": {
    "creators": 0,
    "products": 0,
    "total": 0
  },
  "expiringCount": 0,
  "dataFreshness": {
    "lastSyncedAt": "string",
    "isStale": false,
    "isRefreshing": false
  }
}

Responses

Per-product sample usage this month

GET /samples/product-usage

How many samples each product has consumed in the current calendar month (productId → usedThisMonth). This is the counter the portal checks per-product sample limits against, so it answers 'which product is about to run out of its monthly allowance'.

Products with no usage this month are omitted. Single-shop only.

Example responses

200 Response

{
  "data": [
    {
      "productId": "string",
      "usedThisMonth": 0
    }
  ]
}

Responses

List auto-approval product configs

GET /samples/product-config

Per-product sample auto-approval rules for this shop: monthly sample limit, daily approval target, the minimum GMV / post-rate a requester must clear, the ideal-creator profiles they must match, and how many samples of that product have already gone out this month (usedThisMonth). Products with no row here follow the shop-wide quota only. Read-only; requires a single shop.

Example responses

200 Response

{
  "data": [
    {
      "id": 0,
      "productId": "string",
      "productName": "string",
      "sku": "string",
      "productImage": "string",
      "monthlySampleLimit": 0,
      "dailyApprovalTarget": 0,
      "usedThisMonth": 0,
      "idealCreatorProfiles": [
        {
          "id": 0,
          "name": "string"
        }
      ],
      "config": {
        "minGmv": 0,
        "minPostRate": 0
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Responses

Create auto-approval product config

POST /samples/product-config

Create the auto-approval rule for one product. Requires read_write scope and a single shop. productId must not already have a config in this shop — a duplicate returns 409 PRODUCT_CONFIG_EXISTS; use PUT /samples/product-config/{config_id} to change an existing rule. idealCreatorProfileIds that don't belong to this shop are dropped rather than linked.

Body parameter

{
  "monthlySampleLimit": 0,
  "dailyApprovalTarget": 0,
  "idealCreatorProfileIds": [
    0
  ],
  "config": {
    "minGmv": 0,
    "minPostRate": 0
  },
  "productId": "string"
}

Parameters

Example responses

201 Response

{
  "success": true,
  "data": {
    "id": 0,
    "productId": "string",
    "productName": "string",
    "sku": "string",
    "productImage": "string",
    "monthlySampleLimit": 0,
    "dailyApprovalTarget": 0,
    "usedThisMonth": 0,
    "idealCreatorProfiles": [
      {
        "id": 0,
        "name": "string"
      }
    ],
    "config": {
      "minGmv": 0,
      "minPostRate": 0
    },
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

Update auto-approval product config

PUT /samples/product-config/{config_id}

Partially update one product's auto-approval rule. Requires read_write scope and a single shop. Omitted fields keep their current value; an explicit null clears the setting. config_id is re-checked against this shop before the write — a config belonging to another shop returns 404, never a cross-shop update.

Body parameter

{
  "monthlySampleLimit": 0,
  "dailyApprovalTarget": 0,
  "idealCreatorProfileIds": [
    0
  ],
  "config": {
    "minGmv": 0,
    "minPostRate": 0
  }
}

Parameters

Example responses

200 Response

{
  "success": true,
  "data": {
    "id": 0,
    "productId": "string",
    "productName": "string",
    "sku": "string",
    "productImage": "string",
    "monthlySampleLimit": 0,
    "dailyApprovalTarget": 0,
    "usedThisMonth": 0,
    "idealCreatorProfiles": [
      {
        "id": 0,
        "name": "string"
      }
    ],
    "config": {
      "minGmv": 0,
      "minPostRate": 0
    },
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

Delete auto-approval product config

DELETE /samples/product-config/{config_id}

Remove one product's auto-approval rule. The product falls back to the shop-wide quota; nothing already approved is affected. Requires read_write scope and a single shop. config_id is re-checked against this shop before the delete — a foreign ID returns 404.

Parameters

Example responses

200 Response

{
  "success": true
}

Responses

Get shop sample quota

GET /samples/quota

The shop-wide monthly sample ceiling. monthlyLimit is null when the shop has never set one, which means unlimited — per-product limits still apply. Read-only; requires a single shop.

Example responses

200 Response

{
  "success": true,
  "data": {
    "shopId": 0,
    "monthlyLimit": 0,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

Update shop sample quota

PUT /samples/quota

Set the shop-wide monthly sample ceiling. Requires read_write scope and a single shop. monthlyLimit must be present: a number caps the shop, null removes the cap. The shop is taken from the authenticated key / x-shop-id, never from the body.

Body parameter

{
  "monthlyLimit": 0
}

Parameters

Example responses

200 Response

{
  "success": true,
  "data": {
    "shopId": 0,
    "monthlyLimit": 0,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

List ideal-creator profiles

GET /samples/profiles

Reusable creator-quality criteria (minimum post rate, GMV range, minimum views, minimum followers) that product configs point at when deciding whether to auto-approve a sample request. linkedProducts counts how many product configs reference each profile. Read-only; requires a single shop.

Example responses

200 Response

{
  "data": [
    {
      "id": 0,
      "name": "string",
      "criteria": {
        "minPostRate": 0,
        "gmvRange": {
          "min": 0,
          "max": 0
        },
        "minViews": 0,
        "minFollowers": 0
      },
      "linkedProducts": 0,
      "createdAt": "string",
      "updatedAt": "string"
    }
  ]
}

Responses

Create ideal-creator profile

POST /samples/profiles

Create a reusable ideal-creator profile for this shop. Requires read_write scope and a single shop. Names are unique per shop — a duplicate returns 409 PROFILE_NAME_EXISTS. Link the new profile to products via idealCreatorProfileIds on a product config.

Body parameter

{
  "name": "string",
  "criteria": {
    "minPostRate": 0,
    "gmvRange": {
      "min": 0,
      "max": 0
    },
    "minViews": 0,
    "minFollowers": 0
  }
}

Parameters

Example responses

201 Response

{
  "success": true,
  "data": {
    "id": 0,
    "name": "string",
    "criteria": {
      "minPostRate": 0,
      "gmvRange": {
        "min": 0,
        "max": 0
      },
      "minViews": 0,
      "minFollowers": 0
    },
    "linkedProducts": 0,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

Update ideal-creator profile

PUT /samples/profiles/{profile_id}

Replace a profile's name and criteria. Requires read_write scope and a single shop. profile_id is re-checked against this shop before the write — a profile belonging to another shop returns 404. Renaming onto an existing name returns 409 PROFILE_NAME_EXISTS. Product configs linked to this profile pick up the new criteria immediately.

Body parameter

{
  "name": "string",
  "criteria": {
    "minPostRate": 0,
    "gmvRange": {
      "min": 0,
      "max": 0
    },
    "minViews": 0,
    "minFollowers": 0
  }
}

Parameters

Example responses

200 Response

{
  "success": true,
  "data": {
    "id": 0,
    "name": "string",
    "criteria": {
      "minPostRate": 0,
      "gmvRange": {
        "min": 0,
        "max": 0
      },
      "minViews": 0,
      "minFollowers": 0
    },
    "linkedProducts": 0,
    "createdAt": "string",
    "updatedAt": "string"
  }
}

Responses

Delete ideal-creator profile

DELETE /samples/profiles/{profile_id}

Delete a profile and unlink it from every product config that referenced it — those products keep their other criteria. Requires read_write scope and a single shop. profile_id is re-checked against this shop before the delete — a foreign ID returns 404.

Parameters

Example responses

200 Response

{
  "success": true
}

Responses

Automations

Automation performance and outreach metrics.

Automation portfolio stats for one shop

GET /automations/stats

Shop-level overview of your automations: total_automations, live_automations, archived_automations, and the split between regular_automations and email_automations, plus three breakdowns — by_type (Target Collab, Message, Email, Sample Request Processing, …), by_status (running / stopped / completed / …) and by_type_and_state (each type split live vs archived) — and an aggregated metrics block rolled up across the shop's automations.

This is the portfolio view; use POST /automations/list for the per-automation rows behind it. Pass crm_only=true to count only automations backed by a CRM group. Single-shop only.

Parameters

Example responses

200 Response

{
  "total_automations": 0,
  "live_automations": 0,
  "archived_automations": 0,
  "email_automations": 0,
  "regular_automations": 0,
  "by_type": {
    "property1": 0,
    "property2": 0
  },
  "by_status": {
    "property1": 0,
    "property2": 0
  },
  "by_type_and_state": {
    "property1": {
      "property1": 0,
      "property2": 0
    },
    "property2": {
      "property1": 0,
      "property2": 0
    }
  },
  "metrics": {
    "total_creators_reached": 0,
    "total_sample_requests": 0,
    "total_creators": 0,
    "total_emails_sent": 0,
    "total_dm_messages_sent": 0,
    "total_dm_response_count": 0,
    "total_reply_rate": 0,
    "total_email_open_count": 0,
    "total_email_reply_count": 0,
    "total_email_open_rate": 0,
    "total_email_reply_rate": 0
  }
}

Responses

Performance rollup for one automation

GET /automations/{automation_id}/metrics

The precomputed performance rollup for ONE automation — the numbers the portal shows above the automation's tabs.

tab_counts carries the creator-tracker, sample-request and video counts (the tracker count already excludes creators on the automation's current omit lists, so it matches the tab it labels). top_line_metrics carries creators_reached, dm_response_count and reply_rate, unique_creators_posted and post_rate, videos_count, total_revenue (GMV), and total views / shares / likes.

Check data_available first. It is false when the rollup aggregator has not yet computed a row for this automation — the zeros are then 'not computed yet', not 'nothing happened'. top_line_metrics is null for automation types that have no full-funnel view (is_full_view: false).

Single-shop only; the automation must belong to that shop or this returns 404.

Parameters

Example responses

200 Response

{
  "data_available": true,
  "is_full_view": false,
  "tab_counts": {
    "creator_tracker_count": 0,
    "sample_request_count": 0,
    "video_count": 0,
    "reply_count": 0,
    "unread_count": 0
  },
  "top_line_metrics": {
    "creators_reached": 0,
    "dm_response_count": 0,
    "reply_rate": 0,
    "unique_creators_posted": 0,
    "post_rate": 0,
    "videos_count": 0,
    "total_revenue": 0,
    "total_views": 0,
    "total_shares": 0,
    "total_likes": 0
  }
}

Responses

List automations

POST /automations/list

Your automations with performance and outreach metrics. Includes creators reached, sample requests, videos posted, and GMV. reply_rate is populated for Running, Stopped, and Completed automations.

Body parameter

{
  "page": 1,
  "page_size": 50,
  "sort_by": "gmv",
  "sort_dir": "asc",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "automation_type": "string",
  "status": "string",
  "show_archived": false,
  "created_via": [
    "string"
  ],
  "exclude_created_via": [
    "string"
  ]
}

Parameters

Example responses

200 Response

{
  "data": [
    {
      "automation_id": 0,
      "automation_name": "string",
      "automation_type": "string",
      "is_evergreen": false,
      "status": "string",
      "status_message": "string",
      "gmv": 0,
      "sample_requests": 0,
      "accepted_requests": 0,
      "videos_posted": 0,
      "videos_converted": 0,
      "creators_reached": 0,
      "target_collab_cleanup_creators_reached": 0,
      "dm_response_count": 0,
      "reply_rate": 0,
      "skipped": 0,
      "total_creators": 0,
      "creators_remaining": 0,
      "created_at": "string",
      "completed_at": "string",
      "created_via": "string"
    }
  ],
  "currency": "string",
  "pagination": null,
  "date_range": {
    "start_date": "string",
    "end_date": "string"
  },
  "shops_queried": [
    "string"
  ],
  "aggregate": {
    "creators_reached": 0,
    "tc_invites": 0,
    "tc_invites_creator_count": 0,
    "creators_messaged": 0,
    "emails_sent": 0,
    "sample_request": 0,
    "sample_approved": 0,
    "videos_posted": 0,
    "videos_converted": 0,
    "spark_codes": 0,
    "added_showcase_affiliates": 0,
    "accepted_tc_count": 0,
    "tc_showcase_creator_count": 0,
    "tc_content_creator_count": 0,
    "tc_acceptance_rate": 0,
    "coverage_through": "string"
  },
  "excluded": {}
}

Responses

Region-specific filter options

GET /automations/filters

Returns the filter options (categories, GMV ranges, follower segments, engagement / view tiers, content-style options, etc.) valid for the given shop region. Use the response to drive filter dropdowns or to validate creators_to_include.filters values before submitting a create request.

Region differences:

• Numeric ranges use the region's currency (£ for UK, $ for US, € for EU regions, R$ for BR, etc.).
• Category lists differ — UK has a smaller category set than US.
• AI-search filters (face_visibility / content_style / personality_tone / etc.) are only fully populated for US today; other regions surface a subset.
• Ethnicity filter is available globally regardless of region.

Supported regions: US, UK, IE, MX, DE, FR, ES, BR, IT, GLOBAL (alias for US).

Parameters

Example responses

200 Response

null

Responses

Response Schema

Outreach send capacity for this shop

GET /automations/outreach-capacity

Current outreach send-capacity for a single shop, so callers can pre-check before sending TC invites / DMs and schedule retries when capacity frees.

Two independent limits govern outreach:

• Daily per-shop throttle counted in UTC (resets at 00:00 UTC — see daily_window_resets_at). daily_creators_used counts actual sends only (skipped/creator_not_found invites do not count). The daily ceiling is plan/TikTok-dependent and is not returned as a single number; daily_limit_throttled flags when the shop is currently paused by it.
• TikTok's outreach quota, enforced TikTok-side and read from TikTok's own quota endpoint — see outreach_quota for the consumption, ceiling and refresh instant. It counts connections shop-wide, so it includes outreach not sent through Reacher. Most shops are on a weekly PERIOD quota; some hold a BONUS grant that does not roll, so check outreach_quota.quota_type before calling it weekly. Null when the shop has no synced quota — null means unknown, never zero. weekly_limit_throttled flags when paused by the limit.

The daily pool is shared between the automation engine and direct POST /target-collabs invites. Requires a single shop.

Example responses

200 Response

{
  "shop_id": 0,
  "daily_creators_used": 0,
  "daily_window_resets_at": "string",
  "concurrent_automations_running": 0,
  "max_concurrent_automations": 0,
  "daily_limit_throttled": true,
  "weekly_limit_throttled": true,
  "outreach_quota": {
    "quota_type": "string",
    "used": 0,
    "limit": 0,
    "remaining": 0,
    "unlimited": true,
    "resets_at": "string",
    "gmv_tier": "string",
    "gmv_level_rule": [
      null
    ]
  }
}

Responses

Get automation detail

GET /automations/{automation_id}

Detailed automation data with performance metrics.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "is_evergreen": false,
    "status": "string",
    "status_message": "string",
    "gmv": 0,
    "sample_requests": 0,
    "accepted_requests": 0,
    "videos_posted": 0,
    "videos_converted": 0,
    "creators_reached": 0,
    "target_collab_cleanup_creators_reached": 0,
    "dm_response_count": 0,
    "reply_rate": 0,
    "skipped": 0,
    "total_creators": 0,
    "creators_remaining": 0,
    "created_at": "string",
    "completed_at": "string",
    "created_via": "string"
  },
  "creators_remaining": 0,
  "details": {
    "messaging": {
      "creator_message": "string",
      "message_type": "string",
      "message_sequence": [
        {
          "message_type": "string",
          "message_entry": "string",
          "product_id": "string",
          "days_after_previous": 0,
          "has_image": true
        }
      ],
      "follow_up_steps": [
        {
          "message_type": "string",
          "message_entry": "string",
          "product_id": "string",
          "days_after_previous": 0,
          "has_image": true
        }
      ],
      "personalization": {},
      "ai_custom_qa": [
        null
      ],
      "spark_code_form": {}
    },
    "target_collab": {
      "invitation_name": "string",
      "invitation_message": "string",
      "valid_until": "string",
      "content_type": "string",
      "products": [
        {
          "product_id": "string",
          "product_name": "string",
          "commission_rate": 0,
          "shop_min_commission": 0,
          "shop_ads_commission_rate": 0
        }
      ],
      "offer_free_samples": true,
      "auto_approve_samples": true,
      "auto_resolve_conflicts": "string",
      "support_contact_email": "string",
      "support_contact_phone": "string",
      "invite_start_before_days": "string",
      "invite_expire_after_days": "string"
    },
    "schedule": {
      "daily_caps": {
        "property1": 0,
        "property2": 0
      },
      "start_time": "string",
      "timezone": "string"
    },
    "targeting": {
      "creator_source_type": "string",
      "include_lists": [
        "string"
      ],
      "include_uploads": [
        null
      ],
      "crm_group_id": "string",
      "exclude_lists": [
        "string"
      ],
      "exclude_crm_groups": [
        null
      ],
      "exclude_previously_messaged": true,
      "filters": {},
      "ai_search_filters": {}
    }
  },
  "currency": "string"
}

Responses

Update automation

PATCH /automations/{automation_id}

Partial update across all 4 types. Cannot change automation_type, shop, lifecycle state, or system fields. Idempotency-Key optional; X-Dry-Run: true supported.

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "community": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "target_collab": {
    "invitation_name": "string",
    "valid_until": "2019-08-24",
    "message": "string",
    "products": [
      {
        "product_id": "string",
        "commission_rate": 1,
        "shop_min_commission": 1,
        "shop_ads_commission_rate": 1
      }
    ],
    "content_type": "no_preference",
    "sample_policy": {
      "offer_free_samples": true,
      "auto_approve": true,
      "send_to": "brand_recipient"
    },
    "support_contact": {
      "email": "string",
      "phone": "string"
    },
    "lock_receivers_profiles": true
  },
  "dm_config": {
    "spark_code": {
      "only_collect_creator_information": false,
      "spark_code_submission_url": "string"
    }
  },
  "sample_request": {
    "action": "approve",
    "rejection_reason": "NOT_MATCH",
    "approval_message": "string",
    "rejection_message": "string",
    "message_images": [
      "string"
    ],
    "products": {
      "include_all_products": false,
      "selected_products": [
        {
          "product_id": "string",
          "max_approvals_per_week": 10000
        }
      ],
      "weekly_auto_approval_per_product": 1
    },
    "minimum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "maximum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "auto_approval_settings": {
      "enabled": false,
      "total_weekly_approved_sample_limit": 1,
      "always_approve_status": "string",
      "always_approve_from_lists_ids": [
        0
      ]
    },
    "target_list": [
      0
    ]
  },
  "ai_enabled": true,
  "is_evergreen": true,
  "end_date": "2019-08-24",
  "business_hours_timezone": "string",
  "email_sent_per_day": 1,
  "subject": "string",
  "body": "string"
}

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Delete automation

DELETE /automations/{automation_id}

Soft-delete (state=archived). Reversible only by Reacher support. Calling on already-archived returns 200 with already_archived: true.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Per-creator outcome ledger

GET /automations/{automation_id}/creators

Per-creator outcomes for ONE automation: which creators got an invite/DM submitted, which were skipped (and why), which were previously invited, etc. This is the authoritative per-creator answer to 'what happened to each invite' — backed by the always-present target_collabs / Messages / skipped_creators tables, so it stays populated even after the aggregate creators_reached / skipped counters on the list/detail responses age out (those read from a stats view that only retains recently-active automations).

Queued ≠ delivered. An invite_submitted / outreach_sent outcome means Reacher's worker submitted the invite/DM through the same browser-automation path the portal uses. TikTok does not return a per-creator inbox-delivery receipt, so this is the most authoritative delivery signal available — not a confirmed inbox event. Requires a single shop.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator_handle": "string",
      "outcome": "string",
      "status": "string",
      "detail": "string",
      "skip_reason": "string",
      "invitation_id": "string"
    }
  ],
  "summary": {
    "total": 0,
    "invite_submitted": 0,
    "outreach_sent": 0,
    "previously_invited": 0,
    "invite_removed": 0,
    "skipped": 0,
    "unknown": 0
  },
  "pagination": null
}

Responses

Automation message templates

GET /automations/{automation_id}/messages

The message copy configured on one automation, flattened into a uniform shape regardless of automation type: the TC invite template (tc_invite_message), the ordered DM sequence (message_sequence — array order is send order), follow-up steps, and AI-chatbot Q&A. Placeholders (e.g. {{creators username}}) are NOT substituted — this is the template. For the exact per-creator text that was actually sent, use GET /automations/{automation_id}/sent-messages. Requires a single shop.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "automation_name": "string",
  "automation_type": "string",
  "tc_invite_message": "string",
  "message_sequence": [
    null
  ],
  "follow_up_steps": [
    null
  ],
  "ai_custom_qa": [
    null
  ],
  "personalization": {
    "enabled": false,
    "tone": "string",
    "fallback_message": "string",
    "offer_discussion": "string",
    "product_description": "string",
    "product_selling_points": "string",
    "word_counts": {
      "property1": 0,
      "property2": 0
    },
    "name_source": "string"
  }
}

Responses

Exact sent message copy (grouped by creator)

GET /automations/{automation_id}/sent-messages

What this automation actually sent, with honest coverage semantics:

• dm_sent — the exact rendered DM text per creator (placeholders substituted at send time), grouped by creator, most recently messaged first. Filter with creator_handle; page depth with creator_limit / messages_per_creator.
• tc_sent — Target-Collab invitation batches (who was invited, when, status) plus the invite template. TikTok TC invites are sent from the template and the per-creator rendered text is not stored — exact_copy: false and coverage_note state this explicitly. When the automation is a campaign's TC automation, campaign carries the link.

Hybrid automations (Message + TC) populate both sections. Empty sections carry an explicit message instead of blank lists. Read-only. Requires a single shop.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "automation_name": "string",
  "automation_type": "string",
  "template": {
    "automation_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "tc_invite_message": "string",
    "message_sequence": [
      null
    ],
    "follow_up_steps": [
      null
    ],
    "ai_custom_qa": [
      null
    ],
    "personalization": {
      "enabled": false,
      "tone": "string",
      "fallback_message": "string",
      "offer_discussion": "string",
      "product_description": "string",
      "product_selling_points": "string",
      "word_counts": {
        "property1": 0,
        "property2": 0
      },
      "name_source": "string"
    }
  },
  "dm_sent": {
    "exact_copy": true,
    "groups": [
      {
        "creator_name": "string",
        "creator_id": "string",
        "last_sent_at": "string",
        "messages": [
          {
            "content": "string",
            "sent_at": "string",
            "status": "string"
          }
        ]
      }
    ],
    "creators_returned": 0,
    "total_creators": 0,
    "total_messages": 0,
    "message": "string"
  },
  "tc_sent": {
    "exact_copy": false,
    "coverage_note": "string",
    "template_text": "string",
    "placeholders_present": false,
    "invitations": [
      {
        "sent_at": "string",
        "status": "string",
        "creator_count": 0,
        "creators": [
          "string"
        ],
        "creators_truncated": false,
        "expiration_date": "string"
      }
    ],
    "invitations_returned": 0,
    "total_invitations": 0,
    "total_creators_invited": 0,
    "status_breakdown": {
      "property1": 0,
      "property2": 0
    },
    "campaign": {
      "campaign_id": 0,
      "campaign_name": "string"
    },
    "message": "string"
  },
  "message": "string"
}

Responses

Create Target Collab automation

POST /automations/target-collab

Create a Target Collab (TC) invitation automation with optional follow-up DMs. Required: read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting.

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "community": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "target_collab": {
    "invitation_name": "string",
    "valid_until": "2019-08-24",
    "message": "string",
    "products": [
      {
        "product_id": "string",
        "commission_rate": 1,
        "shop_min_commission": 1,
        "shop_ads_commission_rate": 1
      }
    ],
    "content_type": "no_preference",
    "sample_policy": {
      "offer_free_samples": false,
      "auto_approve": false,
      "send_to": "brand_recipient"
    },
    "support_contact": {
      "email": "string",
      "phone": "string"
    }
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "ai_enabled": false,
  "end_date": "2019-08-24",
  "auto_resolve_conflicts": "SKIP_ALL",
  "is_evergreen": false,
  "business_hours_timezone": "string"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create TC Cleanup automation

POST /automations/tc-cleanup

Create a TC Cleanup utility automation — re-targets creators in this shop who received a TC invite from a prior automation but didn't accept it. Conceptually closer to sample_request than to the proactive TC outreach types: products + creator selection only, no messages, no follow-ups. Required: read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting.

Body parameter

{
  "automation_name": "string",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "community": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "products": [
    {
      "product_id": "string",
      "commission_rate": 1,
      "shop_min_commission": 1,
      "shop_ads_commission_rate": 1
    }
  ],
  "invite_start_before_days": 1,
  "invite_expire_after_days": 1,
  "end_date": "2019-08-24"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create DM automation

POST /automations/dm

Create a Direct Message automation. The mode field selects between 4 variants: vanilla (text-only), with_image, with_product_card, spark_code (collect TikTok spark codes via form). Each mode has specific addon and config requirements — see model schema.

Body parameter

{
  "automation_name": "string",
  "mode": "vanilla",
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_include": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "filters": {
      "product_categories": [
        "string"
      ],
      "follower_count": {
        "min": 0,
        "max": 0
      },
      "creator_ethnicity": [
        "string"
      ],
      "gender": [
        "string"
      ],
      "age_range": [
        "string"
      ],
      "languages": [
        "string"
      ],
      "community": [
        "string"
      ],
      "gmv": {
        "min": 0,
        "max": 0
      },
      "units_sold": {
        "min": 0,
        "max": 0
      },
      "average_views": {
        "min": 0,
        "max": 0
      },
      "engagement_rate": {
        "min": 0,
        "max": 0
      },
      "post_rate": {
        "min": 0,
        "max": 0
      },
      "video_gpm": {
        "min": 0,
        "max": 0
      },
      "live_gpm": {
        "min": 0,
        "max": 0
      },
      "follower_age": [
        "string"
      ],
      "follower_gender": [
        "string"
      ],
      "face_visibility": [
        "string"
      ],
      "content_style": [
        "string"
      ],
      "production_quality": [
        "string"
      ],
      "personality_tone": [
        "string"
      ],
      "body_type": [
        "string"
      ],
      "hair_type": [
        "string"
      ]
    },
    "crm_group_id": "string",
    "crm_group_entered_after": "2019-08-24",
    "crm_group_entered_before": "2019-08-24"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "messages": [
    {
      "type": "message",
      "body": "string",
      "image_url": "string",
      "product_id": "string",
      "submission_url_slug": "string"
    }
  ],
  "follow_ups": [
    {
      "delay_days": 30,
      "addons": [
        {
          "type": "message",
          "body": "string",
          "image_url": "string",
          "product_id": "string",
          "submission_url_slug": "string"
        }
      ]
    }
  ],
  "dm_config": {
    "spark_code": {
      "only_collect_creator_information": false,
      "spark_code_submission_url": "string"
    }
  },
  "personalization": {
    "enabled": true,
    "tone": "engaging",
    "fallback_message": "string",
    "offer_discussion": "",
    "product_description": "",
    "product_selling_points": "",
    "word_counts": {
      "property1": 0,
      "property2": 0
    },
    "name_source": "first_name"
  },
  "ai_enabled": false,
  "end_date": "2019-08-24",
  "is_evergreen": false,
  "business_hours_timezone": "string"
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Duplicate an automation

POST /automations/{automation_id}/duplicate

Create a copy of an existing automation you own — same audience, config, and schedule — as a NEW automation in the STOPPED state. The copy never sends until it is explicitly started in the portal. Requires read_write scope and an Idempotency-Key.

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create Email automation

POST /automations/email

Create an outbound email automation. Different recipient model from outreach — use selection_mode: mailing_list (with vault list IDs or upload emails inline) OR selection_mode: filters (creator search criteria). An email_account_id may back several active email automations. Each one adds to that inbox's daily send volume, and the daily cap is applied per automation, so heavy reuse risks provider throttling or spam classification.

Body parameter

{
  "automation_name": "string",
  "email_account_id": 0,
  "subject": "string",
  "body": "string",
  "selection_mode": "mailing_list",
  "mailing_list": {
    "list_upload_emails": [
      "string"
    ],
    "lists_selected": [
      "string"
    ]
  },
  "filters": {
    "min_creator_gmv": 0,
    "min_followers": 0,
    "min_engagement_rate": 1,
    "min_avg_views": 0,
    "regions": [
      "string"
    ],
    "categories": [
      "string"
    ]
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  },
  "attachments": [
    {
      "name": "string",
      "url": "string"
    }
  ]
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Create Sample Request auto-processing automation

POST /automations/sample-request

Auto-approve OR auto-reject incoming TikTok Shop sample requests by criteria. Side-effect: a CRM Group is internally created from the minimum_performance_criteria so creator membership stays dynamic. The new crm_group_id is returned in side_effects. If CRM-group creation fails, the automation still creates (logged + Sentry breadcrumb). Sample request type uses target_list (vault list IDs) instead of creators_to_include.

Body parameter

{
  "automation_name": "string",
  "sample_request": {
    "action": "approve",
    "rejection_reason": "NOT_MATCH",
    "approval_message": "string",
    "rejection_message": "string",
    "message_images": [
      "string"
    ],
    "products": {
      "include_all_products": false,
      "selected_products": [
        {
          "product_id": "string",
          "max_approvals_per_week": 10000
        }
      ],
      "weekly_auto_approval_per_product": 1
    },
    "minimum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "maximum_performance_criteria": {
      "followers": 0,
      "avg_views": 0,
      "engagement_rate": 1,
      "post_rate": 1,
      "creator_gmv_30_days": 0,
      "gmv_per_sample": 0
    },
    "auto_approval_settings": {
      "enabled": false,
      "total_weekly_approved_sample_limit": 1,
      "always_approve_status": "string",
      "always_approve_from_lists_ids": [
        0
      ]
    },
    "target_list": [
      0
    ]
  },
  "schedule": {
    "Monday_maxCreators": 0,
    "Tuesday_maxCreators": 0,
    "Wednesday_maxCreators": 0,
    "Thursday_maxCreators": 0,
    "Friday_maxCreators": 0,
    "Saturday_maxCreators": 0,
    "Sunday_maxCreators": 0,
    "start_time": "string",
    "end_time": "string",
    "timezone": "string"
  },
  "creators_to_exclude": {
    "list_upload": [
      "string"
    ],
    "lists_selected": [
      "string"
    ],
    "crm_groups": [
      "string"
    ],
    "exclude_previously_messaged": false
  }
}

Parameters

Example responses

201 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Start automation

POST /automations/{automation_id}/start

Transition automation to running. Idempotent — already-running returns 200. Rejects with 422 AUTOMATION_NOT_STARTABLE when the automation can never run as configured (no schedule day with maxCreators > 0, or valid_until/end_date already passed) — this prevents the 'start succeeded but nothing ever sends' trap.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Stop automation

POST /automations/{automation_id}/stop

Transition automation to stopped. Idempotent.

Parameters

Example responses

200 Response

{
  "data": {
    "automation_id": 0,
    "shop_id": 0,
    "automation_name": "string",
    "automation_type": "string",
    "automation_status": "string",
    "state": "string",
    "config": {},
    "schedule": {},
    "creators_to_include": {},
    "creators_to_exclude": {},
    "crm_group_id": "string",
    "ai_enabled": false,
    "end_date": "string",
    "created_at": "string",
    "updated_at": "string",
    "created_via": "string",
    "side_effects": {}
  },
  "dry_run": false,
  "side_effects": {}
}

Responses

Personalization

AI-personalized outreach (CORE-4857): preview the message a creator would receive, resolve product blocks, retone copy, and read fallback stats + per-creator sent history. Configure it on a DM via the personalization block of POST /automations/dm. Single-shop only.

Preview the personalized message a single creator would receive

POST /personalization/preview

Generate the AI personalization blocks for one creator and return the fully assembled message — exactly what a send with the same configuration would ship. When the creator has too little signal to personalize, the brand fallback_message is returned instead (is_fallback: true).

Content Discussion and Product Discussion are AI-generated from the creator's own signals; Product Description / Selling Points / Offer are the fixed strings you pass in (resolve product blocks first via POST /personalization/product-blocks). Region and brand name are taken from the shop (brand name defaults to the shop name).

API previews are stateless: nothing is stored, and a later send generates its own copy (or reuses a lock approved in the Reacher portal composer). Generation endpoints share a separate quota (20/min, 500/hr per key). Requires a single shop.

Body parameter

{
  "creator": {
    "creator_id": "string",
    "creator_handle": "string",
    "creator_first_name": ""
  },
  "message_body": "string",
  "tone": "engaging",
  "fallback_message": "string",
  "brand_name": "",
  "product_description": "",
  "product_selling_points": "",
  "offer_discussion": "",
  "word_counts": {
    "property1": 0,
    "property2": 0
  },
  "name_source": "first_name"
}

Parameters

Example responses

200 Response

{
  "creator_id": "string",
  "message": "string",
  "is_fallback": true,
  "blocks_used": [
    "string"
  ]
}

Responses

Resolve product description + derive selling points

POST /personalization/product-blocks

Resolve the two product-sourced personalization blocks for one of your products: [Product Description] (the product's own catalog text) and [Product Selling Points] (2–3 concrete selling points DERIVED from the product's real title/description/attributes — never invented). Use the returned strings verbatim in POST /personalization/preview and in the personalization block of POST /automations/dm, so preview and send share the same fixed copy.

Both blocks degrade to empty strings (the block simply drops out of the message) ONLY when the product isn't in this shop's catalog or has too little grounded content; a failed lookup (transient database error) returns 500 instead, so empty strings are always a true statement about the product, never an outage artifact — safe to store. Requires a single shop.

Body parameter

{
  "product_id": "string"
}

Parameters

Example responses

200 Response

{
  "product_description": "",
  "product_selling_points": ""
}

Responses

Rewrite a message body in a new tone

POST /personalization/retone

Rewrite the shared message body in a new tone (engaging | bold | inspirational), preserving every [Block] token so the template stays intact. This is brand-level copy (one message for everyone) — there's no creator here. Degrades to the original body on any failure, so the caller never ends up with a broken template. Requires a single shop.

Body parameter

{
  "message_body": "string",
  "tone": "engaging"
}

Parameters

Example responses

200 Response

{
  "message": "string"
}

Responses

Personalization fallback usage for one automation

GET /personalization/automations/{automation_id}/fallback-stats

How many of an automation's personalized outreach messages used the brand fallback (creator had too little signal to personalize) versus were fully personalized. A lifetime aggregate across every send run of the automation, plus the fallback_rate convenience ratio. Counts are recorded when the send engine locks the copy for delivery (immediately before the DM goes out), so a delivery that fails at the last step may still be counted. An automation with no personalized sends yet returns zeros; an automation not in this shop returns 404. Requires a single shop.

Parameters

Example responses

200 Response

{
  "automation_id": 0,
  "messages_sent": 0,
  "fallback_used": 0,
  "fallback_rate": 0
}

Responses

Personalized messages a creator was actually sent

GET /personalization/creators/{creator_id}/sent-messages

The personalized outreach messages this shop sent to one creator (the creator record's audit trail), newest first — the exact copy, whether it was fully personalized or fell back. Rows are recorded when the send engine locks the copy for delivery, so sent_at marks the delivery attempt, not a provider receipt. creator_id is the TikTok creator id (as returned by GET /automations/{id}/creators or GET /automations/{id}/sent-messages). Returns an empty list when this creator has never been personalized in this shop. Requires a single shop.

Parameters

Example responses

200 Response

{
  "creator_id": "string",
  "count": 0,
  "messages": [
    {
      "automation_id": 0,
      "message": "string",
      "is_fallback": true,
      "tone": "string",
      "sent_at": "string"
    }
  ]
}

Responses

Target Collabs

Send a single TikTok Shop Target Collab invitation to one creator by handle — convenience surface over the two-step automation create + start. For >10 invites at a time, use POST /automations/target-collab with a multi-creator audience instead. Also exposes GET/PUT /target-collabs/support-contact-default to configure a shop-level default support_contact, which the TC create surfaces fall back to when a request omits it.

Send a Target Collab invite directly

POST /target-collabs

Send a single TikTok Shop Target Collab (TC) invitation to a creator by handle. This is a convenience surface — it internally creates a single-creator TC automation and immediately starts it.

Queued semantics. The response returns immediately with status: "queued". Actual TC delivery happens asynchronously through Reacher's TC delivery worker (browser automation, the same path the portal uses). Typical end-to-end latency is a few seconds, sometimes longer under worker load. Poll GET /public/v1/automations/{automation_id} for delivery status and target_collabs.invitation_id once the worker submits.

Not for bulk. For >10 invites at a time, use POST /public/v1/automations/target-collab directly with a multi-creator audience — that's more efficient than calling this endpoint in a loop, and exposes the full TC feature set (content type, sample policy, follow-up DMs).

Required. read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting or queueing.

Body parameter

{
  "creator_handle": "string",
  "product_id": "string",
  "commission_rate": 1,
  "shop_ads_commission_rate": 1,
  "message": "string",
  "invitation_name": "string",
  "valid_until": "2019-08-24",
  "support_contact": {
    "email": "string",
    "phone": "string"
  }
}

Parameters

Example responses

201 Response

{
  "automation_id": 0,
  "status": "string",
  "creator_id": "string",
  "creator_handle": "string",
  "shop_id": 0,
  "check_status_at": "string",
  "queued_at": "string",
  "dry_run": false
}

Responses

Get the shop's default Target Collab support contact

GET /target-collabs/support-contact-default

Read the shop-level default support_contact used as a fallback when a TC create request omits support_contact (CORE-5428).

Returns configured: false (with null fields) when no default is set — in that state TC creates still require a per-request support_contact. Requires a single shop (x-shop-id).

Example responses

200 Response

{
  "shop_id": 0,
  "configured": true,
  "email": "string",
  "phone": "string",
  "updated_at": "string"
}

Responses

Set the shop's default Target Collab support contact

PUT /target-collabs/support-contact-default

Configure the shop-level default support_contact once, so TC create requests can omit it (CORE-5428). A per-request support_contact still overrides this default for that request.

email is required; phone is optional. The upsert is keyed on the shop, so re-sending the same body yields the same state. Requires read_write scope, a single shop (x-shop-id), and an Idempotency-Key header (for contract consistency with the other public-API write endpoints) — replay/conflict semantics match those writes.

Body parameter

{
  "email": "string",
  "phone": "string"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "configured": true,
  "email": "string",
  "phone": "string",
  "updated_at": "string"
}

Responses

Metrics

Time-series metrics for dashboards and charts.

Time-series metrics

POST /metrics/timeseries

Fetch time-series data for one or more metrics over a date range. Returns daily/weekly/monthly data points for charting trends. Available metrics: gmv (affiliate-attributed), total_gmv (full shop from the Seller Center scrape), live_gmv (creator LIVE-attributed, from live_sessions — see POST /lives/* for the per-shop currency-aware view), sc_affiliate_live_gmv (creator LIVE GMV as Seller Center itself reports it, under By order source → Creator → Lives — order-date attributed, so it does not match live_gmv; use it to reconcile against a Seller Center export), creators, videos_posted, video_views, gmv_per_video, gmv_per_sample, creators_reached, creators_messaged, tc_invites_sent, samples_approved, sample_requests, gmv_driving_videos, new_creators_posting, open_collabs, accepted_tc_count, emails_sent, dm_responses, reply_rate. Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (aov/ctr/conversion_rate are ratios computed over the full window, not averages of daily ratios; 0 for shops not yet on the Seller Center sync). Granularity (day/week/month) is auto-detected based on the date range if not specified. IMPORTANT: 'creators' returns distinct creators PER DAY — summing daily values double-counts creators active on multiple days. For the headline distinct count over the full period, use POST /metrics/summary instead. Similarly, gmv_per_video and gmv_per_sample are daily ratios — use /metrics/summary for the period-level headline values. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes).

Body parameter

{
  "metrics": [
    "gmv"
  ],
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "granularity": "day"
}

Parameters

Example responses

200 Response

{
  "data": {
    "property1": [
      {
        "date": "string",
        "value": 0
      }
    ],
    "property2": [
      {
        "date": "string",
        "value": 0
      }
    ]
  },
  "granularity": "string",
  "start_date": "string",
  "end_date": "string",
  "currency": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

Dashboard headline metrics

POST /metrics/summary

Pre-computed headline scalar metrics for a date range, matching the Reacher dashboard's top-level KPIs exactly. Use this for summary cards and headline numbers. Includes derived metrics like active_creators (distinct count, not daily sum), gmv_per_video, and gmv_per_sample, plus sc_affiliate_live_gmv (creator LIVE GMV as Seller Center reports it — order-date attributed, so it does not match live_gmv). Also includes Seller Center whole-shop cards: orders, units_sold, aov, ctr, conversion_rate (all-channel; aov/ctr/conversion_rate are ratios computed over the full window). Defaults to the last 30 days if no dates are specified. Dates default to the newest day with settled data for the shop (typically yesterday; up to 2 days back while a day finalizes).

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "gmv": 0,
  "total_gmv": 0,
  "live_gmv": 0,
  "sc_affiliate_live_gmv": 0,
  "active_creators": 0,
  "video_views": 0,
  "videos_posted": 0,
  "samples_approved": 0,
  "gmv_per_video": 0,
  "gmv_per_sample": 0,
  "sample_requests": 0,
  "gmv_driving_videos": 0,
  "new_creators_posting": 0,
  "open_collabs": 0,
  "accepted_tc_count": 0,
  "creators_reached": 0,
  "creators_messaged": 0,
  "tc_invites_sent": 0,
  "emails_sent": 0,
  "dm_responses": 0,
  "reply_rate": 0,
  "orders": 0,
  "units_sold": 0,
  "aov": 0,
  "ctr": 0,
  "conversion_rate": 0,
  "errors": [
    "string"
  ],
  "start_date": "string",
  "end_date": "string",
  "currency": "string",
  "shops_queried": [
    "string"
  ]
}

Responses

Shop GMV

Full TikTok Seller Center shop GMV (ads + organic + affiliate) — daily series and window totals with channel breakdown. Distinct from POST /metrics/timeseries metric=gmv, which is affiliate-attributed only.

Daily shop GMV time series (Seller Center, full shop view)

POST /shop-gmv/timeseries

Daily GMV for one shop from the TikTok Seller Center daily rollup, including channel breakdown (video → affiliate/seller, live → affiliate/seller, product_card → shop_tab/search) and traffic (product impressions/clicks).

Differs from POST /metrics/timeseries metric=gmv — that endpoint reports affiliate-attributed GMV only (Reacher's view of creator-driven sales). This endpoint reports the total shop GMV including ads / Smart+ and organic. Use this when the customer wants numbers matching their TikTok Seller Center dashboard.

Single-shop only — set x-shop-id to a specific shop ID. Defaults to last 30 days ending yesterday. Max range 90 days (TikTok backfill depth). The newest available day is yesterday; today's row is not returned. Empty series is a normal 200 response — Seller Center coverage is still rolling out.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "currency_code": "string",
  "granularity": "daily",
  "start_date": "string",
  "end_date": "string",
  "series": [
    {
      "date": "string",
      "gmv": 0,
      "orders": 0,
      "items_sold": 0,
      "customers": 0,
      "aov": 0,
      "channels": {
        "video": {
          "gmv": 0,
          "affiliate": 0,
          "seller": 0
        },
        "live": {
          "gmv": 0,
          "affiliate": 0,
          "seller": 0
        },
        "product_card": {
          "gmv": 0,
          "shop_tab": 0,
          "search": 0
        }
      },
      "traffic": {
        "product_impressions": 0,
        "product_clicks": 0
      }
    }
  ]
}

Responses

Shop GMV window totals (Seller Center, full shop view)

POST /shop-gmv/summary

Window totals for one shop from the TikTok Seller Center daily rollup — SUMmed across the window with the same channel hierarchy as the timeseries response.

Same coverage caveats as the timeseries endpoint. aov is recomputed as total GMV / total orders over the window (a window-correct value, not the average of daily AOVs). customers is the SUM of daily unique-customer counts — buyers who purchased on multiple days are double-counted; a true window-distinct count is not derivable from this rollup.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "currency_code": "string",
  "start_date": "string",
  "end_date": "string",
  "day_count": 0,
  "gmv": 0,
  "orders": 0,
  "items_sold": 0,
  "customers": 0,
  "aov": 0,
  "channels": {
    "video": {
      "gmv": 0,
      "affiliate": 0,
      "seller": 0
    },
    "live": {
      "gmv": 0,
      "affiliate": 0,
      "seller": 0
    },
    "product_card": {
      "gmv": 0,
      "shop_tab": 0,
      "search": 0
    }
  },
  "traffic": {
    "product_impressions": 0,
    "product_clicks": 0
  }
}

Responses

Shop Health

Per-shop TikTok Shop Performance Score (SPS) and its health sub-metrics (on-time dispatch, negative-review rate, etc.) — daily trend and latest snapshot. Sourced from TikTok's official shop_performances API.

Daily Shop Performance Score (SPS) trend

POST /shop-health/timeseries

Daily Shop Performance Score for one shop from TikTok's official shop_performances/overview API — the same SPS shown in Seller Center. Each point carries sps_score (0-5), sps_tier, peer_percentile, and a dimensions breakdown of the sub-metrics (on-time dispatch, negative-review rate, etc.).

Single-shop only — set x-shop-id to a specific shop ID. Defaults to the last 30 days ending yesterday. Max range 90 days. Only shops on the official-API sync path are covered; an empty series is a normal 200 response (history builds from the first daily pull).

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "start_date": "string",
  "end_date": "string",
  "series": [
    {
      "date": "string",
      "sps_score": 0,
      "sps_tier": "string",
      "peer_percentile": 0,
      "dimensions": [
        {
          "name": "string",
          "score": 0,
          "status": "string",
          "status_text": "string",
          "weight": 0
        }
      ]
    }
  ]
}

Responses

Most recent Shop Performance Score snapshot

POST /shop-health/latest

The most recent Shop Performance Score snapshot for one shop — the current sps_score (0-5), sps_tier, peer_percentile, and the per-sub-metric dimensions breakdown.

Single-shop only. snapshot is null when the shop has no SPS data yet (non-official-API shop, or the first daily pull hasn't run).

Body parameter

{}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "snapshot": {
    "date": "string",
    "sps_score": 0,
    "sps_tier": "string",
    "peer_percentile": 0,
    "dimensions": [
      {
        "name": "string",
        "score": 0,
        "status": "string",
        "status_text": "string",
        "weight": 0
      }
    ]
  }
}

Responses

Shop Performance Score metrics (per-metric status, value, thresholds)

POST /shop-health/metrics

Every stored snapshot of TikTok's six Shop Performance Score metrics for one shop in the window (NRR, NBFR, SFCR, OTDR, AHT, IM_DSAT): status (EXCELLENT/GOOD/POOR/CRITICAL/NIL), value with unit, thresholds, evaluation window, and how many problem items TikTok reported. latest_snapshot_date names the newest day; a metric absent on that day has no data. Window: a preset or explicit dates, max 365 days. Single-shop only.

Body parameter

{
  "preset": "string",
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "metric_codes": [
    "NRR"
  ]
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "start_date": "string",
  "end_date": "string",
  "latest_snapshot_date": "string",
  "snapshot_count": 0,
  "points": [
    {
      "date": "string",
      "metric_code": "NRR",
      "metric_name": "string",
      "dimension": "string",
      "score": 0,
      "value": 0,
      "value_unit": "string",
      "status": "EXCELLENT",
      "status_text": "string",
      "excellent_threshold": 0,
      "poor_threshold": 0,
      "evaluation_window_start": "string",
      "evaluation_window_end": "string",
      "is_top_reason": false,
      "top_reason_text": "string",
      "problems_upstream_total": 0,
      "problems_stored": 0,
      "problems_complete": true,
      "problems_truncated": true
    }
  ]
}

Responses

Orders, returns or chats behind one Shop Performance Score metric

POST /shop-health/problems

The problem items TikTok attributes to one metric on one snapshot day (default: the latest stored snapshot), paged and ordered by TikTok's page then item key. pagination.stored_total is what Reacher holds; upstream_total/upstream_truncated are TikTok's own count and whether it cut the list. snapshot_date is null with an empty page when nothing is stored. Single-shop only.

Body parameter

{
  "metric_code": "NRR",
  "snapshot_date": "2019-08-24",
  "page": 1,
  "page_size": 20,
  "version": 1
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "metric_code": "NRR",
  "snapshot_date": "string",
  "pagination": {
    "page": 0,
    "page_size": 0,
    "stored_total": 0
  },
  "upstream_total": 0,
  "upstream_truncated": true,
  "version": 0,
  "items": [
    {
      "item_key": "string",
      "order_id": "string",
      "return_order_id": "string",
      "chat_record_id": "string",
      "product_id": "string",
      "sku_id": "string",
      "product_name": "string",
      "reason": "string",
      "rating": 0,
      "review_count": 0,
      "event_time": "string",
      "deliver_time": "string",
      "expect_deliver_time": "string",
      "actual_deliver_time": "string",
      "duration_hours": 0,
      "page": 0
    }
  ]
}

Responses

P&L

Merchant profit & loss straight from your TikTok Seller Center finance export: window totals as an ordered waterfall, the running P&L bucketed by day / week / bi-weekly / month, and order x SKU detail with its fee breakdown. Every figure is TikTok's own, summed and never recomputed, so any cadence reconciles to Seller Center exactly. Rows are bucketed by order PAID date in the shop's Seller Center timezone, so recent windows keep moving as orders settle — read data_status on every response for freshness. Costs TikTok cannot see are supplied separately: store cost of goods per SKU and per-unit sample cost with PUT /pnl/costs, then read POST /pnl/profit for the contribution profit they imply. POST /pnl/skus rolls the same figures up per SKU as a gross / contribution P&L (revenue and per-SKU fees less cost of goods); per-SKU ad spend is not available, so the true net bottom line stays on the summary and profit surfaces. Single-shop only, and enabled per shop on request.

Per-product P&L inputs

GET /pnl/products

The per-product side of the P&L that POST /pnl/summary reports in aggregate: every active product in the shop with its SKU pricing (sale and original price in currency units, not cents), stock, the derived discount_pct, and the affiliate commission_rate / shop_ads_commission_rate from the shop's most recent Target Collaboration config.

gmv_max is shop-level, not per product: whether GMV Max is currently running and the average ROAS actually achieved across its active campaigns. tiktok_fee_pct is the platform's flat fee assumption used by the calculator.

These are the inputs to a margin calculation, not settled money — for what TikTok actually paid out, use POST /pnl/summary or POST /pnl/orders. Single-shop only. A shop with no catalogued products returns an empty products list as a normal 200.

Example responses

200 Response

{
  "products": [
    {
      "product_id": "string",
      "title": "string",
      "primary_image_url": "string",
      "category_chain": [],
      "brand_name": "string",
      "currency": "USD",
      "skus": [],
      "commission": {
        "commission_rate": 0,
        "shop_ads_commission_rate": 0
      },
      "discount_pct": 0
    }
  ],
  "shop_id": 0,
  "tiktok_fee_pct": 6,
  "gmv_max": {
    "active": false,
    "avg_roas": 0,
    "tooltip": "Based on average ROAS across all active campaigns in your shop."
  }
}

Responses

P&L totals for a window

POST /pnl/summary

Window totals as an ordered waterfall, summed from TikTok's own daily P&L series. Rows are bucketed by order PAID date in the shop's Seller Center timezone. Recent days keep moving as orders settle — check data_status for freshness.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "currency": "string",
  "start_date": "string",
  "end_date": "string",
  "days_with_data": 0,
  "totals": {
    "gross_sales": 0,
    "refunds": 0,
    "referral_fee": 0,
    "affiliate": 0,
    "gmv_max": 0,
    "campaigns": 0,
    "managed_services": 0,
    "shipping_and_warehousing_cost": 0,
    "others": 0,
    "net_earnings": 0
  },
  "rollups": {
    "property1": 0,
    "property2": 0
  },
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Running P&L series

POST /pnl/timeseries

The running P&L: the same waterfall bucketed by day, week, bi-weekly or month. Buckets are summed from TikTok's daily rows, so any cadence reconciles to Seller Center exactly.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "cadence": "day"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "currency": "string",
  "cadence": "string",
  "series": [
    {
      "gross_sales": 0,
      "refunds": 0,
      "referral_fee": 0,
      "affiliate": 0,
      "gmv_max": 0,
      "campaigns": 0,
      "managed_services": 0,
      "shipping_and_warehousing_cost": 0,
      "others": 0,
      "net_earnings": 0,
      "period_start": "string"
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Order-level P&L detail

POST /pnl/orders

One row per order x SKU with its fee breakdown, filterable by order source, settled state, product or SKU — the same filters applied by hand to the Seller Center export. Unsettled lines are included by default and their amounts still move.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "order_source": "Video",
  "settled": true,
  "product_id": "string",
  "sku_id": "string",
  "limit": 100,
  "offset": 0,
  "amounts_fields": "standard"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "total": 0,
  "limit": 0,
  "offset": 0,
  "selected_fields": [
    "string"
  ],
  "orders": [
    {
      "order_id": "string",
      "sku_id": "string",
      "product_id": "string",
      "product_name": "string",
      "sku_name": "string",
      "quantity": 0,
      "order_paid_date": "string",
      "order_settled_date": "string",
      "order_status": "string",
      "order_source": [
        "string"
      ],
      "is_settled": true,
      "unsettled_reason": "string",
      "estimated_settle_time": "string",
      "sample_order_type": "string",
      "linked_statement_id": "string",
      "currency": "string",
      "amounts": {}
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Per-SKU gross / contribution P&L

POST /pnl/skus

One row per SKU: units sold and the fee lines from the order-level export summed over the window, joined to your cost of goods, with a gross profit and margin.

This is a GROSS / CONTRIBUTION view, not a net bottom line. The fees here are the ones TikTok books against the order itself — referral, affiliate commission, refunds, discounts and the like — and ad spend is NOT among them: TikTok does not attribute ad spend to a single SKU, so gross_profit is revenue less those per-SKU fees less COGS, and stops one step short of net earnings. For the true shop-level bottom line that includes ad spend, use POST /pnl/summary and POST /pnl/profit. If you request the net_earnings or total_expense columns they are the order-line totals and likewise exclude ad spend.

gross_profit is an upper bound while units_uncosted is non-zero — uncosted units are counted, never assumed free. Windowed by order PAID date; single shop only.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "product_id": "string",
  "sku_id": "string",
  "limit": 100,
  "offset": 0,
  "amounts_fields": "standard",
  "sort": "gross_sales"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "currency": "string",
  "start_date": "string",
  "end_date": "string",
  "total": 0,
  "limit": 0,
  "offset": 0,
  "selected_fields": [
    "string"
  ],
  "currency_mismatched_costs": 0,
  "skus": [
    {
      "product_id": "string",
      "sku_id": "string",
      "sku_name": "string",
      "product_name": "string",
      "units": 0,
      "amounts": {
        "property1": 0,
        "property2": 0
      },
      "cogs": 0,
      "gross_profit": 0,
      "gross_margin_pct": 0,
      "units_costed": 0,
      "units_uncosted": 0,
      "currency": "string"
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

List stored cost inputs

GET /pnl/costs

Every cost input stored for this shop: cost of goods per SKU and per-unit sample cost per product. Returns full history — a row per effective_from — not just what is in force today, so a caller restating an old window can see which amount applied then. sku_id is null on the product-level default.

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "costs": [
    {
      "id": 0,
      "product_id": "string",
      "sku_id": "string",
      "cost_type": "string",
      "amount": 0,
      "currency": "string",
      "effective_from": "string",
      "notes": "string",
      "source": "string",
      "updated_at": "string"
    }
  ]
}

Responses

Set cost inputs

PUT /pnl/costs

Insert or update cost inputs in bulk — the endpoint a spreadsheet or CSV import writes through. Rows are keyed on (product_id, sku_id, cost_type, effective_from): re-sending a key overwrites its amount rather than stacking a second cost onto the same units, so replaying the same import is safe. Omit sku_id to set a product-level default that applies to every SKU without one of its own. Requires read_write scope and a single shop.

Body parameter

{
  "costs": [
    {
      "product_id": "string",
      "sku_id": "string",
      "cost_type": "cogs",
      "amount": 0,
      "currency": "USD",
      "effective_from": "2019-08-24",
      "notes": "string"
    }
  ]
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "costs": [
    {
      "id": 0,
      "product_id": "string",
      "sku_id": "string",
      "cost_type": "string",
      "amount": 0,
      "currency": "string",
      "effective_from": "string",
      "notes": "string",
      "source": "string",
      "updated_at": "string"
    }
  ]
}

Responses

Delete a cost input

DELETE /pnl/costs/{cost_id}

Remove one stored cost by its id. The units it covered become uncosted again and drop out of contribution_profit — they are not treated as free-of-charge silently, they are reported as uncosted. Scoped to this shop, so an id belonging to another shop returns 404. Requires read_write scope and a single shop.

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "costs": [
    {
      "id": 0,
      "product_id": "string",
      "sku_id": "string",
      "cost_type": "string",
      "amount": 0,
      "currency": "string",
      "effective_from": "string",
      "notes": "string",
      "source": "string",
      "updated_at": "string"
    }
  ]
}

Responses

Contribution profit (P&L less your costs)

POST /pnl/profit

TikTok's bottom line carried down by the costs it cannot see. net_earnings is taken from the daily series unchanged — the only source that includes GMV Max ad spend — and cost of goods and sample cost are subtracted from it. Set cadence to get the running series as well as the totals.

Units with no cost on file are COUNTED, never assumed to be zero, so contribution_profit is an upper bound while units_uncosted or sample_units_uncosted is non-zero. Use POST /pnl/costs/coverage to get the list of what is missing.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "cadence": "total",
  "sample_basis": "shipped"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "currency": "string",
  "start_date": "string",
  "end_date": "string",
  "cadence": "string",
  "sample_basis": "string",
  "days_with_data": 0,
  "totals": {
    "net_earnings": 0,
    "cogs": 0,
    "sample_cost": 0,
    "contribution_profit": 0,
    "units": 0,
    "units_costed": 0,
    "units_uncosted": 0,
    "units_on_refunded_lines": 0,
    "sample_units": 0,
    "sample_units_costed": 0,
    "sample_units_uncosted": 0
  },
  "series": [
    {
      "net_earnings": 0,
      "cogs": 0,
      "sample_cost": 0,
      "contribution_profit": 0,
      "units": 0,
      "units_costed": 0,
      "units_uncosted": 0,
      "units_on_refunded_lines": 0,
      "sample_units": 0,
      "sample_units_costed": 0,
      "sample_units_uncosted": 0,
      "period_start": "string"
    }
  ],
  "currency_mismatched_costs": 0,
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

What is missing before profit is trustworthy

POST /pnl/costs/coverage

The SKUs that sold and the products that shipped samples in this window with no cost on file, ordered by how many units each one represents — the worklist for making POST /pnl/profit complete, biggest impact first. coverage_pct is by units, not by SKU count, so one missing best-seller outranks fifty missing long-tail SKUs.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "sample_basis": "shipped"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "currency": "string",
  "start_date": "string",
  "end_date": "string",
  "sample_basis": "string",
  "cogs": {
    "units": 0,
    "units_costed": 0,
    "coverage_pct": 0,
    "missing_count": 0,
    "missing": [
      {
        "product_id": "string",
        "sku_id": "string",
        "product_name": "string",
        "sku_name": "string",
        "units": 0
      }
    ],
    "truncated": true
  },
  "samples": {
    "sample_units": 0,
    "sample_units_costed": 0,
    "coverage_pct": 0,
    "missing_count": 0,
    "missing": [
      {
        "product_id": "string",
        "sample_units": 0
      }
    ],
    "truncated": true
  }
}

Responses

Settlement adjustments

POST /pnl/adjustments

Credits, clawbacks and manual corrections TikTok posts against a statement rather than an order. They never appear on order rows, so a P&L built only from /pnl/orders silently omits them — net_amount is the figure to carry across.

Windowed on the date TikTok raised the adjustment. settled_date is null until it reaches a payout.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "limit": 100,
  "offset": 0
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "total": 0,
  "limit": 0,
  "offset": 0,
  "net_amount": 0,
  "adjustments": [
    {
      "adjustment_id": "string",
      "adjustment_type": "string",
      "reason": "string",
      "amount": 0,
      "created_date": "string",
      "settled_date": "string",
      "linked_statement_id": "string",
      "linked_payout_id": "string",
      "currency": "string"
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Buyer-side payment breakdown

POST /pnl/customer-payments

What the CUSTOMER paid for each order x SKU, as opposed to what the seller earned: subtotal before and after discount, which party funded each discount, shipping, retail delivery fee and tax.

Paired to order lines on (order, SKU) to get a paid date, since this sheet carries none of its own. TikTok does not guarantee that pairing is 1:1, so a payment row with no matching order line falls outside the window rather than being invented into it.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "product_id": "string",
  "sku_id": "string",
  "limit": 100,
  "offset": 0
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "total": 0,
  "limit": 0,
  "offset": 0,
  "payments": [
    {
      "order_id": "string",
      "sku_id": "string",
      "currency": "string",
      "amounts": {
        "property1": 0,
        "property2": 0
      }
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Affiliate Orders

Affiliate Center -> Orders, over the API: one row per order x SKU with the creator, the content (video / LIVE / showcase) that drove the sale, the commission model and rates, and estimated vs actual commission side by side. This is the order-level audit trail behind /creators/performance and /videos/performance. Rows are keyed on TikTok's seller and bucketed by order CREATED date in the shop's Affiliate Center timezone; status and actual amounts keep moving for weeks as commission settles, so read data_status for freshness. Single-shop only. A shop whose export collection is not yet enabled reads data_status.state == "never_run".

Affiliate order lines: creator, content and commission per order

POST /affiliate/transactions

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.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "creator_handle": "string",
  "content_id": "string",
  "content_type": "string",
  "product_id": "string",
  "sku_id": "string",
  "order_status": "string",
  "settled": true,
  "limit": 100,
  "offset": 0
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "seller_id": "string",
  "start_date": "string",
  "end_date": "string",
  "total": 0,
  "limit": 0,
  "offset": 0,
  "transactions": [
    {
      "order_id": "string",
      "sku_id": "string",
      "product_id": "string",
      "product_name": "string",
      "quantity": 0,
      "price": 0,
      "payment_amount": 0,
      "currency": "string",
      "fully_refunded": true,
      "payment_method": "string",
      "order_status": "string",
      "is_settled": true,
      "creator_handle": "string",
      "content_type": "string",
      "content_id": "string",
      "commission_model": "string",
      "standard_commission_rate": 0,
      "shop_ads_commission_rate": 0,
      "estimated": {
        "commission_base": 0,
        "standard_commission": 0,
        "shop_ads_commission": 0,
        "cofunded_creator_bonus": 0
      },
      "actual": {
        "commission_base": 0,
        "standard_commission": 0,
        "shop_ads_commission": 0,
        "cofunded_creator_bonus": 0
      },
      "order_created_at": "string",
      "paid_at": "string",
      "delivered_at": "string",
      "commission_paid_at": "string",
      "platform": "string"
    }
  ],
  "data_status": {
    "state": "string",
    "last_synced_at": "string",
    "last_window": {
      "start_date": "string",
      "end_date": "string"
    }
  }
}

Responses

Lives

Creator LIVE-attributed GMV — window totals and per-session rows from TikTok's Affiliate Center LIVE data. Distinct from the gmv field (all affiliate revenue); the same number is on POST /metrics/* as live_gmv. Single-shop, currency-aware.

LIVE metric cards with trend

POST /lives/metrics

The five LIVE performance cards the portal shows above the session table — Live GMV, Live Units Sold, Live Count, Avg Engagement Rate and Avg Viewing Duration. Each card carries its value, unit, the percent change against the immediately preceding window of equal length, and chart_data: one point per day of the window, zero-filled on days with no sessions so the series length always matches the range.

Differs from POST /lives/summary — that returns flat window totals. This returns the same totals plus period-over-period change and a daily series, and accepts the portal's filters / search so the cards can be scoped to a creator or a GMV band. Engagement rate is a decimal (0.0-1.0), durations are seconds.

Single-shop only; defaults to the last 30 days ending today. LIVE analytics is region-gated — shops outside the supported regions get a 403 REGION_NOT_SUPPORTED. A shop with no sessions returns zeroed cards as a normal 200.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "filters": {
    "gmv": {
      "min": 0,
      "max": 0
    },
    "views": {
      "min": 0,
      "max": 0
    },
    "duration": {
      "min": 0,
      "max": 0
    },
    "unitsSold": {
      "min": 0,
      "max": 0
    },
    "likes": {
      "min": 0,
      "max": 0
    },
    "comments": {
      "min": 0,
      "max": 0
    },
    "ctr": {
      "min": 0,
      "max": 0
    },
    "engagementRate": {
      "min": 0,
      "max": 0
    }
  },
  "search": "string"
}

Parameters

Example responses

200 Response

{
  "success": true,
  "metrics": [
    {
      "label": "string",
      "value": 0,
      "unit": "string",
      "change": 0,
      "comparison_text": "string",
      "tooltip_text": "string",
      "chart_data": [
        0
      ]
    }
  ]
}

Responses

Products sold inside LIVE sessions

POST /lives/products

The per-product breakdown behind one or more LIVE sessions: for each product featured in the session, its LIVE GMV, units sold, orders, average order value, creator commission and refunds. This is the session x product grain — POST /lives/list gives the session totals, this explains what inside the session earned them.

Pass the key values from POST /lives/list rows in live_session_ids (up to 50 per request). Results are keyed back by session ID in request order. Sessions with no product rows — including any ID that belongs to a different shop, or a shop still on the legacy LIVE data path — return an empty products list rather than an error. Single-shop only.

Body parameter

{
  "live_session_ids": [
    "string"
  ]
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "sessions": [
    {
      "live_session_id": "string",
      "products": [
        {
          "product_id": "string",
          "product_name": "string",
          "cover": "string",
          "categories": null,
          "live_gmv": 0,
          "items_sold": 0,
          "orders": 0,
          "avg_order_value": 0,
          "commission": 0,
          "refunded_gmv": 0,
          "refunded_items": 0
        }
      ]
    }
  ]
}

Responses

Creator LIVE-attributed GMV window totals

POST /lives/summary

Window totals for creator LIVE-attributed GMV for one shop, from customers.live_sessions (the Affiliate Center LIVE value shops see on /insights/transaction-analysis → LIVE streams).

Differs from POST /metrics/summary field gmv — that is ALL affiliate revenue (video + live + product card). This isolates the LIVE-stream slice only. The live_gmv field on /metrics/summary is the same number as a simple cross-shop scalar; this endpoint adds per-shop currency, session count, engagement and viewing duration.

Single-shop only — set x-shop-id to a specific shop ID. Defaults to the last 30 days ending today. Empty totals (live_count 0) are a normal 200 response — live-session coverage is data-presence driven.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "currency_code": "string",
  "start_date": "string",
  "end_date": "string",
  "live_count": 0,
  "live_gmv": 0,
  "items_sold": 0,
  "avg_engagement_rate": 0,
  "avg_viewing_duration": 0
}

Responses

Per-session creator LIVE-attributed GMV rows

POST /lives/list

Paginated per-session view of creator LIVE-attributed GMV for one shop — one row per affiliate LIVE session with creator, timestamps, GMV, units, and engagement.

Single-shop only. Defaults to the last 30 days ending today. Sort by live_gmv (default), start_time, units_sold or views. Empty sessions is a normal 200 response for shops without live-session data.

Body parameter

{
  "start_date": "2019-08-24",
  "end_date": "2019-08-24",
  "page": 1,
  "page_size": 20,
  "sort_by": "live_gmv",
  "sort_dir": "asc"
}

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "currency_code": "string",
  "start_date": "string",
  "end_date": "string",
  "page": 0,
  "page_size": 0,
  "total": 0,
  "sessions": [
    {
      "live_session_id": "string",
      "title": "string",
      "creator_handle": "string",
      "start_time": "string",
      "end_time": "string",
      "duration_seconds": 0,
      "live_gmv": 0,
      "units_sold": 0,
      "views": 0,
      "likes": 0,
      "comments": 0,
      "ctr": 0,
      "engagement_rate": 0,
      "new_followers": 0,
      "avg_viewing_duration": 0
    }
  ]
}

Responses

Analytics

Affiliate funnel and creator level distributions.

Affiliate funnel stage detail

GET /funnel/stages/{stage_id}

Everything behind one stage of the affiliate funnel returned by GET /funnel: creator_count and percentage_of_funnel, the insights block (unique creators, total entries, conversion rate from the previous stage with its conversion_label, and median days spent in the status), the CRM group_id / group_filters that define the stage, the automation_templates available for it, and the active_automations currently working it.

stage_id accepts the stage keys from the funnel overview — e.g. sample-requested, sample-approved, content-posted, content-unfulfilled, gmv-generated, top-creators.

Set include_products=true to also get the per-product breakdown of the stage (one row per product with stage-relevant metrics such as creators_in_stage, gmv_generated, avg_views, avg_gmv, spark_code_collected); metrics that don't apply to the stage come back as null. Products are paginated independently via products_page / products_page_size and can be narrowed with product_ids.

Single-shop only. Data covers the last 90 days, matching the dashboard.

Parameters

Example responses

200 Response

{
  "shop_id": 0,
  "stage": {
    "stage_id": "string",
    "title": "string",
    "description": "string",
    "group_id": "string",
    "creator_count": 0,
    "percentage_of_funnel": 0,
    "insights": {
      "total_creators": 0,
      "total_in_stage": 0,
      "advanced_to_next_percentage": 0,
      "conversion_label": "of previous status",
      "median_time_in_status_days": 0
    },
    "automation_templates": [
      {
        "id": "string",
        "title": "string",
        "description": "string"
      }
    ],
    "active_automations": [
      {
        "automation_id": 0,
        "automation_name": "string",
        "automation_type": "string",
        "sample_requests": 0,
        "last_finished_at": "2019-08-24T14:15:22Z",
        "status": "string",
        "status_msg": "string",
        "status_details": "string",
        "creators_remaining": 0,
        "creators_reached": 0,
        "skipped": 0,
        "total_creators": 0,
        "crm_group_id": "string",
        "crm_group_name": "string",
        "ai_enabled": false,
        "created_at": "2019-08-24T14:15:22Z",
        "target_collab_cleanup_creators_reached": 0
      }
    ],
    "group_filters": {}
  },
  "products": {
    "stage_id": "string",
    "products": [
      {
        "product_id": "string",
        "product_name": "string",
        "image_url": "string",
        "metrics": {
          "property1": 0,
          "property2": 0
        }
      }
    ],
    "total": 0,
    "page": 0,
    "page_size": 0
  }
}

Responses

CRM v2 sample-request rows, with archivedCount and lastUpdatedAt

GET /funnel/v2/requests

The paginated sample-request pipeline for one shop — the rows behind the Sample Requests board. Each row carries the creator (handle, followers, level, rising-star / fast-growing signals, CRM tags), the product, the request's status and timestamps, and the creator's performance metrics (post rate, PPS score, average views, engagement rate, GMV per sample, videos per sample).

Filter by pipeline tab (status), product, SKU, creator profile, sourcing automation, tag, date range, free-text search, and any of the metric ranges (min_* / max_*). product_ids and sku_ids are AND-ed: passing both narrows to those SKUs rather than widening. show_archived returns the archived board instead; show_expiring narrows to requests about to expire. Response also reports archivedCount (requests hidden because the creator is archived), expiringCount, lastUpdatedAt (when this shop was last observed on TikTok; null if never) and a dataFreshness stamp.

Single-shop only, and only for shops on the CRM v2 pipeline — others get a 404 and should use /samples.

Parameters

Example responses

200 Response

{
  "data": [
    {
      "creator": {
        "id": "string",
        "handle": "string",
        "name": "string",
        "creatorImage": "string",
        "followers": 0,
        "creatorLevel": "string",
        "fastGrowing": true,
        "isRisingStar": true,
        "returning": true,
        "tags": [
          "string"
        ]
      },
      "products": [
        {
          "applyId": "string",
          "productId": "string",
          "name": "string",
          "sku": "string",
          "variantName": "string",
          "productImage": "string",
          "status": "string",
          "qty": 1,
          "isRepeatedRequest": true,
          "isArchived": false,
          "expiresInDays": 0,
          "commissionRate": 0,
          "stock": 0,
          "sampleAllowanceLeft": 0,
          "requestedAt": "string",
          "expiresAt": "string",
          "isExpired": false
        }
      ],
      "aggregated": {
        "unfulfilled": 0,
        "postRate": 0,
        "avgViews": 0,
        "ppsScore": 0,
        "liveGmv": 0,
        "engagementRate": 0,
        "shopGmv": 0,
        "creatorGmv": 0,
        "avgGmvPerVideo": 0,
        "gmvPerSample": 0,
        "videosPerSample": 0
      },
      "productCount": 0,
      "requestDate": "string",
      "expiresInDays": 0,
      "source": "string"
    }
  ],
  "pagination": {
    "page": 0,
    "perPage": 0,
    "totalItems": 0,
    "totalPages": 0
  },
  "archivedCount": {
    "creators": 0,
    "products": 0,
    "total": 0
  },
  "expiringCount": 0,
  "lastUpdatedAt": "string",
  "dataFreshness": {
    "lastSyncedAt": "string",
    "isStale": false,
    "isRefreshing": false
  }
}

Responses

CRM v2 pipeline counts, archive-inclusive, with archivedCounts per stage

GET /funnel/v2/counts

How many sample requests sit in each pipeline tab — toReview, readyToShip, shipped, pendingContent, completed, cancelled — under the filters you pass, plus the overall completionRate, the shop's approvalTarget (limit and used), archivedCount, expiringCount and a dataFreshness stamp. This is the tab-badge row above the board.

Every tab count INCLUDES requests hidden because the creator is archived, so the funnel matches TikTok's Affiliate Center. archivedCounts breaks that hidden share down per tab, and archivedCount.total is the hidden request count overall. With show_archived=true the archived rows are counted as visible, so archivedCounts comes back zeroed; to list them, pass the same flag to /funnel/v2/requests.

Accepts the same filters as /funnel/v2/requests (the counts respect them), so you can ask 'how many are in each stage for this product / date range'. Single-shop, CRM v2 shops only.

Parameters

Example responses

200 Response

{
  "counts": {
    "toReview": 0,
    "readyToShip": 0,
    "shipped": 0,
    "pendingContent": 0,
    "completed": 0,
    "cancelled": 0,
    "all": 0,
    "inShipment": 0,
    "posted": 0,
    "allApproved": 0,
    "overdue": 0,
    "rejected": 0,
    "expired": 0,
    "ignored": 0
  },
  "archivedCounts": {
    "toReview": 0,
    "readyToShip": 0,
    "shipped": 0,
    "pendingContent": 0,
    "completed": 0,
    "cancelled": 0,
    "all": 0,
    "inShipment": 0,
    "posted": 0,
    "allApproved": 0,
    "overdue": 0,
    "rejected": 0,
    "expired": 0,
    "ignored": 0
  },
  "completionRate": 0,
  "approvalTarget": {
    "limit": 0,
    "used": 0
  },
  "archivedCount": {
    "creators": 0,
    "products": 0,
    "total": 0
  },
  "expiringCount": 0,
  "dataFreshness": {
    "lastSyncedAt": "string",
    "isStale": false,
    "isRefreshing": false
  }
}

Responses

CRM v2 pipeline headline metrics, pendingReview archive-inclusive

GET /funnel/v2/metrics

The headline metrics above the Sample Requests board: pendingReview (count plus how many expire soon), approvedInAutoProcess (count with period-over-period changePct and changeDirection), completionRate, and approvalTarget progress against the shop's sample-approval limit, with a dataFreshness stamp.

pendingReview.count INCLUDES requests hidden because the creator is archived, so it matches TikTok's Affiliate Center; expiringSoon and completionRate stay over the visible rows, which are the ones you can act on.

Accepts the same filters as /funnel/v2/requests. Under a sku_ids filter, notScopableBySku names the metrics that could not be narrowed — approvalTarget, whose limit and used counters are product-grain — so treat those as unscoped rather than filtered. Single-shop, CRM v2 shops only.

Parameters

Example responses

200 Response

{
  "pendingReview": {
    "count": 0,
    "expiringSoon": 0
  },
  "approvedInAutoProcess": {
    "count": 0,
    "changePct": 0,
    "changeDirection": "up"
  },
  "completionRate": {
    "rate": 0,
    "changePct": 0,
    "changeDirection": "up"
  },
  "approvalTarget": {
    "monthlyLimit": 0,
    "monthlyUsed": 0,
    "dailyTarget": 0,
    "dailyCurrent": 0,
    "dailyPct": 0,
    "onTrack": true
  },
  "dataFreshness": {
    "lastSyncedAt": "string",
    "isStale": false,
    "isRefreshing": false
  },
  "notScopableBySku": [
    "string"
  ]
}

Responses

CRM v2 filter vocabulary

GET /funnel/v2/filter-config

The values you can actually filter the CRM v2 pipeline by for this shop — the products, sourcing automations, CRM tags and status tabs that exist in its data, plus the bounds of each metric range. Call this once to build a filter UI or to discover valid product_ids / automation_ids / tags before querying /funnel/v2/requests.

Single-shop, CRM v2 shops only.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Recommended next-best automations

GET /recommendations

Reacher Recommends for one shop: the automation types the shop has not run in the current timeframe, returned as ready-to-action suggestions. Each entry carries the automation title, description, impact type (e.g. 'High Impact', 'Addon'), the navigate path to set it up, its button label, and shop_names — the shops the recommendation applies to.

Covers the four automation plays Reacher scores: Target Collab, Message + Product Card, Spark Code, and Content Flywheel. An empty array means the shop is already running all of them. Single-shop only.

Example responses

200 Response

null

Responses

Response Schema

Shop performance targets

GET /targets

The performance targets the shop is measured against — the goal values behind the dashboard's progress bars. Each target carries its granularity (weekly / monthly / quarterly), the period it applies from (created_at), and a targets object with the per-metric goals: target_collabs, creators_messaged, sample_requests, sample_approved, videos_posted, videos_converted, spark_codes.

Omit granularity to get the latest target for each granularity the shop has set; pass one to get that granularity's history, newest first. An empty targets array means the shop has not set any.

Read-only — targets are created and edited in the Reacher dashboard. Single-shop only.

Parameters

Example responses

200 Response

{
  "targets": [
    {
      "created_at": "2024-01-01T00:00:00Z",
      "creators_messaged": 200,
      "customer_id": 1,
      "granularity": "monthly",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "sample_approved": 80,
      "sample_requests": 100,
      "shop_id": 123,
      "spark_codes": 10,
      "target_collabs": 50,
      "updated_at": "2024-01-01T00:00:00Z",
      "videos_converted": 25
    }
  ],
  "total_count": 1
}

Responses

Affiliate funnel overview

GET /funnel

Affiliate funnel stage counts matching the dashboard's 'Affiliate Funnel' section. Shows creators at each stage: sample requested, approved, content posted, content unfulfilled, GMV generated, and top creators (>$10k GMV). Data is based on the last 90 days.

Example responses

200 Response

null

Responses

Response Schema

GMV Max

TikTok Smart+ (GMV Max) campaigns and daily performance metrics for your shop.

List GMV Max campaigns

GET /gmv-max/campaigns

List all GMV Max (TikTok Smart+) campaigns for the shop(s) addressed by x-shop-id. Returns cached campaign metadata last synced from TikTok by the portal — call the portal's sync endpoints to refresh. Supports multi-shop (x-shop-id: all or comma-separated).

Example responses

200 Response

{
  "data": [
    {
      "shop_id": 0,
      "campaign_id": "string",
      "campaign_name": "string",
      "status": "string",
      "shopping_ads_type": "string",
      "budget": 0,
      "roas_bid": 0,
      "last_synced_at": "string",
      "currency": "string"
    }
  ],
  "shops_queried": [
    "string"
  ]
}

Responses

Create a GMV Max campaign

POST /gmv-max/campaigns

Create a new GMV Max (TikTok Smart+) campaign on the shop's connected TikTok Business ad account. Requires read_write scope. Single shop only — set x-shop-id to the owning shop.

The canonical body is mapped to TikTok's create payload server-side (daily_budget→budget, target_roas→ROAS bid, product_selection→ALL / CUSTOMIZED_PRODUCTS, etc.). The shop must already be connected to TikTok Business / GMV Max — an unconnected or incomplete connection returns 400 INVALID_REQUEST.

Idempotent via the Idempotency-Key header — replays of the same key + same body return the cached 201 without creating a duplicate. X-Dry-Run: true validates the body + connection and echoes the exact TikTok payload without calling TikTok.

Body parameter

{
  "campaign_name": "string",
  "campaign_type": "product",
  "product_selection": "all",
  "item_group_ids": [
    "string"
  ],
  "target_roas": 0,
  "daily_budget": 0,
  "schedule_type": "from_now",
  "schedule_start_time": "string",
  "schedule_end_time": "string",
  "promotion_days": 1,
  "auto_budget_enabled": true,
  "affiliate_posts_enabled": true
}

Parameters

Example responses

201 Response

null

Responses

Response Schema

Daily GMV Max campaign metrics

GET /gmv-max/campaigns/{campaign_id}/metrics

Daily performance metrics (spend, impressions, clicks, orders, gross_revenue, ROAS, CPC, CPM, CTR) for one campaign over a date range. Date range may not exceed 90 days (inclusive). Defaults to the last 30 days. Multi-shop is supported — when multiple shops are addressed via x-shop-id (a comma-separated list or all), the campaign's owning shop is resolved automatically and metrics are returned for that shop.

Parameters

Example responses

200 Response

{
  "campaign_id": "string",
  "shop_id": 0,
  "data": [
    {
      "date": "string",
      "spend": 0,
      "impressions": 0,
      "clicks": 0,
      "orders": 0,
      "gross_revenue": 0,
      "cpc": 0,
      "cpm": 0,
      "ctr": 0,
      "roas": 0,
      "ad_roi": 0
    }
  ],
  "start_date": "string",
  "end_date": "string",
  "currency": "string"
}

Responses

Daily GMV Max creative metrics (incl. video view rate)

GET /gmv-max/campaigns/{campaign_id}/creative-metrics

Daily per-creative performance for one campaign, including the video view-rate funnel: 2-second and 6-second view rates plus watch-completion rates (25/50/75/100%), all as percentages (0–100), alongside spend, impressions, clicks, conversions, revenue and ROI. Returns one row per creative per day (raw daily series — aggregate as needed). Optionally narrow to a single creative with material_id. Date range may not exceed 90 days (inclusive); defaults to the last 30 days. Multi-shop is supported — the campaign's owning shop is resolved automatically from x-shop-id.

Parameters

Example responses

200 Response

{
  "campaign_id": "string",
  "shop_id": 0,
  "data": [
    {
      "material_id": "string",
      "date": "string",
      "spend": 0,
      "impressions": 0,
      "clicks": 0,
      "conversions": 0,
      "revenue": 0,
      "roi": 0,
      "video_view_rate_2s": 0,
      "video_view_rate_6s": 0,
      "cost_per_order": 0,
      "ctr": 0,
      "video_ctr": 0,
      "conversion_rate": 0,
      "item_group_id": "string",
      "delivery_status": "string",
      "surface": "string",
      "video_view_rate_p25": 0,
      "video_view_rate_p50": 0,
      "video_view_rate_p75": 0,
      "video_view_rate_p100": 0
    }
  ],
  "start_date": "string",
  "end_date": "string",
  "currency": "string"
}

Responses

GMV Max dashboard KPIs

GET /gmv-max/dashboard

Aggregated GMV Max KPIs for a shop over a recent window, with previous-period comparison: spend, revenue, orders, impressions, clicks, ROAS — plus a per-day breakdown for charting. Single shop only (set x-shop-id to a specific shop ID). Mirrors the portal Dashboard exactly.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max campaign detail

GET /gmv-max/campaigns/{campaign_id}

Detail for one campaign: name, status, ad type, budget, ROAS bid, last sync time, plus the campaign's daily metric rows (spend, impressions, clicks, orders, gross_revenue, CPC, CPM, CTR, ROAS). Single shop only — the caller must address the campaign's owning shop via x-shop-id. For multi-shop callers, use the /campaigns list endpoint to discover which shop owns a campaign before requesting its detail.

Parameters

Example responses

200 Response

null

Responses

Response Schema

Update a GMV Max campaign

PATCH /gmv-max/campaigns/{campaign_id}

Patch the mutable subset of a GMV Max campaign — daily budget, target ROAS, name, and pause/resume (operation_status). Requires read_write scope. PATCH semantics — fields the caller omits are left unchanged; at least one field must be provided.

The shop must be connected to TikTok Business / GMV Max (400 INVALID_REQUEST otherwise). Idempotent via the Idempotency-Key header. X-Dry-Run: true echoes the mapped TikTok patch without calling TikTok. Single shop only.

Body parameter

{
  "campaign_name": "string",
  "daily_budget": 0,
  "target_roas": 0,
  "operation_status": "ENABLE",
  "promotion_days": 1,
  "auto_budget_enabled": true
}

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max creatives for a campaign

GET /gmv-max/creatives

List the synced creatives (videos, spark codes, etc.) attached to a specific GMV Max campaign, with per-creative performance summaries. Single shop only.

Parameters

Example responses

200 Response

null

Responses

Response Schema

GMV Max spark code sync state

GET /gmv-max/spark-codes

Cached spark-code sync state for the shop: which codes are queued, in flight, succeeded, or failed against TikTok. Read-only — sync itself is JWT-only on the portal. Single shop only.

Example responses

200 Response

null

Responses

Response Schema

GMV Max automation quick-start templates

GET /gmv-max/templates

Hard-coded set of quick-start automation templates the portal exposes (e.g. 'Boost top performers', 'Wind down low-ROAS'). Useful as a starting point when scaffolding an automation via the Phase-2 writes API. Not shop-scoped — same set for every caller.

Example responses

200 Response

null

Responses

Response Schema

List GMV Max automations

GET /gmv-max/automations

List all GMV Max automations configured for the shop, with their current status, trigger frequency, boost window, and last-run summary. Single shop only — automations are per-shop.

Example responses

200 Response

null

Responses

Response Schema

Create a GMV Max automation

POST /gmv-max/automations

Create a new automation that watches the selected campaign(s) and fires creative boosts when its conditions match. Requires read_write scope. Idempotent via the Idempotency-Key header — replays of the same key + same body return the cached 201 instead of creating a duplicate row.

X-Dry-Run: true validates the body and echoes the would-be row without touching the DB. Single shop only — set x-shop-id to the owning shop.

Every set_up_creative_boost action requires a total_creative_boost_cost guardrail (lifetime spend cap) — missing one returns 422 TOTAL_BUDGET_CAP_REQUIRED. Each campaign_id can only belong to one active automation at a time — conflicts return 422 CAMPAIGN_ALREADY_ASSIGNED.

Body parameter

{
  "name": "string",
  "template_type": "string",
  "trigger_frequency": "daily",
  "campaign_ids": [
    "string"
  ],
  "conditions": [
    {
      "metric": "creative_roi",
      "operator": "lt",
      "value": 0,
      "lookback_days": 3
    }
  ],
  "actions": [
    {
      "action_type": "set_up_creative_boost",
      "params": {}
    }
  ],
  "guardrails": [
    {
      "rule_type": "total_creative_boost_cost",
      "operator": "lt",
      "value": 0
    }
  ],
  "boost_start_date": "2019-08-24",
  "boost_end_date": "2019-08-24"
}

Parameters