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

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" ]
        }
      }
    }
  }'

Response

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", "..." ]
  }
}