JSON API — Product Recommendations

Product recommendations delivered as raw JSON instead of a rendered widget, so you can lay them out yourself. Use it for a custom-designed widget, a single-page app, a native app, or any surface where you control the presentation layer and just want the picks.

In the panel: New campaign › App / API › JSON API — Product Recs.

The steps

Six steps: Catalog, Interactions, Recommendation, Data in Response, Code and Performance.

1. Catalog

Your catalog has to be in place and current — nothing can be recommended that Personyze does not know about. Each item needs at least an internal ID, a title and a URL, plus an image if your layout shows one.

2. Interactions

The engine learns from what people do with items: viewed, added to cart, purchased, read, liked. On a normal website Personyze can often detect much of this automatically. If you are consuming JSON, you are usually rendering the results yourself — which means you must also report interactions yourself, or the engine never learns from anything your custom layout shows.

This is the single most common reason a JSON recommendation returns weak or generic results: the output is being rendered, but nothing is being reported back.

3. Recommendation

Choose what should be recommended, and in what context — a home page, a category page, a product page, a cart or post-purchase page each imply a different algorithm.

Whichever algorithm you pick, you can narrow it with the same set of modifiers:

Time window — today, recently, in the last 2 / 4 days, in the last week, or all time. Shorter windows follow trends; longer ones are more stable.
Category scope — from all categories, only from the last viewed category, or from the current product’s category.
Interest scope — from the visitor’s inferred interests, or from the interests associated with the last product they looked at.
Ordering and freshness — recent first, oldest first, cheapest, or recently added to the catalog.
Co-occurrence — bought together, or viewed together within the current category.

Filters restrict the pool further: in stock only, a price range, a particular brand or category, or any custom catalog field.

For a fuller treatment of the algorithms themselves, see Recommendation algorithm types.

4. Data in Response

Personyze generates a JSON array of objects, where each object contains the fields you select here. You are choosing the shape of your own API response, so pick exactly what your renderer needs and nothing more.

Typical selection for a product widget:

[
  {
    "internal_id": "nw-p001",
    "title": "Alpine Shell",
    "price": 249,
    "image_1": "https://example.test/img/alpine-shell.jpg",
    "url": "https://example.test/shop/alpine-shell"
  },
  ...
]

Any custom catalog field can be included, so if your layout shows a badge, a rating or a stock message, map that field here rather than looking it up separately.

5. Code

The wizard gives you the snippet to embed. Two ways to consume the result:

On a page — the snippet assigns the JSON to a JavaScript variable you name, and your own script renders it. This is the usual choice for a custom widget or an SPA.
Server-side or from an app — call /rest/tracker-v1 and read the matching action out of the response. The JSON arrives in the action’s data field. This is the path native apps and non-web platforms use; it is documented end to end, with a worked example, in Implementing a custom recommendations app.

6. Performance

Results once it is live. Note this only reflects what Personyze can see — if you render the JSON yourself and do not report interactions, the performance figures will understate what the recommendation actually did.

Note: there is no QA step

Unlike on-site campaigns, JSON API campaigns have no QA step — there is no rendered content for the panel to preview. Validate by requesting the JSON yourself and inspecting it: confirm you get the number of items you expect, that the fields you selected are present, and that the values are populated rather than empty.

JSON API — Content Recommendations
Implementing a custom recommendations app — the full API path, with a worked example.
Products object and product interactions in the REST API.