Custom Algorithms

Custom is the serve endpoint for custom algorithms (Bring Your Own Recommendations (BYOR)). It lets you serve product lists computed outside Insider One, an in-house ML model, a third-party engine, or a hand-curated business list, through the same delivery pipeline as native algorithms: in-stock control, attribute filters, category filters, user-based exclusions, affinity re-ranking (hp), variant handling, and fallbacks all still apply on top of your-supplied list.

A custom algorithm is addressed by an ID of the form cus-{subType}-{algoId} (e.g. cus-p-8842). The sub-type decides the serve contract:

locale is part of the partition key for every sub-type, not just Generic; it's the same catalog locale required as a query parameter below. Only the row key inside that partition differs: userId for cus-p-, the base productId for cus-c-, and one row per scored product for cus-g-.

Working principles

• Identity. The request must carry either algorithm (a full cus- id; the request itself is the whole configuration; strategyId, when also present, is recorded for attribution only) or strategyId (a stored strategy whose algorithm is custom, resolved with full /v2/strategy semantics; stored endpoint_template values merge under request values). A native (non-cus-) value on either path is rejected with a 400.

• Gate validation. Partner, authentication, rate-limit, and requesting origin validation checks run before any strategy resolution.

• Store lookup. Candidate ids are read from the custom-scores store, partitioned by {partnerName}:{customAlgorithmId}:{locale}. Personalized and contextual serves are point reads keyed by userId / productId; a generic serve drains the whole partition and orders by score (descending, stable).

• Enrichment and ranking. Candidates (over-fetched at 4× the requested size so filter drops don't under-fill) are enriched from the product catalog: out-of-stock and filtered-out items drop, the stored order is preserved, the hp affinity re-rank applies when requested, and the list is cut to size.

• Response. Custom-served products are keyed in the types map by the full custom id (e.g. "cus-p-8842": 12); fallback-filled products keep their native type codes.

Generic (cus-g-) results are served through a shared query cache with a fixed ~10-minute TTL, so newly ingested generic scores can take up to ~10 minutes to appear. Personalized and contextual serves are never written to the shared cache.

Custom ids also participate in the wider V2 surface: a stored custom strategy called via /v2/strategy transparently serves through this same path, cus- entries are admitted inside Chef and /v2/mixed strategy lists, and a cus- id can itself be used as a fallback candidate for another strategy.

Endpoint

GET https://recommendation.api.useinsider.com/v2/custom

Fallbacks

• Due to possibilities such as:

  • No custom personalized algorithm results row for the user in the SR API request /

  • No custom contextual algorithm results for the product in the SR API

  • Filtering applied in the SR API endpoint causing custom recommendations to be filtered out,

    In such cases, Insider One returns an empty response for the custom part of the request, not an error. Then, if fallbacks are enabled, it hands over to the standard fallback flow exactly like a native algorithm that returned nothing.

• Fallbacks are filled from your prebuilt (static) chain, or from a dynamic chain requested with fallbacks (CSV of up to 4 fallback strategy ids, or none to disable filling). Consumption mode is set with fbType (agg default, first alternative).

• When the store has no data and no fallback is selected, the response is a well-formed empty success (success: true, empty data), by design, not an error.

• Fallback products appear in types under their own native codes; per-source attribution is available with fbDetails=true (fallbackInfo block).

Query Parameters

Examples

Generic — cus-g-

One shared list per partner + algorithm + locale. No user or product context is needed.

Request

https://recommendation.api.useinsider.com/v2/custom?partnerName=demoshop&locale=en_US&algorithm=cus-g-1024

Response

{
    "success": true,
    "total": 8,
    "types": {
        "cus-g-1024": 8
    },
    "data": [
        "SKU-77120",
        "SKU-88431",
        "SKU-10294",
        "SKU-55710",
        "SKU-31448",
        "SKU-90021",
        "SKU-66317",
        "SKU-24805"
    ]
}

Personalized — cus-p- (requires userId)

The list stored for this specific user is served; without userId, the request is rejected with 400 (Missing parameter: userId).

Request

https://recommendation.api.useinsider.com/v2/custom?partnerName=demoshop&locale=en_US&algorithm=cus-p-8842&userId=usr-5f2a91c3

Response

{
    "success": true,
    "total": 6,
    "types": {
        "cus-p-8842": 6
    },
    "data": [
        "SKU-40233",
        "SKU-11876",
        "SKU-93012",
        "SKU-77120",
        "SKU-58649",
        "SKU-30215"
    ]
}

Contextual — cus-c- (requires productId)

The list stored for the base product is served; without productId, the request is rejected with 400 (Missing parameter: productId).

Request

https://recommendation.api.useinsider.com/v2/custom?partnerName=demoshop&locale=en_US&algorithm=cus-c-4519&productId=SKU-30215

Response

{
    "success": true,
    "total": 5,
    "types": {
        "cus-c-4519": 5
    },
    "data": [
        "SKU-30990",
        "SKU-30218",
        "SKU-41102",
        "SKU-77120",
        "SKU-15530"
    ]
}

With details and fallback attribution

When the custom list cannot fill the requested size, fallbacks top it up — fallback products keep their native type codes in types, and fbDetails=true names each contributing source.

Request

https://recommendation.api.useinsider.com/v2/custom?partnerName=demoshop&locale=en_US&algorithm=cus-p-8842&userId=usr-5f2a91c3&size=3&details=true&fbDetails=true

Response

{
    "success": true,
    "total": 3,
    "types": {
        "cus-p-8842": 2,
        "mvop": 1
    },
    "data": [
        {
            "item_id": "SKU-40233",
            "name": "Cap",
            "in_stock": 1,
            "price": { "USD": 16 },
            "locale": "en_US"
        },
        {
            "item_id": "SKU-11876",
            "name": "Belt",
            "in_stock": 1,
            "price": { "USD": 55 },
            "locale": "en_US"
        },
        {
            "item_id": "SKU-90021",
            "name": "Scarf",
            "in_stock": 1,
            "price": { "USD": 24 },
            "locale": "en_US"
        }
    ],
    "fallbackInfo": [
        { "source": "cus-p-8842", "count": 2 },
        { "source": "mvop", "count": 1 }
    ]
}

Common 400 responses