Skip to main content

Product Integration

Before You Start

Before beginning product integration, make sure to review the Data Source Management console. This tool enables you to track feed or API ingestion, validate product data with the assigned Data Source UUID, and quickly identify issues such as missing fields or processing errors. Monitoring this view ensures that product records are properly synced and eligible for ad serving before you proceed with campaign and placement setup.

ℹ️ For more details, see Data Source Management

Link to Advertisers

It’s important to call the advertiser API before sending products that reference new advertisers. Ensure that for each advertiser_id used in product data, there is an active advertiser record in the system. If an advertiser is missing, product API calls will likely return an error for those products (e.g., "Invalid advertiser_id"). Once advertisers are in place, you can send products with those advertiser_ids and the platform will link them.

Product Ingestion API​

The primary endpoint for sending product data is:

POST /integration/products This endpoint accepts a JSON payload containing your marketplace ID and an array of product objects. The marketplace_id is a unique identifier for your retail network or account in GoWit’s system (it ensures the data goes to the correct marketplace context). GoWit will provide this ID during onboarding. Each API call can include multiple products – up to 10,000 products or 50 MB of JSON in one request is supported, allowing efficient bulk uploads if needed.

See the Product Schema for the full field list.

Sample Product JSON Payload​

When calling the product API, format your JSON as follows: include the marketplace_id and a list of products. Each product in the list is a JSON object with the necessary fields. For example:

{
  "marketplace_id": 123,         // your assigned marketplace ID
  "products": [
    {
      "id": "123456",
      "name": "Black Leather Ankle Boots",
      "advertiser_id": "67890",
      "image_url": "https://yourcdn.com/images/boots.jpg",
      "retailer_taxonomy": "Shoes > Boots > Leather",
      "status": "ACTIVE",
      "description": "Stylish black leather ankle boots for any occasion.",
      "price": 129.99,
      "brand": "XYZ Shoes",
      "stock": 20,
      "rating": 4.5
    },
    {
      "id": "ABC-789",
      "name": "Blue Denim Jacket",
      "advertiser_id": "67890",
      "image_url": "https://yourcdn.com/images/jacket.jpg",
      "retailer_taxonomy": "Clothing > Jackets > Denim",
      "status": "ACTIVE",
      "price": 89.50,
      "brand": "FashionCo",
      "stock": 15
    }
    // ... more products as needed ...
  ]
}

Ensure each product object includes all required fields. If any required field is missing or null, the API will reject that product and return an error for it. (Required fields for API are the same as for feed. Optional fields can be provided to enrich the data, just like in feeds.)

Ensure each product object includes all required fields. If any required field is missing or null, the API will reject that product and return an error for it. (Required fields for the API are the same as for the feed. Optional fields can be provided to enrich the data, just like in feeds.

Updating and Deleting via API​

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

Update a Product​

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

Deactivate/Delete a Product​

Send that product with "status": "DELETED" in a POST request. Marking status as DELETED will immediately make that product inactive on the platform (it won’t show in active listings or be eligible for new ads).

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 product not included in that process as deleted.

Essentially, you:

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

Below is a sample curl command to send product data to the GoWit Product Ingestion API:

curl --location '<YOUR_BASE_URL>/integration/products' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Data-Source-UUID: <YOUR_DATA-SOURCE-UUID>' \
--header 'Content-Type: application/json' \
--data '{
    "marketplace_id": 19,
    "products": [
        {
            "retailer_taxonomy": "Rustic>Copper>Computer",
            "image_url": "http://lorempixel.com/320/200/nature/",
            "price": 537,
            "name": "Heavy Duty Wooden Wallet 2222222",
            "id": "162-49-442242",
            "stock": 277,
            "advertiser_id": "05301C331B03",
            "status": "ACTIVE",
            "process_id": 1234
        },
        {
            "retailer_taxonomy": "Rustic>Copper>Computer",
            "image_url": "http://lorempixel.com/320/200/nature/",
            "price": 53,
            "name": "Heavy Duty Wooden Wallet",
            "id": "162-49-442242",
            "stock": 27,
            "advertiser_id": "05301C331B023",
            "status": "ACTIVE",
            "process_id": 1234
        }
    ]
}'
  1. Call
    PATCH /integration/products
    with that process_id and status: DELETED to deactivate any product not in the batch.
curl --location --request PATCH '<YOUR_BASE_URL>/integration/products' \
--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 product 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 product feed is typically an XML file containing a list of products. Each product 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:

Minimal XML Feed Example with Required Fields​

<!-- Minimal XML feed example with required fields -->
<products>
  <product>
    <product_id>123456</product_id>
    <name>Black Leather Ankle Boots</name>
    <advertiser_id>67890</advertiser_id>
    <image_url>https://yourcdn.com/images/boots.jpg</image_url>
    <retailer_taxonomy>Shoes &gt; Boots &gt; Leather</retailer_taxonomy>
    <status>Active</status>
  </product>
</products>

Extended XML Feed Example Including Optional Fields​

<!-- Extended example including optional fields -->
<products>
  <product>
    <product_id>123456</product_id>
    <name>Black Leather Ankle Boots</name>
    <advertiser_id>67890</advertiser_id>
    <image_url>https://yourcdn.com/images/boots.jpg</image_url>
    <retailer_taxonomy>Shoes &gt; Boots &gt; Leather</retailer_taxonomy>
    <status>Active</status>
    <description>Stylish black leather ankle boots for any occasion.</description>
    <price>129.99</price>
    <brand>XYZ Shoes</brand>
    <buybox>true</buybox>
    <stock>20</stock>
    <rating>4.5</rating>
  </product>
  <!-- ...other products... -->
</products>

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 products currently in your catalog. Any previously imported product 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 products in the file at all; removal is inferred by their absence.

  • Partial Feed (Status-Based): Each feed file always includes all products, and you explicitly set the status field (Active or Deleted) for each. A product 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 product.

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.)