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 GET to an address you own, on the schedule set on the source, and you return your whole catalog.
  • Push — you POST changed 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.

Everything below applies to Product API sources only. A Product feed is a plain feed link from your shop system (Google Shopping, Heureka, Árukereső or Ceneo) — it has no push endpoint, no secret and no custom fields.

Pull — we read your address

The request we send

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

HeaderValue
Acceptapplication/json
User-AgentYapletBot/1.0 (+https://yaplet.com)
SignatureThe 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."]
    }
  ]
}
A feed written before versions existed is still a valid feed. A product with no 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.
A pull is always a full snapshot. Any product of this source that is missing from your response is deleted. If you want to send only changes, use push.

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

id
string or number required
Your stable identifier. 1–200 characters. Numbers are accepted and stored as text — so 1001 and "1001" are the same product.
title
string required
1–500 characters.
link
string required
The product page. Must be an http or https URL, up to 2048 characters.

Optional

description
string
Up to 20,000 characters. Indexed in full and shown to the AI in full.
image
string
An http or https URL.
price
string or number
Free text, up to 100 characters — "12.90 EUR" is fine. Used only when the product has no variants.
sale_price
string or number
Same rules as price. Used only when the product has no variants.
availability
string
Up to 100 characters. Used only when the product has no variants.
brand
string
Up to 200 characters.
category
string or string[]
The product's category as a path, at most 6 levels, each up to 100 characters. Either one string with > between the levels ("Protein > Whey") or a list of levels (["Protein", "Whey"]). A deeper path makes the item invalid.
priority
number
A number, 0 or more. Higher comes first. Products with a priority lead every list your AI shows, in priority order, and your AI presents that order as your shop's most popular products — so set it only on products you are happy to see presented that way. It decides order only: it never makes an irrelevant product relevant, and never decides what the AI may say about a product. Left out, the best version's priority is used.
popularity
number
A number, 0 or more — units sold in the last 30 days, for example. Higher comes first. It orders the products that have no priority, after the ones that have one. Only the order counts; the number itself is never shown to the AI or a visitor. Left out, the versions' popularity is added up.
rating
number
The average star rating on a 0–5 scale, such as 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.
review_count
number
How many reviews the rating is based on — a whole number, 0 or more. The highest-rated ranking lists only products with at least 5 reviews.
added_at
string
The day the product was first listed in your shop, 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.
attributes
object
Your own fields. See below.
search_terms
string[]
Extra words that should find this product — nicknames, an old name, a common misspelling. At most 100 words per product, its versions included. Your AI also reads them as the product's other names ("Also known as"), so it recognizes a visitor's nickname or old name for the product. Claims and instructions never match on them. Only add words that are not already in the title, description or attributes.
rule_keys
string[]
Keys this product carries — they connect it to your claims and instructions. Up to 500, each up to 200 characters.
rules
string[]
Sentences the AI receives as this product's own instructions. Up to 100, each up to 5,000 characters.
variants
object[]
The versions of this product — flavors, sizes, colors. At most 500. See the next section.

The version object

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

id
string or number required
The version's own stable identifier — usually your real SKU. It must be unique within the product; a repeat makes the whole product invalid.
options
object
What distinguishes this version, as 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.
price / sale_price / availability
string or number
This version's own price, sale price and stock status. Same rules as on the product.
link
string
A link straight to this version, if you have one. Falls back to the product's link.
image
string
This version's own image, if it differs.
attributes
object
Fields that belong to this version only — its own nutrition table, for instance.
priority
number
Order within the product. Higher comes first.
popularity / rating / review_count / added_at
number or string
This version's own figures, with the same rules as on the product. A version's 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.
search_terms / rule_keys / rules
string[]
Exactly as on the product, but for this version. A version's keys count as the product's keys, so a claim or instruction keyed on something only one flavor contains still reaches the product — and your AI is told it holds only for the versions carrying that key, and names them. A version's own rules are instructions for that version only.
If you send 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.
A product with no 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.
There are no alternative field names.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" }
}
String values are split on commas and semicolons."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.

There is no length cap on attributes. Everything you send is kept and indexed.

rule_keys and rules

Both are stored but never made searchable. They exist only for claims and instructions.

  • rule_keys give 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.
  • rules are 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.
Because they are not searchable, sending an ingredient list only in 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:

  • rating with review_count answers "which one is rated highest?" — always said together with the rating and the number of reviews.
  • added_at answers "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.

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

One workspace key grants push access to every Product API source in the workspace; the source id in the URL is what selects the target. Rotating the key breaks every shop integration in the workspace at once.

The body

FieldDefaultMeaning
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);

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"
}
A 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.

Only the latest run is kept per source. Your next push — or a scheduled read that happens in between — overwrites it, and the old 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

  • 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.
A pushed product replaces all of its versions. There is no way to add or remove a single version on its own: send the product with the complete 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:

FieldMeaning
skipped_for_creditProducts left out because credit is at the 500-credit line.
skipped_for_roomProducts left out because there was no room for them, as on some older free workspaces.
learning_pausedtrue 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

CodeWhen
400Malformed JSON, a bad mode, more than 20,000 items, or an empty merge
401Missing or invalid Y-API-Key
403Your workspace lacks the Content sources permission
404Unknown source, a source in another workspace, or a Product feed or shop source
409Another read or push is running for this source — wait and retry
411No Content-Length — chunked uploads are not accepted
413Body larger than 25 MB
413The 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
429Too many requests. Retry-After tells you how long to wait
429Too 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.

A workspace that nobody pays for (no subscription, no credit balance, and the free 14 days over) gets smaller limits: 5 MB per body, 1,000 items per push, and 6 pushes a minute rather than 60. An over-size body is refused with 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

© 2026 Yaplet. All rights reserved.