Subscribe directed campaigns (alpha)

curl --request POST \
  --url https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

POST

api

buyer

storefront-connections

{connectionId}

accounts

{accountId}

directed-campaigns

Subscribe directed campaigns (alpha)

curl --request POST \
  --url https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.interchange.io/api/v2/api/v2/buyer/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Alpha and PostHog-gated. This operation mirrors existing upstream campaigns; it does not create or modify campaigns in the connected account.

Subscribe an active, non-organization adapter account that is already mapped to the requested advertiser. The first sync enumerates get_media_buys without IDs and backfills terminal history for one year; active campaigns are always mirrored. This backfill covers campaign metadata, not delivery reports. Named operation: subscribe_directed_campaigns

Field	Location	Type	Required	Description
`connectionId`	path	integer	Yes	Active adapter connection ID
`accountId`	path	integer	Yes	Connected ad-account row ID
`advertiserId`	body	numeric string	Yes	Advertiser already mapped to the account
`sourceId`	body	string	Yes	Adapter storefront platform ID returned by the mapping list

The request completes after the initial enumeration attempt. The response includes the durable subscription (backfillStart, lastSyncedAt, lastSyncStatus, and lastSyncError) plus the initial mirrored/retired/skipped counts. Calling the same operation again is idempotent and refreshes the mirror. The default metadata sweep runs every 15 minutes. Use the subscription-status operation for the latest metadata-sync health and fixed history boundary. There is no running backfill percentage or delivery-import status. Campaign summaries expose mode, provider, mirror state, and directed.lastSyncedAt for row-level freshness. When broad enumeration omits a campaign that is already mirrored, Interchange reads nonterminal upstream IDs through a bounded, resumable direct-read cycle before treating absence as authoritative. A complete terminal response preserves the campaign and its package history even when the provider returns an empty package list. Already-terminal local mirrors remain available without repeated provider reads. A failed or incomplete direct response marks the sync unhealthy and retains the last valid mirror.

Response

{
  "subscription": {
    "id": "17",
    "customerId": 100,
    "advertiserId": "12345",
    "connectionId": "42",
    "accountId": "81",
    "sourceId": "tiktok",
    "providerType": "tiktok",
    "status": "ACTIVE",
    "backfillStart": "2025-07-12T10:00:00.000Z",
    "lastSyncedAt": "2026-07-12T10:00:08.000Z",
    "lastSyncStatus": "SUCCESS",
    "lastSyncError": null,
    "errorCode": null,
    "errorField": null,
    "errorReason": null,
    "upstreamCode": null,
    "createdAt": "2026-07-12T10:00:00.000Z",
    "updatedAt": "2026-07-12T10:00:08.000Z",
    "archivedAt": null
  },
  "sync": {
    "subscriptionId": "17",
    "mirrored": 12,
    "retired": 0,
    "skipped": 0,
    "errors": []
  }
}

A successful enrollment response can contain sync errors. When errors is non-empty, the subscription remains durable with status ERROR and the worker retries; other provider-supported read operations remain available. A successful response with mirrored: 0 and no errors means no campaigns were eligible in the one-year metadata window. Neither outcome is a delivery backfill.

Errors and recovery

Error	Recovery
`FEATURE_NOT_ENABLED`	Ask the Interchange account team to enroll the customer in the alpha. Do not call an adapter endpoint directly.
Account or connection not found	Re-list the official adapter connection and its discovered accounts; use only returned IDs.
Account is not mapped	Map the discovered account to the intended advertiser, verify it with the mappings list, then retry.
Account is subscribed to another advertiser	Unsubscribe first, confirm which advertiser should own the mirror, remap, then subscribe again.
Meta targeting cannot be represented safely	Inspect the Meta ad set for unsupported geography exclusions, locales, interests, behaviors, or placement constraints. Included and excluded Custom Audiences are projected through `audience_include` and `audience_exclude`. The last complete mirror is retained; no partial targeting is published.
Upstream sync error	Inspect subscription health. Reconnect for authentication errors; otherwise retry after the provider recovers. Existing valid mirrors are retained.

See Directed campaigns (alpha).

⌘I

Getting Started

Advertisers

Campaigns

Product Discovery

Webhooks

Creatives

Signals & Brand

Audiences & Inventory

Measurement & Conversions

Reporting & Activity

Planning & Governance

Connections

Account & Billing

Subscribe directed campaigns (alpha)

Response

Errors and recovery

​Response

​Errors and recovery

Response

Errors and recovery