Recommendations

Recommendation limits

GET read_products

Get recommendation limits and supported modes.

Use this response to build controls; do not hardcode limits or enum values.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"rail_min_limit":4,"rail_max_limit":24,"rail_default_limit":12,"history_window_options":[30,60,90],"rule_match_kinds":["same_category","same_brand","same_vendor","shares_tag","same_collection","same_attribute","store_wide"],"rule_sorts":["best_selling","newest","price_asc","price_desc"],"rules_max_per_store":5,"cross_device_modes":["off","logged_in_with_consent"],"exclusions_max_per_store":500,"list_default_limit":25,"list_max_limit":200,"page_size_options":[20,50,100,200],"pins_max_per_product":24}}

Get recommendation settings

GET read_products

Get store-wide recommendation settings.

These settings govern related-product and recently-viewed rails across storefronts.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/settings' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/settings", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/settings",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"settings":{"related_limit":8,"recently_viewed_enabled":true,"recently_viewed_limit":8,"history_window_days":30,"hide_out_of_stock":true,"exclude_free_products":true,"cross_device_history":"off"}}}

Update recommendation settings

PUT write_products

Replace store-wide recommendation settings.

Send the complete settings object returned by GET.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`related_limit` required	`integer`	Products in the related rail. Example: `8`
`recently_viewed_enabled` required	`boolean`	Whether Recently viewed is enabled. Example: `true`
`recently_viewed_limit` required	`integer`	Products in Recently viewed. Example: `8`
`history_window_days` required	`integer`	History window from limits. Example: `30`
`hide_out_of_stock` required	`boolean`	Exclude sold-out products automatically. Example: `true`
`exclude_free_products` required	`boolean`	Exclude zero-price products automatically. Example: `true`
`cross_device_history` required	`string`	Cross-device mode from limits. Example: `off`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/recommendations/settings' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "cross_device_history": "off",
  "exclude_free_products": true,
  "hide_out_of_stock": true,
  "history_window_days": 30,
  "recently_viewed_enabled": true,
  "recently_viewed_limit": 8,
  "related_limit": 8
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/settings", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "cross_device_history": "off",
    "exclude_free_products": true,
    "hide_out_of_stock": true,
    "history_window_days": 30,
    "recently_viewed_enabled": true,
    "recently_viewed_limit": 8,
    "related_limit": 8
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/recommendations/settings",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "cross_device_history": "off",
        "exclude_free_products": True,
        "hide_out_of_stock": True,
        "history_window_days": 30,
        "recently_viewed_enabled": True,
        "recently_viewed_limit": 8,
        "related_limit": 8,
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"settings":{"related_limit":8,"recently_viewed_enabled":true,"recently_viewed_limit":8,"history_window_days":30,"hide_out_of_stock":true,"exclude_free_products":true,"cross_device_history":"off"}}}

Get recommendation rules

GET read_products

Get the ordered automatic recommendation rule chain.

Rules run after pinned products and fill the rail in position order. An empty list uses the default category best-seller rule.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/rules' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/rules", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/rules",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"rules":[{"match_kind":"same_category","sort":"best_selling","position":0,"include_subcategories":true}]}}

Set recommendation rules

PUT write_products

Replace the ordered recommendation rule chain.

Send rules in display order. same_attribute requires an attribute id in match_value; include_subcategories applies only to same_category. Send an empty array to restore the default category best-seller rule.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`rules` required	`array<object>`	Complete ordered rule list. Example: `[{"match_kind":"same_category","sort":"best_selling","include_subcategories":true}]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/recommendations/rules' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "rules": [
    {
      "include_subcategories": true,
      "match_kind": "same_category",
      "sort": "best_selling"
    }
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/rules", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "rules": [
      {
        "include_subcategories": true,
        "match_kind": "same_category",
        "sort": "best_selling"
      }
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/recommendations/rules",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "rules": [{
            "include_subcategories": True,
            "match_kind": "same_category",
            "sort": "best_selling",
        }],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"rules":[{"match_kind":"same_category","sort":"best_selling","position":0,"include_subcategories":true}]}}

List curated products

GET read_products

List products that have pinned recommendation lists.

Compact product references are included so clients do not need one product request per row.

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Default: `1` Example: `1`
`limit`	`integer`	Page size bounded by the limits response. Example: `25`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/pins?limit=25&page=1' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/pins?limit=25&page=1", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/pins?limit=25&page=1",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"product_ids":[42],"products":[{"id":42,"title":"Matte Sticker","slug":"matte-sticker"}],"total":1}}

Get pinned recommendations

GET read_products

Get one product's ordered pinned recommendations.

The products array follows pin order and contains display identity.

Path parameters

Name	Type	Description
`productId` required	`integer`	Store-scoped product id. Example: `42`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/pins/42' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/pins/42", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/pins/42",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"product_id":42,"pins":[{"related_product_id":17,"position":0}],"products":[{"id":17,"title":"Sticker Sheet","slug":"sticker-sheet"}]}}

Set pinned recommendations

PUT write_products

Replace one product's ordered pinned recommendations.

A product cannot pin itself or repeat a related product.

Path parameters

Name	Type	Description
`productId` required	`integer`	Store-scoped product id. Example: `42`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`related_ids` required	`array<integer>`	Related product ids in display order. Example: `[17,23]`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/recommendations/pins/42' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "related_ids": [
    17,
    23
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/pins/42", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "related_ids": [
      17,
      23
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/recommendations/pins/42",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "related_ids": [17, 23],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"product_id":42,"pins":[{"related_product_id":17,"position":0}],"products":[{"id":17,"title":"Sticker Sheet","slug":"sticker-sheet"}]}}

List recommendation exclusions

GET read_products

List products excluded from all recommendations.

Compact product references are returned with the ID list.

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Default: `1` Example: `1`
`limit`	`integer`	Page size bounded by the limits response. Example: `25`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl 'https://api-store.tringify.com/api/2025-01/recommendations/exclusions?limit=25&page=1' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/exclusions?limit=25&page=1", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/recommendations/exclusions?limit=25&page=1",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"product_ids":[42],"products":[{"id":42,"title":"Matte Sticker","slug":"matte-sticker"}],"total":1}}

Exclude a product

POST write_products

Exclude a product from all recommendations.

Exclusions apply to pinned products as well as automatic and recently-viewed recommendations. They do not unpublish the product.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`product_id` required	`integer`	Product id. Example: `42`

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl -X POST 'https://api-store.tringify.com/api/2025-01/recommendations/exclusions' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": 42
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/exclusions", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "product_id": 42
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/recommendations/exclusions",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "product_id": 42,
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"excluded":true}}

Remove a recommendation exclusion

DELETE write_products

Allow a product to be recommended automatically again.

The operation is idempotent.

Path parameters

Name	Type	Description
`productId` required	`integer`	Store-scoped product id. Example: `42`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

401 UNAUTHORIZED
Authorization header missing, malformed, or token invalid/expired.
402 SUBSCRIPTION_REQUIRED
The store does not have an active or trialing subscription.
403 STORE_API_SCOPE_REQUIRED
Token is valid but lacks the required scope for this call.
429 RATE_LIMITED
The token's request allowance is exhausted. Retry after the Retry-After header.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/recommendations/exclusions/42' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/recommendations/exclusions/42", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/recommendations/exclusions/42",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"removed":true}}

Endpoints#

Headers

Errors

Headers

Errors

Headers

Body parameters

Errors

Headers

Errors

Headers

Body parameters

Errors

Query parameters

Headers

Errors

Path parameters

Headers

Errors

Path parameters

Headers

Body parameters

Errors

Query parameters

Headers

Errors

Headers

Body parameters

Errors

Path parameters

Headers

Errors