Products & write-backs

A product is an item of the brand’s catalogue: what the AI assistants recommend — or not — and what Skoup compares their claims against (price, stock, specs). Products come from a source: shopify (synchronized from the store, updated in real time), feed (a CSV or Google Shopping feed), manual (created in Skoup or through the API, for a stack without a connector) or site (an offering Skoup read on the brand’s own site — a plan, a service — editable like a manual one). For a brand that sells software or runs an establishment (its vertical), the products are its offerings: plans, services, treatments, with the same fields.

A write-back is a change Skoup wrote in the store for a product: its description, its SEO title and description, or the barcode of its variants. It is journaled field by field, with the value it replaced, and can be rolled back from the app for 30 days.

Statuses

draftactivearchived

Product status, as in the store.

failedappliedrolled_back

Write-back status: a write-back is born failed and becomes applied once the store accepted it; rolled_back once the previous values are restored.

I want to…

I want to…	Call
Search the catalogue	`GET /v1/brands/{brand}/products?q=grizl`
List the manual products	`GET /v1/brands/{brand}/products?source=manual`
Read one product and its variants	`GET /v1/brands/{brand}/products/{product}`
Add a product (no connector)	`POST /v1/brands/{brand}/products`
Update a manual product	`PATCH /v1/brands/{brand}/products/{product}`
See what Skoup wrote in the store	`GET /v1/brands/{brand}/products/{product}/write_backs`
See how the AI perceive a product	`GET /v1/brands/{brand}/products/{product}/perception` (`metrics:read`)

Scopes: products:read, products:write. Events: product.created, product.updated, product.deleted, catalog.sync.completed, catalog.sync.failed, write_back.applied, write_back.rolled_back, sheet.validated.

Scenario: feed Skoup from a Magento catalogue

Without a connector, push your products as manual products and keep them in sync with PATCH:


curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/products \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Idempotency-Key: magento-sku-GRZ-CF-SL7" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","sku":"GRZ-CF-SL7","price":2499,"currency":"EUR","url":"https://nordvelo.fr/grizl-cf-sl-7","category":"Gravel"}'

Pricing of an offer

An offer sold as a subscription says what its price buys:

Field	Meaning
`price`	The price of one `price_period`.
`price_period`	`month`, `year` or `once`; `null` = a one-off price (a store’s product).
`price_annual`	The amount of one year, however the site writes it.
`price_unit`	`flat` or `per_user` (per user, practitioner, seat).
`addons`	The options sold on top: `name`, `price` (`null` = on quote), `period`, `unit`. 12 at most.

Skoup reads these fields on the site’s pricing page when it analyses the brand (source site); you correct them in the app or with PATCH. They are the truth a price quoted by an AI is compared with: see the Alerts guide.

Pitfalls

Synced products are read-only. PATCH on a shopify or feed product answers 422 resource_read_only: the store is the truth, fix it there — Skoup picks the change up.
Write-backs are not applied through the API. A person validates the diff in the app before anything reaches a storefront; the API only reads the journal.
A product removed at the source emits product.deleted; it comes back with product.created if it reappears.
price_annual is always a yearly amount. A site showing “€32/month billed yearly” is price_annual: 384. Skoup then accepts both “€32/month” and “€384/year” in an AI answer.
Add-ons widen the high bound, never the price. An add-on on quote (price: null) leaves the pricing open-ended: only an answer under the offer’s price is wrong.
Test mode: creations are rolled back; read the sandbox’s Nordvelo catalogue instead.