Skip to main content
POST

​
Overview

Send who the customer is, and Glood looks up their history server-side and returns four blocks: No product_ids are needed: each block is anchored on the customer’s own two most recent products for that signal. This makes the endpoint a fit for marketing emails, CRM and CDP syncs, account pages, and any surface that knows the customer but not the product they are looking at. For recommendations around specific products, use Query recommendations. Every block always comes back filled. When a customer has too little data for a block, Glood tops it up with trending products, and the block’s checkpoint tells you how much of it is personalized. You can ask for only some of the blocks, or for the checkpoints alone to decide what to show before fetching products.

​
Identifying the customer

Send at least one of these. A request with none of them is rejected with 400.
Send customer_id whenever you have it. A customer usually browses on several devices, and customer_id reaches all of them. email alone reaches only the devices where an email was captured, plus the customer’s orders.
Send one customer’s identifiers per request. Identifiers are combined with OR, so an email for one customer and a phone for another would merge both customers’ histories.
Anonymous client_id / user_id are not accepted here (400). For anonymous shoppers, use Query recommendations. An identifier that matches nobody is not an error: you get 200 with customer.identified: false and three blocks filled from trending.

​
What each signal contains

Each signal keeps at most 10 products. Products that no longer exist in the catalogue are skipped when choosing a block’s anchors.

​
Sending the live cart

If your storefront knows the current cart, send it as cart_product_ids: up to 10 product IDs, as an array or a comma-separated string. It replaces Glood’s add-to-cart history, which cannot see removals. Send [] for an empty cart. Leave the field out only when you don’t know the cart.
  • Products the customer has bought.
  • Products in the customer’s cart.
  • Products and tags the merchant excluded in Glood settings.
  • A block’s own anchor products.
  • The same product twice in one response. Blocks claim products in order: cart, then browsing_history, then purchase_history, then trending. The trending block shows the shop’s top trending products before any of them are used to top up other blocks.

​
Choosing blocks

Send blocks to get only some of the blocks, for example ["cart", "trending"]. Valid names are cart, browsing_history, purchase_history and trending. Leave it out to get all four.
  • The response contains only the blocks you asked for, always in the order above, whatever order you send them in.
  • A block you did not ask for is not computed and claims no products. So a block can contain a product that, in a full response, an earlier block would have taken.
  • Without trending, short blocks are topped up from the very top of the trending list.
  • customer.signals always reports all three signals.

​
Checkpoints only

Add ?checkpoints_only=true to the URL to get every block’s checkpoint, and customer, without the products. Each block then has recommendation_serve_id, recommendation_type and checkpoint only. Use it to decide which blocks to show, or whether a customer has enough data for a personalized campaign, before you fetch any products. The checkpoints are the same as in a full response for the same request: Glood still builds the blocks to count their products. The response is smaller, but the request costs the same. It combines with blocks.

​
Context

context is an optional list of free-form labels for where the recommendations will be shown, for example ["email", "win_back"]: up to 20 strings of up to 200 characters each. It does not change which products are returned.

​
Checkpoints

Every block carries a checkpoint: customer.signals reports how much history was found for each signal (count, capped at 10), and customer.signals.cart.source says whether the cart came from your request (request) or from Glood’s tracking (pixel).
You can render every block as-is. Use the checkpoint to label it (for example “Picked for you” only when status is personalized), to show only the first personalized_count products, or to measure how often customers have enough data.

​
Sales channels

Send publication_ids to return only products published on those sales channels, as on the other headless recommendation endpoints. See Filter by Sales Channel.

​
Errors

​
Examples

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-shop
string
required

Shopify store URL

Example:

"shop.myshopify.com"

Query Parameters

​
checkpoints_only
boolean
default:false

true returns every block's checkpoint (and customer) without the products: each block has no recommendations. The checkpoints equal those of a full response for the same request; Glood still builds the blocks to count them.

Body

application/json

Request body

At least one of customer_id, email or phone is required. Unknown fields (including client_id and user_id) are rejected with 400.

​
customer_id

Shopify customer ID, numeric or GID, as a string or a number. Reaches every device the customer used, so send it whenever you have it.

Example:

"9155793715519"

​
email
string

Customer email. Case and surrounding whitespace are ignored. Also matched against the Shopify customer record and against orders, so guest checkouts are found.

Example:

"shopper@example.com"

​
phone
string

Customer phone. Formatting is ignored, so +1 (555) 010-9999 and +15550109999 are equivalent. Also matched against orders.

Example:

"+15550109999"

​
cart_product_ids

The customer's live cart: up to 10 product IDs, as a JSON array of integers or a comma-separated string. When present it replaces Glood's add-to-cart history, and [] means an empty cart. Omit it only when you don't know the cart.

Maximum array length: 10
Example:
​
max_recommendations
integer
default:10

Products per block.

Required range: 1 <= x <= 50
​
view
enum<string>
default:product_details

Format of each block's recommendations.

Available options:
product_details,
product_ids
​
blocks
enum<string>[]

Optional. The blocks to return. The response contains only these, always in the order cart, browsing_history, purchase_history, trending. A block not asked for is not computed and claims no products in the cross-block dedupe; without trending, short blocks are topped up from the very top of the trending list.

Required array length: 1 - 4 elements
Available options:
cart,
browsing_history,
purchase_history,
trending
Example:
​
context
string[]

Optional. Free-form labels for where the recommendations will be shown. Does not change which products are returned.

Maximum array length: 20
Required string length: 1 - 200
Example:
​
publication_ids
(string | integer)[]

Optional. Numeric Shopify publication (sales channel) ids. When present, only products published on at least one of these channels are returned and the default "published to the Online Store" gate is replaced by this filter; market and B2B filters still apply. A single id may be sent without the array wrapper. Each id must be one the merchant enabled under Settings → Sales channels; unknown ids return 400. The id is the numeric tail of gid://shopify/Publication/.

Maximum array length: 50
Pattern: ^[0-9]+$
Example:

Response

The requested blocks (all four by default), each with a checkpoint

​
status
enum<string>
required
Available options:
ok
​
serve_id
string<uuid>
required

Unique identifier for this request

​
customer
object
required

What Glood found about the customer. Email and phone are never echoed.

​
blocks
object
required

Only the blocks asked for in blocks (all four by default), in this order.