Enabled resource errors field for orders and carts —
Check the use case
LogoLogo
Metrics APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Metrics API
  • Getting started
    • API specification
    • Queries
      • Breakdown
      • Date breakdown
      • Stats
      • Search
    • Filters
    • Analysis
      • FBT
    • Errors
    • Use cases
      • Orders by currency
      • Orders by status and payment status
      • Orders by repeat customer
      • Orders by bundle
      • Orders by shipment status and shipping method name
      • Orders paid with gift cards
      • Orders associated with a specific promotion
      • Number of products per order by country
      • Best-selling products by market
      • Customers that bought a specific product
      • Shipments average time in picking
      • Top 10 spenders by currency
      • Orders by day
      • Returns per year by destination city
      • Refunds by country and currency
      • Latest carts with a specific product from a specific market
      • Orders by resource error code and message
      • Latest archived orders
      • Latest placed orders from customers with specific email domains
      • Frequently bought together products
  • API reference
    • Orders
    • Returns
    • Carts
On this page
  • Request
  • Response
  • Example
  1. Getting started
  2. Analysis

FBT

How to perform an FBT query and how it works

PreviousAnalysisNextErrors

Last updated 2 years ago

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 as a specified item ( or ) 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 without any extra query keys:

{
  "filter": {
    "line_items": {
      "item_ids": {
        "in": [
          "...",
          "..."

          // ...

        ]
      }
    }
  },
  "meta": { ... }
}
Operator
Type
Description
Example

in

Array

"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.

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

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

A list of SKU or bundle IDs associated as to one or more .

The filter object is required (if missing the API will respond with a 400 Bad request ). You can optionally add the meta object for any useful information about the query itself (learn more ).

line items
orders
orders
filter
error
here
SKU
bundle