The Product API
The developer reference for a Product API source — the JSON your shop serves for us to read, and the endpoint your shop pushes changes to as they happen.
Overview
A Product API source works in two directions, and you can use either or both:
- Pull — we send a
GETto an address you own, on the schedule set on the source, and you return your whole catalog. - Push — you
POSTchanged products to us the moment they change.
The API tab of the brand's Products page (Brand → (your brand) → Products → API) 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.
| Header | Value |
|---|---|
Accept | application/json |
User-Agent | YapletBot/1.0 (+https://yaplet.com) |
Signature | The SHA-256 hash of your shared secret, lowercase hex |
Plus any extra headers you configured on the source.
Signature is a plain hash of the shared secret — not an HMAC over the body, and it does not change between requests. Verify it by hashing your own copy of the secret and comparing. Treat it as a bearer token protected by TLS, not as a request signature: it cannot detect replay or tampering.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,
"popularity": 1240,
"rating": 4.8,
"review_count": 312,
"added_at": "2025-03-14",
"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,
"popularity": 410,
"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": ["Do not exceed the recommended daily dose."]
}
]
}
variants is stored as a product with exactly one version, carrying the price and availability you sent on the product itself. You do not have to change anything to keep working — adding variants is how you get grouped flavors and sizes when you want them.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 catalog.
The product object
Required
1001 and "1001" are the same product.http or https URL, up to 2048 characters.Optional
http or https URL."12.90 EUR" is fine. Used only when the product has no variants.price. Used only when the product has no variants.variants.> between the levels ("Protein > Whey") or a list of levels (["Protein", "Whey"]). A deeper path makes the item invalid.4.8. Leave it out when the product has no reviews — never send 0. Left out, the versions' ratings are averaged, weighted by their review counts.YYYY-MM-DD — a full ISO date-time is accepted and cut to the day. Used for "what's new". Left out, the earliest version's date is used.The version object
Each entry in variants is one thing a customer can buy. Only id is required.
name: value — { "Flavor": "Pistachio", "Size": "1 kg" }. At most 5 options, names up to 40 and values up to 60 characters. The order you send them in is the order we show them in, so send them the way you want them read.popularity lets your AI say which flavor or size is the most popular; send rating and review_count per version only if you collect reviews per version.rules are instructions for that version only.variants, the product's own price, sale_price and availability are ignored — the versions carry them. The run report counts this as "Product prices ignored (versions sent)", so a non-zero figure there means you are sending both and one of them is doing nothing.variants is not a special case internally: it becomes a product with one unnamed version holding the price and availability you sent. That is why an older feed keeps working untouched.sku, url, image_link, salePrice and product_url are all ignored — use exactly the names above. Unknown keys are ignored silently.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" }
}
"Pack size": "12,5 kg" becomes two values, 12 and 5 kg. Use an array for anything that legitimately contains a comma or semicolon.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 claims and instructions.
rule_keysgive the product its keys, together with the product fields your source turns into keys. A claim or instruction from the Claims or Instructions tab applies to the product when they share a key.rulesare sentences the AI receives verbatim, every time this product appears in an answer, as the product's own instructions. They are never claims: to let your AI say what a product does, write a claim on the Claims tab.
rule_keys means the AI can never find the product by that ingredient. Put it in attributes as well if customers search for it.Order and sorting: priority, popularity, rating, review_count, added_at
All of them are optional. Every list your AI shows comes in one order, called "most popular": products with a priority first, in priority order, then the rest by popularity. Your AI may present that order as your shop's most popular products — for the whole shop or for one category — and it answers a "what are your best / top / best-selling / trending products?" question with it. A version's popularity lets it say which flavor or size of a product is the most popular.
Other orders are used only when the visitor asks for them:
ratingwithreview_countanswers "which one is rated highest?" — always said together with the rating and the number of reviews.added_atanswers "what's new?".- "What's the cheapest?" (or the most expensive) needs nothing extra, as long as every price in the catalog is in one currency. It goes by what a visitor actually pays, sale price included.
Without the data, your AI never makes that claim: no product is called highest rated, new or cheapest, and when none of the matching products carries a priority or a popularity, the list is simply alphabetical and nothing in it is called most popular. Products whose every version is out of stock always come last, in every order and every category list.
priority is presented as popularity. The products you give one lead every list and are shown as your most popular products, so set it only where you are happy to see that. Your AI says nothing else about how well a product sells, and never calls a single product "the best".These fields also decide what Yaplet learns first when credit runs short: priority, then popularity, then review_count, then rating (highest first, products without a value last), then the order you sent them in. See When credit runs short below.
What is not searchable
price, sale_price and availability are never part of what the AI learned — they change constantly and are read live from the versions when an answer is written. The search cannot match on them; the AI's catalog lookup can still filter by them — a price limit, in stock, on sale — using the live values.
search_terms work the other way round: they help the search find a product, and the AI sees them only as the product's other names. It confirms one when a visitor uses it, but never volunteers them and never repeats one that looks like a misspelling.
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. An item that holds more than 50,000 values — every field and list entry in it, nested ones included — is skipped too, with the reason "item: holds more than 50,000 values, far more than a product".
One version is not skipped on its own. If any version of a product fails validation, the whole product is skipped, so the catalog 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. It is the last part of the push address, which you can copy with Copy push address in the ⋯ menu of the source's row on the Sources tab (Product API sources only), or from the Push address line on the API tab.
Authentication
Send your workspace API key in the Y-API-Key header. This is the key from Settings → Connections → MCP & API keys, not the source's shared secret.
The body
| Field | Default | Meaning |
|---|---|---|
mode | "merge" | "merge" updates only what you send. "replace" makes this push a full snapshot. |
products | [] | Product objects, exactly as above. |
deleted_ids | [] | Products to remove. Ignored in replace mode. |
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"
}
202 does not mean the products landed. Your items have been validated, but the import itself runs in the background — limits, storage and indexing can still fail afterwards. Poll the run to be sure.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.
run_id then returns 404. Read a report before you send the next push. A failed run still answers 200; check the status field, not the HTTP code.Push semantics
mergetouches only the ids you send. Everything you leave out is untouched.deleted_idsare 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 bothproductsanddeleted_ids, the product wins.mode: "replace"deletes every product of this source that is not in the payload.
variants list you want it to end up with. A version you leave out of that list is deleted.{"mode": "replace", "products": []}deletes every product of the source. Unlike a pull, there is no empty-payload guard on replace.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.
When credit runs short
A workspace that pays from credit (the free 14 days or bought credit, no paid plan) learns products only until 500 credits are left, so the rest goes to answers. Below that line:
- A push is still accepted with
202, and a scheduled read or Fetch now still runs. - Products Yaplet already knows update at once: price, sale price, availability and versions.
- New or changed products wait. They are not stored, so a new product does not appear yet. They are tried again the next time they arrive, in a scheduled read or in a later push that includes them. A product that changed and is waiting keeps its old row, price and stock included, until it is learned.
- A product that waits is never deleted: deletions are worked out from everything you sent.
- A source is never stopped, emailed about or switched off for lack of credit.
Adding credit puts a source with a schedule back in the queue, and its waiting products are learned again within about an hour. A paid plan has no such line.
The run report counts what waited, next to the existing counters:
| Field | Meaning |
|---|---|
skipped_for_credit | Products left out because credit is at the 500-credit line. |
skipped_for_room | Products left out because there was no room for them, as on some older free workspaces. |
learning_paused | true when the credit line was reached part-way through the run. |
The products learned are accepted minus skipped_for_credit minus skipped_for_room.
Errors
| Code | When |
|---|---|
400 | Malformed JSON, a bad mode, more than 20,000 items, or an empty merge |
401 | Missing or invalid Y-API-Key |
403 | Your workspace lacks the Content sources permission |
404 | Unknown source, a source in another workspace, or a Product feed or shop source |
409 | Another read or push is running for this source — wait and retry |
411 | No Content-Length — chunked uploads are not accepted |
413 | Body larger than 25 MB |
413 | The body holds far more than any real product feed: more than 1,000,000 objects and lists, 1,500,000 values or 100,000 different field names. It is refused before its products are looked at |
429 | Too many requests. Retry-After tells you how long to wait |
429 | Too many product pushes are being processed right now: "Too many product pushes are being processed right now. Try again in 30 seconds." Nothing was processed; the answer carries Retry-After: 30, so send the push again after that many seconds |
Rate limits
12 pushes per minute per source, and 60 per minute per workspace. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
413 and an over-count push with 400. Adding credit or starting a subscription restores the full limits immediately, and the free 14 days of a new workspace carry the full limits too.The API tab always prints the numbers in force for your own workspace, and says when they are the free set — so check there rather than assuming the figures above.Things that catch people out
The product moves to whichever source delivered it last, losing the keys and rules sentences the previous source sent. Do not run two sources over an overlapping id space.
Extra headers configured on the source are applied last, so naming one Signature, Accept or User-Agent silently replaces ours.
JSON forbids leading zeros in numbers, so send those ids as strings.
Unlike a failed scheduled read, a failed push does not count as a strike and nobody is emailed. Only your polling code will notice.
A version that fails validation takes its entire product out of the run — an invalid version is never silently dropped on its own. The report counts it as "Versions that stopped a product" and names the first reason, so check that counter when a product you definitely sent is missing.
We keep the order you send options in, so {"Color": …, "Size": …} reads "Color · Size" and the reverse reads "Size · Color". If the order on screen is not what you expect, it is the order in your payload.
The versions win and the product's price is ignored — it is not an error and nothing warns you in the moment. The run report's "Product prices ignored (versions sent)" counter is the only signal.
The whole item is refused, not trimmed. If your shop has deep taxonomies, flatten the tail into the last level before sending.