FBT

How to perform an FBT query and how it works

Also known as Frequently Bought Together, FBTs are a type of analysis query that, based on your entire order history, allows you to retrieve the items that most frequently have been added as line items in the same orders as a specified item (SKU or bundle) or array of items.
Request
To perform an FBT query send a POST request to the /analysis/fbt endpoint specifying the item ID(s) in the filter without any extra query keys:
{
  "filter": {
    "line_items": {
      "item_ids": {
        "in": [
          "...",
          "..."
​
          // ...
​
        ]
      }
    }
  },
  "meta": { ... }
}
Operator
Type
Description
Example
in
Array
A list of SKU or bundle IDs associated as line items to one or more orders.
"item_ids": { "in": [ "xYZkjABcde", "yzXKjYzaCx"] }
Please note that while the attribute value of the in operator used in the standard filters matches any (logic OR) of the specified array's values, the attribute value of the in operator used in the FBT filters matches all (logic AND) of the specified array's values.
The filter object is required (if missing the API will respond with a 400 Bad request error). You can optionally add the meta object for any useful information about the query itself (learn more here).
Response
The response of an FBT query returns an aggregation by item ID ordered by value (e.g. from the most frequently bought together item to the less frequently bought together item), with some additional information:
{
  "data": [
    {
      "item_id": "...",
      "value": ...,
      "type": "...",
      "name": "..."
    },
    { ... }
  ],
  "meta": { ... }
}
Key
Type
Description
item_id
String
The ID of the item associated with the line item.
value
Integer
The number of orders containing both the item identified by the item_id and the item(s) identified by the ID(s) specified in the request body.
type
String
The type of the item identified by the item_id (one of sku or bundle).
name
String
The name of the line item (as in the first created order among the ones counted in the value). When missing, it gets populated with the name of the associated item (if present).
The FBT query returns a maximum of 10 records (i.e. the 10 most frequently bought together items).
Example
Request
Response
The following request performs an FBT query to get the items most frequently bought together with the item identified by the ID "BmDzSVkXAW":
curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/metrics/analysis/fbt' \
  -H 'Accept: application/vnd.api.v1+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Authorization: Bearer {{your_access_token}}' \
  -d '{
    "filter": {
      "line_items": {
        "item_ids": {
          "in": [ "BmDzSVkXAW" ]
        }
      }
    }
  }'
On success, the API responds with a 200 OK status code, returning the aggregated values in the data object and additional information in the meta object:
{
  "data": [
    {
      "item_id": "ZrxeSRgOmB",
      "value": 789,
      "type": "skus",
      "name": "Black T-Shirt, Men, Size M"
    },
    {
      "item_id": "nLgbSeMxpB",
      "value": 456,
      "type": "skus",
      "name": "White T-Shirt, Women, Size XS"
    },
    {
      "item_id": "nprzSARKeW",
      "value": 123,
      "type": "skus",
      "name": "Red Baseball Cap, Limited edition, One size"
    },
    { ... }
  ],
  "meta": {
    "type": "fbt",
    "trace_id": "fe571ea2-8a4f-4a5e-bd26-ac54651bb2e4",
    "mode": "test",
    "organization_id": "xYZkjABcde",
    "market_ids": [ "yzXKjYzaCx", "..." ]
  }
}

Operator	Type	Description	Example
`in`	Array	A list of SKU or bundle IDs associated as line items to one or more orders.	`"item_ids": { "in": [ "xYZkjABcde", "yzXKjYzaCx"] }`

Key	Type	Description
`item_id`	String	The ID of the item associated with the line item.
`value`	Integer	The number of orders containing both the item identified by the `item_id` and the item(s) identified by the ID(s) specified in the request body.
`type`	String	The type of the item identified by the `item_id` (one of `sku` or `bundle`).
`name`	String	The name of the line item (as in the first created order among the ones counted in the `value`). When missing, it gets populated with the name of the associated item (if present).

Getting started - Previous

Analysis

Next - Getting started

Errors

Last modified 7mo ago