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, an email template or any surface where you control the presentation and just want the picks. You fetch them with one GET request.

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

The steps

Seven steps: Catalog, Interactions, Recommendation, Data in Response, Code, Automation and Performance. There is no Target step: the picks are for whoever your request names.

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. The catalog lives in Settings → Recommendation setup → Product Catalog. See Setting the Product / Content Feed.

2. Interactions

The engine learns from what people do with products: viewed, added to cart, purchased. Views, add-to-carts and purchases on your own website are tracked as usual, from Settings → Recommendation setup → Product Tracking. Your own layout is different: Personyze did not draw it, so it cannot see what happens there.

Clicks: send people through the click_url that comes back with every item. It opens the product and records the click.
Anything that happens off your website, such as a view or a purchase inside your app, has to be reported by you. Use the product interactions REST API.

This is the 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 the algorithm. The picker is the same one on-site widgets use, grouped into Personalized & Behavioral; Cross-Sells, Co-Views & Upsells; Visitor History; Catalog Events; and Custom. A request does not come from a page of your site, so the Page row offers what the person did instead:

General: no particular item.
Items they viewed: anchored to what they viewed.
Items in their cart: anchored to their cart.
Items they purchased: anchored to what they bought.

Many algorithms have settings of their own, shown on the card:

Period: Recently, Today, In last 2 days, In last 4 days, In last week or In all time. Shorter windows follow trends, while longer ones are more stable.
Taken from: which part of the catalog. For example, any category, the categories they viewed, their last cart category, or their reported interests.
Sort by: Viewed, Recently added to catalog, Purchased, Added to cart, Added to wishlist, Cheap, High rated or High profit.

The Output card sets how many items come back (up to 12), Fallback algorithms to run when the main one returns too few, and Fill empty cells to top up a short result with popular items. Below it, filters narrow the pool. You can skip items the person already engaged with, restrict to chosen categories or to items with an image or a price, or write custom rules on any catalog field. Out-of-stock items are excluded automatically.

For the algorithms themselves, see Recommendation Algorithms. See also Filters and Fallbacks.

4. Data in Response

Personyze answers with a JSON array of objects, one per product, carrying the fields you choose here. Each row pairs a Field on Personyze with its Name in JSON result, so you define your own response contract. Pick exactly what your renderer needs and nothing more.

Every product also comes back with a click_url, whether or not you list it. Send the user to that URL: it opens the product and records the click, and the view and click statistics are built from it.

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",
    "click_url": "https://pic.personyze.com/href/k=…"
  },
  ...
]

Any custom catalog field can be included. 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 Code step, titled Request URL, gives you ready-made URLs. They appear once the campaign is saved. Make a GET request to one and the recommendations come back as JSON. What you put at the end says who, or what, they are for:

URL ends in	Recommends for
`/email={INSERT EMAIL HERE}`	The person with that email address. An address Personyze has not seen creates a profile, so the first request enrols them.
`/internal_id={INSERT INTERNAL ID HERE}`	The person with your own ID for them, held on their profile as Internal ID. An unknown ID also creates a profile.
`/u={INSERT PERSONYZE USER ID HERE}`	Personyze’s own numeric user ID, the one the tracker exposes on your site. Anything but a number is refused with `Invalid parameter`.
`/item_internal_id={INSERT ITEM INTERNAL ID HERE}`	No person: products related to that product. These are items viewed or bought together with it, or the most popular in its category.

A fifth URL, ending in /get[]=…, recommends nothing. It returns your chosen fields for the products you name, up to 50 per request, and its period (1 Day, 2 Days, Week, All time) sets the window for any interaction counters you asked for.

The request is the same from a backend, an app or an email template. If your app already reports to Personyze through the mobile SDK, you can also deliver the picks there with a Product Recs for Apps campaign.

6. Automation

This step is optional. Add rules that alert you, or act, when this campaign’s numbers cross a line. See Automation.

7. Performance

The Performance step shows JSON API statistics. Viewed counts the recommendations served to your application. Clicked counts users who went through a returned click_url and landed on your site, as a % of Viewed. Added to cart and Purchased follow in the same session, each a % of the step before. Transactions, attributed revenue and their share of site revenue sit alongside. It only reflects what Personyze can see: without the click_url, clicks and everything after them go uncounted. Every figure is explained in Product and content recommendations.

Note: there is no QA step

Unlike on-site campaigns, JSON API campaigns have no QA step, because there is no rendered content for the panel to preview. Validate by requesting a URL yourself and reading the answer. Check that you get the number of items you expect, that the fields you selected are present, and that the values are populated rather than empty. A request that cannot be answered still returns JSON, as {"error": "…"}. For example, No recommendations for this user means the algorithm found nothing for that person and there was no fallback to fill in.

Recommendations Outside Your Site — Where to Start
JSON API — Content Recommendations
Products object and product interactions in the REST API.
Implementing a custom recommendations app, the SDK and REST route for apps, with a worked example.