Get Headless Recommendations using Query

curl --request POST \
  --url https://storefront.glood.ai/api/storefront/v3/headless/recommendations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-shop: <x-shop>' \
  --data '
{
  "client_id": "client-abc",
  "user_id": "user-xyz",
  "queries": [
    {
      "id": "rec-1",
      "recommendation_type": "similar_products",
      "product_ids": [
        123,
        456
      ],
      "view": "product_ids",
      "max_recommendations": 10
    }
  ]
}
'

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_details",
      "recommendations": [
        {
          "product_id": 9311227838783,
          "title": "Classic Cotton T-Shirt",
          "handle": "classic-cotton-t-shirt",
          "price": 1025,
          "compare_at_price": null,
          "image": {
            "id": "gid://shopify/ProductImage/123456",
            "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg",
            "altText": "Classic Cotton T-Shirt",
            "width": 1600,
            "height": 1600
          },
          "tags": "cotton,casual,bestseller",
          "options": [
            {
              "id": 123,
              "name": "Title",
              "position": 1,
              "values": ["Default Title"]
            }
          ],
          "variants": [
            {
              "variant_id": 48328566276415,
              "title": "Default Title",
              "display_name": "Classic Cotton T-Shirt - Default Title",
              "price": "1025.00",
              "compare_at_price": null,
              "sku": "",
              "position": 1,
              "is_in_stock": true,
              "available_for_sale": true,
              "sellable_online_quantity": 50,
              "selected_options": [
                {
                  "name": "Title",
                  "value": "Default Title"
                }
              ]
            }
          ],
          "metafields": []
        }
      ]
    }
  }
}

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_ids",
      "recommendations": [
        { "product_id": 9311227838783 },
        { "product_id": 9311227838784 }
      ]
    }
  }
}

{
  "errors": [
    {
      "message": "\"product_ids\" is required",
      "path": ["queries", 0, "product_ids"],
      "type": "any.required",
      "context": {
        "label": "queries[0].product_ids",
        "key": "product_ids"
      }
    }
  ]
}

POST

api

storefront

headless

recommendations

curl --request POST \
  --url https://storefront.glood.ai/api/storefront/v3/headless/recommendations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-shop: <x-shop>' \
  --data '
{
  "client_id": "client-abc",
  "user_id": "user-xyz",
  "queries": [
    {
      "id": "rec-1",
      "recommendation_type": "similar_products",
      "product_ids": [
        123,
        456
      ],
      "view": "product_ids",
      "max_recommendations": 10
    }
  ]
}
'

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_details",
      "recommendations": [
        {
          "product_id": 9311227838783,
          "title": "Classic Cotton T-Shirt",
          "handle": "classic-cotton-t-shirt",
          "price": 1025,
          "compare_at_price": null,
          "image": {
            "id": "gid://shopify/ProductImage/123456",
            "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg",
            "altText": "Classic Cotton T-Shirt",
            "width": 1600,
            "height": 1600
          },
          "tags": "cotton,casual,bestseller",
          "options": [
            {
              "id": 123,
              "name": "Title",
              "position": 1,
              "values": ["Default Title"]
            }
          ],
          "variants": [
            {
              "variant_id": 48328566276415,
              "title": "Default Title",
              "display_name": "Classic Cotton T-Shirt - Default Title",
              "price": "1025.00",
              "compare_at_price": null,
              "sku": "",
              "position": 1,
              "is_in_stock": true,
              "available_for_sale": true,
              "sellable_online_quantity": 50,
              "selected_options": [
                {
                  "name": "Title",
                  "value": "Default Title"
                }
              ]
            }
          ],
          "metafields": []
        }
      ]
    }
  }
}

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_ids",
      "recommendations": [
        { "product_id": 9311227838783 },
        { "product_id": 9311227838784 }
      ]
    }
  }
}

{
  "errors": [
    {
      "message": "\"product_ids\" is required",
      "path": ["queries", 0, "product_ids"],
      "type": "any.required",
      "context": {
        "label": "queries[0].product_ids",
        "key": "product_ids"
      }
    }
  ]
}

Identifying the shopper

Every identity field is optional. Send whichever ones your storefront has, and Glood resolves them to a single visitor profile:

Field	Use when
`client_id`	You have the Shopify `_shopify_y` device cookie.
`user_id`	You have the Glood-generated user id (returned by Headless Init).
`customer_id`	The shopper is logged in and you have their Shopify customer ID.
`email`	You have no `customer_id` — resolves to the same profile.
`phone`	Same as `email`, for storefronts that identify shoppers by phone.

email and phone exist for storefronts that never see a Shopify customer_id. They identify the same shopper profile a customer_id would, so recommendations are personalized identically either way.

Send every identifier you have, not just one. A shopper often has both an anonymous browsing profile (under client_id) and an identified one (under customer_id or email). Passing both lets Glood pick whichever holds the richer browsing history.

Matching ignores formatting, so you do not need to normalize before sending:

email — case and surrounding whitespace are ignored (" Shopper@Example.com " matches shopper@example.com)
phone — punctuation and spacing are ignored (+1 (555) 010-9999 matches +15550109999)

Sending no identifier at all is valid. You get the same recommendations, just without personalization — no error. An unrecognized email or phone behaves the same way.

How personalization works

When a request identifies a shopper with browsing history, results are ranked using that history in addition to the products in product_ids:

similar_products — stays anchored to the products you asked about; browsing history refines the ordering rather than replacing it.
bought_together — the same blend, applied to co-purchase candidates.

Only browsing history is used. Purchase and cart history do not affect ranking. To override the automatic behaviour, set ranking_criteria on an individual query — for example bestsellers or new_arrivals. Leaving it unset is recommended.

Personalization improves as browsing data accumulates. A shopper Glood has not seen before receives standard relevance-ranked recommendations.

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_details",
      "recommendations": [
        {
          "product_id": 9311227838783,
          "title": "Classic Cotton T-Shirt",
          "handle": "classic-cotton-t-shirt",
          "price": 1025,
          "compare_at_price": null,
          "image": {
            "id": "gid://shopify/ProductImage/123456",
            "url": "https://cdn.shopify.com/s/files/1/example/products/t-shirt.jpg",
            "altText": "Classic Cotton T-Shirt",
            "width": 1600,
            "height": 1600
          },
          "tags": "cotton,casual,bestseller",
          "options": [
            {
              "id": 123,
              "name": "Title",
              "position": 1,
              "values": ["Default Title"]
            }
          ],
          "variants": [
            {
              "variant_id": 48328566276415,
              "title": "Default Title",
              "display_name": "Classic Cotton T-Shirt - Default Title",
              "price": "1025.00",
              "compare_at_price": null,
              "sku": "",
              "position": 1,
              "is_in_stock": true,
              "available_for_sale": true,
              "sellable_online_quantity": 50,
              "selected_options": [
                {
                  "name": "Title",
                  "value": "Default Title"
                }
              ]
            }
          ],
          "metafields": []
        }
      ]
    }
  }
}

{
  "status": "ok",
  "serve_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "data": {
    "rec-1": {
      "recommendation_serve_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "recommendation_type": "similar_products",
      "max_recommendations": 10,
      "creation_type": "automatic",
      "product_ids": [123, 456],
      "view": "product_ids",
      "recommendations": [
        { "product_id": 9311227838783 },
        { "product_id": 9311227838784 }
      ]
    }
  }
}

{
  "errors": [
    {
      "message": "\"product_ids\" is required",
      "path": ["queries", 0, "product_ids"],
      "type": "any.required",
      "context": {
        "label": "queries[0].product_ids",
        "key": "product_ids"
      }
    }
  ]
}

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"

Body

application/json

Request body

queries

object[]

required

Show child attributes

client_id

string

Client identifier (Shopify _shopify_y device cookie). Optional.

user_id

string

User identifier generated by Glood. Optional.

customer_id

string

Shopify customer ID for a logged-in shopper. Optional.

string

Shopper email address. Use this when your storefront has no access to a Shopify customer_id — it resolves to the same visitor profile. Case and surrounding whitespace are ignored. Optional.

Example:

"shopper@example.com"

phone

string

Shopper phone number. Alternative to customer_id, with the same behaviour as email. Formatting is ignored, so +1 (555) 010-9999 and +15550109999 are equivalent. Optional.

Example:

"+15550109999"

publicationIds

(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:

["30085840999"]

Response

Recommendations response

status

enum<string>

required

Response status

Available options:

ok

serve_id

string<uuid>

required

Unique identifier for this recommendation serve request

data

object

required

Recommendation results keyed by query ID

Show child attributes

API Reference

Product Recommendations

Search

Identifying the shopper

How personalization works

Authorizations

Headers

Body

Response

​Identifying the shopper

​How personalization works

Authorizations

Headers

Body

Response

Identifying the shopper

How personalization works