The Product API

Overview

A Product API source works in two directions, and you can use either or both:

• Pull — we send a GET to an address you own, on the schedule set on the source, and you return your whole catalogue.
• Push — you POST changed products to us the moment they change.

The dashboard's API tab carries this same reference with your brand's real addresses already filled in, so start there when you are wiring it up.

Pull — we read your address

The request we send

A single GET. There is no pagination: return everything in one response.

Plus any extra headers you configured on the source.

Your address must use https, on the first request and on every redirect. Private and internal addresses are refused.

What you return

There is one shape, whether or not your products have versions. A product that sells in several flavors, sizes or colors carries a variants list; a product that does not carries its own price and availability instead.

{
  "products": [
    {
      "id": "whey-gold",
      "title": "Whey Gold protein powder",
      "link": "https://shop.example.com/products/whey-gold",
      "description": "Whey protein concentrate with added digestive enzymes.",
      "image": "https://shop.example.com/images/whey-gold.jpg",
      "brand": "Acme Nutrition",
      "category": "Protein > Whey",
      "priority": 820,
      "attributes": {
        "Ingredients": ["whey protein concentrate (milk)", "cocoa"],
        "Serving": "1 scoop (32 g) a day"
      },
      "search_terms": ["whey", "protein shake"],
      "rule_keys": ["whey protein"],
      "variants": [
        {
          "id": "10803",
          "options": { "Flavor": "Pistachio", "Size": "1 kg" },
          "price": "39.90 EUR",
          "availability": "in stock",
          "link": "https://shop.example.com/products/whey-gold?variant=10803",
          "attributes": {
            "Nutrition per serving": { "Energy": "128 kcal", "Protein": "24 g" }
          },
          "priority": 950,
          "rule_keys": ["pistachio"]
        },
        {
          "id": "10804",
          "options": { "Flavor": "Pistachio", "Size": "2.3 kg" },
          "price": "79.90 EUR",
          "sale_price": "69.90 EUR",
          "availability": "out of stock"
        }
      ]
    },
    {
      "id": "SKU-1001",
      "title": "Vitamin C 1000 mg, 60 tablets",
      "link": "https://shop.example.com/products/vitamin-c-1000",
      "description": "High-dose vitamin C in an easy-to-swallow tablet.",
      "price": "12.90 EUR",
      "sale_price": "9.90 EUR",
      "availability": "in stock",
      "brand": "Acme Health",
      "category": ["Vitamins", "Vitamin C"],
      "attributes": {
        "Ingredients": ["ascorbic acid", "rose hip extract"],
        "Form": "tablet"
      },
      "rule_keys": ["ascorbic acid"],
      "rules": ["Vitamin C contributes to the normal function of the immune system."]
    }
  ]
}

Timing and failure

Three attempts per read (30 seconds each, waiting 5 then 15 seconds), but only for timeouts, network errors and 5xx. A 4xx fails immediately. The response body may be up to 50 MB and contain at most 20,000 products.

Returning zero products counts as a failure, so a broken endpoint can never silently empty the catalogue.

The product object

Required

Optional

The version object

Each entry in variants is one thing a customer can buy. Only id is required.

attributes — your own fields

An object whose values are a string, number, boolean, an array of those, or one level of nested object — which is how you send something like a nutrition table:

"attributes": {
  "Serving": "1 scoop (32 g)",
  "Nutrition per serving": { "Energy": "128 kcal", "Protein": "24 g", "Fat": "2.2 g" }
}

Nesting deeper than one level makes the whole product invalid — not just that one field.

rule_keys and rules

Both are stored but never made searchable. They exist only for product rules.

• rule_keys decide which rules apply to this product.
• rules are sentences the AI receives verbatim, every time this product appears in an answer.

What is not searchable

price, sale_price and availability are deliberately never part of what the AI learned — they change constantly and are read live from the versions when an answer is written. The AI cannot search on them.

search_terms are the mirror image: they are only searchable. They help the search find a product and are never shown to the AI, so a product's nicknames cannot leak into a sentence.

Invalid items

Invalid items are skipped, never fatal — the run continues and the report lists the first 50 with the reason. If the same id appears twice in one payload, the last one wins.

One version is not skipped on its own. If any version of a product fails validation, the whole product is skipped, so the catalogue never holds a product that is quietly missing half its sizes. The report counts these separately as "Versions that stopped a product".

Push — you send us changes

The endpoint

POST https://yaplet.com/api/products/push/{sourceId}

{sourceId} is the source's id — copy it from the Copy push URL button on the Sources tab.

Authentication

Send your organisation API key in the Y-API-Key header. This is the key from Settings → API, not the source's shared secret.

The body

const res = await fetch("https://yaplet.com/api/products/push/YOUR_SOURCE_ID", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Y-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({
    mode: "merge",
    products: [
      {
        id: "SKU-1001",
        title: "Vitamin C 1000 mg, 60 tablets",
        link: "https://shop.example.com/products/vitamin-c-1000",
        price: "12.90 EUR",
        availability: "in stock",
        attributes: { Ingredients: ["ascorbic acid"] },
        rule_keys: ["ascorbic acid"],
      },
    ],
    deleted_ids: ["SKU-0999"],
  }),
});

const result = await res.json();
console.log(result.run_id, result.accepted);

curl -X POST "https://yaplet.com/api/products/push/YOUR_SOURCE_ID" \
  -H "Content-Type: application/json" \
  -H "Y-API-Key: YOUR_API_KEY" \
  -d '{
    "mode": "merge",
    "products": [
      {
        "id": "SKU-1001",
        "title": "Vitamin C 1000 mg, 60 tablets",
        "link": "https://shop.example.com/products/vitamin-c-1000",
        "price": "12.90 EUR",
        "availability": "in stock",
        "attributes": { "Ingredients": ["ascorbic acid"] },
        "rule_keys": ["ascorbic acid"]
      }
    ],
    "deleted_ids": ["SKU-0999"]
  }'

$payload = json_encode([
    "mode" => "merge",
    "products" => [[
        "id" => "SKU-1001",
        "title" => "Vitamin C 1000 mg, 60 tablets",
        "link" => "https://shop.example.com/products/vitamin-c-1000",
        "price" => "12.90 EUR",
        "availability" => "in stock",
        "attributes" => ["Ingredients" => ["ascorbic acid"]],
        "rule_keys" => ["ascorbic acid"],
    ]],
    "deleted_ids" => ["SKU-0999"],
]);

$ch = curl_init("https://yaplet.com/api/products/push/YOUR_SOURCE_ID");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Y-API-Key: YOUR_API_KEY",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode >= 200 && $httpCode < 300) {
    $result = json_decode($response, true);
    echo "Run: " . $result["run_id"];
} else {
    echo "Error " . $httpCode . ": " . $response;
}

import requests

url = "https://yaplet.com/api/products/push/YOUR_SOURCE_ID"
headers = {
    "Content-Type": "application/json",
    "Y-API-Key": "YOUR_API_KEY",
}
body = {
    "mode": "merge",
    "products": [
        {
            "id": "SKU-1001",
            "title": "Vitamin C 1000 mg, 60 tablets",
            "link": "https://shop.example.com/products/vitamin-c-1000",
            "price": "12.90 EUR",
            "availability": "in stock",
            "attributes": {"Ingredients": ["ascorbic acid"]},
            "rule_keys": ["ascorbic acid"],
        }
    ],
    "deleted_ids": ["SKU-0999"],
}

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

if response.ok:
    result = response.json()
    print("Run:", result["run_id"])
else:
    print("Error", response.status_code, response.text)

What you get back

A successful push answers 202 Accepted:

{
  "run_id": "3f9d2c6e-1b7a-4c1e-9f0a-2d8e5b6c7a90",
  "status": "running",
  "received": 1,
  "accepted": 1,
  "invalid": 0,
  "report_url": "/api/products/push/YOUR_SOURCE_ID/runs/3f9d2c6e-1b7a-4c1e-9f0a-2d8e5b6c7a90"
}

Checking a run

GET https://yaplet.com/api/products/push/{sourceId}/runs/{runId}

Same Y-API-Key header. Poll until status is no longer "running", then read the counters and, if status is "failed", the error and error_code fields.

Push semantics

• merge touches only the ids you send. Everything you leave out is untouched.
• deleted_ids are product ids, not version ids. Deleting a product deletes its versions with it. An id you do not own, or that does not exist, is ignored silently. If an id is in both products and deleted_ids, the product wins.
• mode: "replace" deletes every product of this source that is not in the payload.

Products whose content has not changed cost nothing — they are not re-indexed. Changing only price, sale price or availability updates the row without re-indexing anything.

A successful push also brings back products that were hidden because the source had been failing. It does not restart a schedule that stopped after three failed reads — only Fetch now does that.

Errors

Rate limits

12 pushes per minute per source, and 60 per minute per organisation. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Things that catch people out