Items

Return the commerce items table.

curl -X GET "https://api.beacon.hard.al/v1/reports/commerce/items?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&reportingCurrency=example_string&groupBy=item_name&columns=%5B%22item_name%22%5D&filterField=item_name&filterValue=example_string&limit=example_string&offset=example_string&sortBy=item_name&sortDirection=asc" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests
import json

url = "https://api.beacon.hard.al/v1/reports/commerce/items?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&reportingCurrency=example_string&groupBy=item_name&columns=%5B%22item_name%22%5D&filterField=item_name&filterValue=example_string&limit=example_string&offset=example_string&sortBy=item_name&sortDirection=asc"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch("https://api.beacon.hard.al/v1/reports/commerce/items?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&reportingCurrency=example_string&groupBy=item_name&columns=%5B%22item_name%22%5D&filterField=item_name&filterValue=example_string&limit=example_string&offset=example_string&sortBy=item_name&sortDirection=asc", {
  method: "GET",
  headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_API_TOKEN"
}
});

const data = await response.json();
console.log(data);

package main

import (
    "fmt"
    "net/http"
)

func main() {

    req, err := http.NewRequest("GET", "https://api.beacon.hard.al/v1/reports/commerce/items?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&reportingCurrency=example_string&groupBy=item_name&columns=%5B%22item_name%22%5D&filterField=item_name&filterValue=example_string&limit=example_string&offset=example_string&sortBy=item_name&sortDirection=asc", nil)
    if err != nil {
        panic(err)
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}

require 'net/http'
require 'json'

uri = URI('https://api.beacon.hard.al/v1/reports/commerce/items?tenantId=123e4567-e89b-12d3-a456-426614174000&sourceId=123e4567-e89b-12d3-a456-426614174000&timeframe=today&startDate=example_string&endDate=example_string&timezone=example_string&interval=minute&reportingCurrency=example_string&groupBy=item_name&columns=%5B%22item_name%22%5D&filterField=item_name&filterValue=example_string&limit=example_string&offset=example_string&sortBy=item_name&sortDirection=asc')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Get.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'

response = http.request(request)
puts response.body

{
  "success": true,
  "data": {
    "range": {
      "startDate": "2026-10-01",
      "endDate": "2026-10-07",
      "timezone": "Europe/Istanbul"
    },
    "previousRange": {
      "startDate": "2026-09-24",
      "endDate": "2026-09-30",
      "timezone": "Europe/Istanbul"
    },
    "currency": {
      "reportingCurrency": "USD",
      "status": "available",
      "excludedCount": 0
    },
    "rows": [
      {
        "item_id": "SKU-1001",
        "item_name": "Trail Running Shoes",
        "category": "Shoes",
        "orders": 60,
        "view_item_count": 2400,
        "add_to_cart_count": 300,
        "itemKey": "["SKU-1001","","","","Trail Running Shoes","Northwind","Shoes",37.5]",
        "sku": null,
        "brand": "Northwind",
        "price": 37.5,
        "quantity": 120,
        "coupon": null,
        "discount": 0,
        "items": 120,
        "revenue": 4500
      },
      {
        "item_id": "SKU-2040",
        "item_name": "Waterproof Jacket",
        "category": "Outerwear",
        "orders": 35,
        "view_item_count": 1500,
        "add_to_cart_count": 190,
        "itemKey": "["SKU-2040","","","","Waterproof Jacket","Northwind","Outerwear",37.5]",
        "sku": null,
        "brand": "Northwind",
        "price": 37.5,
        "quantity": 70,
        "coupon": null,
        "discount": 0,
        "items": 70,
        "revenue": 2625
      },
      {
        "item_id": "SKU-3110",
        "item_name": "Merino Socks",
        "category": "Accessories",
        "orders": 18,
        "view_item_count": 900,
        "add_to_cart_count": 95,
        "itemKey": "["SKU-3110","","","","Merino Socks","Northwind","Accessories",37.5]",
        "sku": null,
        "brand": "Northwind",
        "price": 37.5,
        "quantity": 36,
        "coupon": null,
        "discount": 0,
        "items": 36,
        "revenue": 1350
      }
    ],
    "pagination": {
      "limit": 50,
      "offset": 0,
      "total": 3
    },
    "columns": [
      "item_name",
      "item_id",
      "brand",
      "category",
      "price",
      "quantity",
      "coupon",
      "discount",
      "view_item_count",
      "add_to_cart_count",
      "orders",
      "items",
      "revenue"
    ],
    "groupBy": null,
    "sort": {
      "sortBy": "orders",
      "sortDirection": "desc"
    }
  },
  "meta": {
    "reportSettingsVersion": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-required",
    "message": "tenant-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "validation-error",
    "message": "Validation failed for 'timeframe': timeframe must be one of: today, yesterday, last7days, last30days, custom",
    "details": {
      "field": "timeframe",
      "message": "timeframe must be one of: today, yesterday, last7days, last30days, custom"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "bearer-required",
    "message": "bearer-required"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "invalid-credential",
    "message": "invalid-credential"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-revoked",
    "message": "credential-revoked"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "credential-expired",
    "message": "credential-expired"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-granted",
    "message": "tenant-not-granted",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "source-does-not-belong-to-tenant",
    "message": "source-does-not-belong-to-tenant"
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "insufficient-scope",
    "message": "insufficient-scope",
    "details": {
      "required": "reports:read"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "tenant-not-found",
    "message": "tenant-not-found",
    "details": {
      "tenantId": "2f1c7c3e-6c1a-4f1e-9b7a-2d8e4c1a9f10"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "source-not-found",
    "message": "source-not-found",
    "details": {
      "sourceId": "7b0e5a54-1d43-4c8e-8d2f-5a9c3e6b1f27"
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

{
  "success": false,
  "error": {
    "code": "rate-limited",
    "message": "rate-limited",
    "details": {
      "retryAfterSeconds": 30
    }
  },
  "timestamp": "2026-11-01T09:30:00.000Z",
  "path": "/v1/reports/commerce/items",
  "requestId": "req_01JD2V8Q9Z6R4XK7T3M5N8P2WA"
}

GET

/v1/reports/commerce/items

GET

Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token

Bearer Tokenstring

Required

OAuth access token (token exchange) or organization API key.

query

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

Format: uuid

query

sourceIdstring

UUID of one source of the tenant. Omit it to include every source of the tenant.

Format: uuid

query

timeframestring

Reporting period. The presets today, yesterday, last7days and last30days cover whole calendar days ending today in the request timezone; last7days is today and the six days before it. Use custom together with startDate and endDate. Defaults to today.

query

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

query

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

query

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

Min length: 1 • Max length: 100

query

intervalstring

Time bucket size: minute, hour, day, week or month.

query

reportingCurrencystring

ISO 4217 currency code, for example USD. Amounts are returned in the tenant's reporting currency.

query

groupBystring

Group items by one column: item_name, item_id, brand, category, price, quantity, coupon or discount. Grouped rows also carry itemCount. When columns is sent it must include this column. Defaults to one row per item.

query

columnsarray

Columns to return on each row. Repeat the parameter or separate names with commas. Defaults to all columns.

query

filterFieldstring

Column to filter by: item_name, item_id, brand, category or coupon. Requires filterValue.

query

filterValuestring

Text to look for in filterField. Case-insensitive and matches part of the value. Requires filterField.

Min length: 1 • Max length: 255

query

limitstring

Maximum number of rows to return, 1 to 500. Defaults to 50.

Min: 1 • Max: 500

query

offsetstring

Number of rows to skip, 0 to 10000. Defaults to 0.

Min: 0 • Max: 10000

query

sortBystring

Column to sort by. Defaults to orders.

query

sortDirectionstring

asc or desc. Defaults to desc.

Request Preview

Response

Response will appear here after sending the request

Authentication

header

Authorizationstring

Required

Bearer token. OAuth access token (token exchange) or organization API key.

Query Parameters

tenantIdstring

Required

UUID of the tenant to report on. Send it exactly once. GET /v1/workspace/access lists the tenants this credential can read.

sourceIdstring

UUID of one source of the tenant. Omit it to include every source of the tenant.

timeframestring

startDatestring

First day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom, together with endDate.

endDatestring

Last day of a custom period, YYYY-MM-DD, inclusive. Send it only with timeframe=custom; it must not be before startDate.

timezonestring

IANA time zone name such as Europe/Istanbul or America/New_York. It sets the calendar-day boundaries of the period and of the time buckets. Defaults to Europe/Istanbul.

intervalstring

Time bucket size: minute, hour, day, week or month.

reportingCurrencystring

ISO 4217 currency code, for example USD. Amounts are returned in the tenant's reporting currency.

groupBystring