Sync catalogs

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

POST /api/v2/buyer/advertisers/{advertiserId}/catalogs/sync Inbound ADCP sync_catalogs endpoint. Buyers call this to sync catalog feeds and items onto the advertiser. Provide either a remote feed url or inline items per catalog — not both. For an agent on the account-resolved V3 MCP surface, use save_catalog instead. It saves exactly one catalog per request and requires an idempotency key, so a retry returns the original outcome rather than applying another update. Its request is one flat catalog object, not a catalog wrapper. A URL is re-fetched on each save; archive through the same tool with isArchived: true and the catalog identity instead of looking for a separate delete operation:

{
  "catalogId": "summer-sale-2026",
  "advertiserId": "12345",
  "name": "Summer Sale 2026",
  "type": "product",
  "url": "https://feeds.acme.com/products.xml",
  "feedFormat": "google_merchant_center",
  "updateFrequency": "daily",
  "idempotencyKey": "save-summer-sale-2026-0001"
}

The Catalogs Page saves through save_catalog, not this operation. Choose Add feed to connect a hosted URL or upload a CSV, TSV, XLS, XLSX, or JSON file. For an existing hosted feed, choose Sync now, which saves the feed again and fetches it. For an existing uploaded feed, choose Replace file. The Page shows each feed’s health, what its last sync changed, its transform and its newest versions and syncs. When the feed address cannot be fetched without signing in, such as a Google Drive or SharePoint share link, the Page shows the API’s message and what to do next. The Page no longer shows per-item approval counts or rejected rows, because the platform does not record an item review result. It does not copy a generated instruction into chat. If you give Apostra an exact feed URL or inline item payload, Apostra saves it with save_catalog.

Request

curl

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/catalogs/sync \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": { "account_id": "12345" },
    "catalogs": [
      {
        "catalog_id": "summer-sale-2026",
        "type": "product",
        "name": "Summer Sale 2026",
        "url": "https://feeds.acme.com/products.xml",
        "feed_format": "google_merchant_center",
        "update_frequency": "daily",
        "conversion_events": ["purchase", "add_to_cart"]
      }
    ],
    "delete_missing": false,
    "validation_mode": "strict"
  }'

Parameters

Field	Type	Required	Notes
`advertiserId`	string (path)	Yes	Unique identifier for the advertiser
`account.account_id`	string	Yes	Advertiser ID to attach catalogs to
`catalogs`	array	Yes	Catalog feeds to sync (1–50 per call)
`catalogs[].catalog_id`	string	Yes	Buyer-assigned catalog identifier
`catalogs[].type`	enum	Yes	`product`, `offering`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination`
`catalogs[].name`	string	No	Display name (1–255 chars)
`catalogs[].url`	string	No	Remote feed URL. Provide this or `items`, not both
`catalogs[].items`	array	No	Inline catalog items (max 10000). Provide this or `url`, not both
`catalogs[].feed_format`	enum	No	`google_merchant_center`, `facebook_catalog`, `shopify`, `linkedin_jobs`, `custom`
`catalogs[].update_frequency`	enum	No	`realtime`, `hourly`, `daily`, `weekly`
`catalogs[].conversion_events`	array	No	Conversion event IDs linked to this catalog
`catalog_ids`	array	No	Only process these `catalog_id`s from the `catalogs` array
`delete_missing`	boolean	No	Archive buyer-managed catalogs not in this request. Default `false`
`dry_run`	boolean	No	Preview changes without persisting. Default `false`
`validation_mode`	enum	No	`strict` (default) or `lenient` item validation

Response

{
  "catalogs": [
    {
      "catalog_id": "summer-sale-2026",
      "action": "created",
      "platform_id": "cat_abc123",
      "item_count": 1840,
      "items_approved": 1832,
      "items_pending": 0,
      "items_rejected": 8,
      "item_issues": [
        { "item_id": "sku_4471", "field": "image_link", "issue": "unreachable URL", "severity": "error" }
      ],
      "last_synced_at": "2026-06-07T12:00:00Z",
      "next_fetch_at": "2026-06-08T12:00:00Z"
    }
  ],
  "dry_run": false
}

Each result carries an action of created, updated, unchanged, failed, or deleted. Item-level problems appear in item_issues with severity error or warning. When dry_run was true, nothing is persisted.

Errors

400 VALIDATION_ERROR — a catalog supplies both url and items, exceeds 50 catalogs, or fails strict item validation.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

Advertiser tasks

All advertiser operations

Advertiser overview

Fields, lifecycle, and concepts

List catalogs

See synced catalogs

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Advertiser tasks

Advertiser overview

List catalogs

​Request

​Parameters

​Response

​Errors

​Related

Advertiser tasks

Advertiser overview

List catalogs

Request

Parameters

Response

Errors

Related