Skip to main content

Advertiser Integration

Before You Start

Before beginning advertiser integration, ensure you are familiar with the Data Source Management console. This tool allows you to trace ingestion activity, monitor advertiser syncs, and debug potential issues using the assigned Data Source UUID. By checking logs and status flags here, you can confirm that advertiser records are processed correctly before proceeding to campaign setup and ad serving. Using this visibility early helps reduce integration errors and ensures smoother QA and go-live phases.

ℹ️ For more details, see Data Source Management

Remember that products reference advertisers via advertiser_id. Thus, the advertiser’s id field value is what must match the advertiser_id in product records. Keep these consistent. For example, if you have an advertiser with id = 67890 (as in the examples above), then products for that advertiser should use 67890 in the feed or "advertiser_id": "67890" in the JSON. Typos or case mismatches will cause link failures (IDs are usually case-sensitive strings). A common pitfall is an extra space or leading zero in an ID in one place but not the other – ensure consistent formatting.

Advertiser Ingestion API​

GoWit provides an endpoint to create or update advertiser records via API. The endpoint is:

POST /integration/advertisers This expects a JSON payload with your marketplace_id and an array of advertisers. Each advertiser object would at least include the advertiser’s id (unique advertiser identifier in your system), name (advertiser name), and status (e.g. ACTIVE or DELETED).

See the Advertiser Schema for the full field list.

Sample Advertiser JSON Payload​

{
  "marketplace_id": 123,
  "advertisers": [
    {
      "id": "vendor_001",
      "name": "Brand One",
      "status": "ACTIVE"
    },
    {
      "id": "vendor_002",
      "name": "Brand Two",
      "status": "ACTIVE"
    }
  ]
}

This would create two advertisers (or update them if they already exist). The same headers and auth apply for this endpoint (Authorization token, JSON content type, etc.), and include Data-Source-UUID.

Updating and Deleting via API​

The advertiser API support upserts for create/update and provide a mechanism for deletions:

Update an Advertiser:​

Simply send an object with the same id and the fields you want to change.
For advertisers, the POST /integration/advertisers call acts as both create and update – if the advertiser ID already exists, it will update that record with new values (e.g., status change) and the response will count it under updated rather than created.

Deactivate/Delete an advertiser via API:​

Send that advertiser with "status": "DELETED" in a POST request. Marking status as DELETED will immediately make that advertiser inactive on the platform. (which usually also pauses its campaigns).

Full Catalog Sync via API​

If you prefer an approach where each API batch represents a full snapshot (similar to a full feed) and want the system to auto-remove missing items, GoWit’s API provides an optional two-step process using the process_id.

When you do a POST, the request includes a process_id. You can then call a special PATCH endpoint to instruct the system to mark any advertiser not included in that process as deleted.

Essentially, you:

  1. Send the full list of advertisers via
    POST /integration/advertisers
    with a flag indicating start of full sync (the process_id is included). cURL Example for Advertiser Ingestion API

Below is a sample curl command to send advertiser data to the GoWit Advertiser Ingestion API:

curl --location '<YOUR_BASE_URL>/integration/advertisers' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Data-Source-UUID: <YOUR_DATA-SOURCE-UUID>' \
--header 'Content-Type: application/json' \
--data '{
  "marketplace_id": 19,
  "advertisers": [
    {
      "id": "vendor_001",
      "name": "Brand One",
      "status": "ACTIVE"
      "process_id": 1234
    },
    {
      "id": "vendor_002",
      "name": "Brand Two",
      "status": "ACTIVE"
      "process_id": 1234
    }
  ]
}'
  1. Call
    PATCH /integration/advertisers
    with that process_id and status: DELETED to deactivate any advertisers not in the batch.
curl --location --request PATCH '<YOUR_BASE_URL>/integration/advertisers' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "marketplace_id": 19,
    "process_id": 1234,
    "status": "DELETED"
}'

It’s important to note that the process_id should be unique for each batch set. For example, if you send us 150 batches with one process_id, and after marking the non-matching items as ‘DELETED’, this process is considered complete. For subsequent batches later, ensure to use a different process_id. This practice keeps your advertiser feeds organized and current in our system.

In most cases, a combination of POST (for upserts) and either individual deletions or occasional full-sync logic can keep the data up-to-date.
If your use-case is incremental (most updates are additions or changes), you might not need the process_id approach often. It’s there for convenience when doing complete replacements of data via API.

Feed File Structure​

Your advertiser feed is typically an XML file containing a list of advertisers. Each advertiser in the feed should include all required fields.
Below is an example of a minimal XML feed with only the mandatory fields, followed by an extended example including optional fields:

XML Feed Example with Required Fields​

<!-- Minimal XML feed example with required fields -->
<sellers>
    <seller>
            <id>1234</id>
            <name>Nexora</name>
            <status>ACTIVE</status>
    </seller>
</sellers>

Full vs Partial Feeds​

When onboarding a feed, you will declare whether your feed will be “Full” or “Partial” in terms of content. This affects how deletions are handled

  • Full Feed: Every feed file delivered is a complete snapshot of all active advertisers currently in your catalog. Any previously imported advertisers that is absent in the latest full feed will be assumed removed and GoWit will automatically mark it as deleted (simulating a deletion). In this mode, you typically do not include discontinued advertisers in the file at all; removal is inferred by their absence.

  • Partial Feed (Status-Based): Each feed file always includes all advertisers, and you explicitly set the status field (Active or Deleted) for each. A advertiser is removed only if its status is set to "Deleted" in the feed; missing entries are not auto-removed. This mode requires that the status field be present and kept accurate for every advertiser.

Both approaches are supported – just ensure GoWit knows which strategy you’re using so it can configure ingestion accordingly. (If using partial feed mode, you must consistently include the Deleted entries until they drop from the catalog, otherwise they’d remain active indefinitely.)