Documentation

Send us your catalog

One endpoint, one payload shape, one credential. You send products in your own words; we resolve them to BrandsGateway IDs and tell you exactly what happened to each one.

The whole thing, in one call

This is the entire contract. Everything else on this site explains a piece of it.

PUT /api/v1/products/{yourProductId}

curl -X PUT https://vendors.brandsgateway.com/api/v1/products/SKU12345 \
  -u "$BG_USER:$BG_APP_PASSWORD" \
  -H "X-Vendor-Id: $BG_VENDOR_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "values": {
    "brand": "Gucci",
    "gender": "Women",
    "color": "Brown",
    "material": "Calf Leather",
    "country": "Italy",
    "category": "Bags Women",
    "group": "Shoulder Bags",
    "condition": "New with tags"
  },
  "product": {
    "type": "simple",
    "name": "Leather Shoulder Bag",
    "sku": "SKU12345",
    "regular_price": "1250.00",
    "sale_price": "875.00",
    "stock_quantity": 3,
    "manage_stock": true,
    "global_unique_id": "4068849312345",
    "images": [
      { "src": "https://cdn.yourshop.com/12345_1.jpg" },
      { "src": "https://cdn.yourshop.com/12345_2.jpg" }
    ],
    "meta_data": [
      { "key": "_external_id",   "value": "SKU12345" },
      { "key": "_vendor_sku",    "value": "SKU12345_V" },
      { "key": "_vendor_cost",   "value": "610.00" },
      { "key": "_import_source", "value": "yourshop" }
    ]
  }
}'

Three things this shows

Your ID, not ours. The URL ends with your own product identifier. First call creates it, every call after updates it — so re-sending the same product never makes a duplicate.

Your words, not our IDs. Put brand, colour and category in values exactly as your system writes them. You never build a mapping table.

One credential. The same BrandsGateway username and application password works on every endpoint here, monitoring included.

Start here

Three pages, in order, and you are integrated. About twenty minutes.

Send your first product

Credentials, one call, a live product. Six steps, about twenty minutes.

Every field explained

What each field must contain, which ones are required, and what breaks without them.

Check it worked

Test a payload before you send it, then see the outcome of every product.

In a hurry? Paste a payload into the validator and it will tell you what is wrong with it before you send anything.

Four rules that will save you a day

Read these now. They are the four things that surprise people, and each one is a support ticket you will not have to open.

Your feed decides what is in stock

Every sync overwrites the stock number — it does not adjust it. Anything changed on our side is temporary and goes back on your next run. Drop a product from your feed and its stock goes to zero; it is not deleted. Sync lifecycle

Never reuse an external ID

It is how we recognise a product forever. Reusing one for a different item silently overwrites the first. It must also be alphanumeric — a hyphen breaks the product URL.

Barcodes are shared across the whole marketplace

If another vendor already lists the same item under that EAN, yours is rejected and we name the conflicting listing. That is a commercial question, not a bug. What to do about it

Nothing fails silently

Every product that does not land is recorded with a reason, the field it concerns, and the run it happened in. Your dashboard groups them by cause, so one mapping fix usually clears hundreds of rows at once.

Look it up when you hit it

Reference, not a reading list. The validator and your dashboard link straight to the right entry when something goes wrong.

Error reference

Every rejection code and its fix. Your dashboard links here.

Taxonomy & IDs

Let us resolve your names to IDs — or map them yourself.

Sync lifecycle

Upsert, images, going out of stock, archival.

Examples

Working payloads and client code in four languages.

Authentication

Credentials, scope and rate limits in full.

Testing locally

Build against a local BrandsGateway, not production.

Why this exists

Every vendor used to be integrated by hand: BrandsGateway built a pipeline per supplier and maintained the field mapping in code. It worked, but you could not ship a catalog change without us, and you could not see why a product never appeared.

This inverts that. Everything the old pipeline did on your behalf — resolving names to IDs, mapping sizes, checking prices — is specified here, checkable before you send, and visible after.