API Controller: `api/v1/traffic`

Generated from OpenclawSellercentralApiRegistry. Run bin/rails sellercentral_api_docs:sync after API updates.

Endpoints

`GET /api/v1/traffic`

Returns seller traffic in business-summary mode or ASIN-detail mode when the asin parameter is provided.

Query Options

asin (optional): Switches response mode to ASIN detail for the provided ASIN.
asins (optional): Comma, space, or newline-separated ASIN list used to constrain and order business-summary rows.
top_items_count (optional): Business-summary row limit when asins is not provided. Allowed values: 20, 50, 100.
start_date (optional): ASIN detail mode start date parsed with Time.zone.parse.
end_date (optional): ASIN detail mode end date parsed with Time.zone.parse.

Request Examples

Business summary mode

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/traffic?top_items_count=20"

ASIN detail mode

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/traffic?asin=B000000001&start_date=2026-01-01&end_date=2026-02-28"

Response Examples

Business summary response (`200`)

{
  "traffic": {
    "mode": "business",
    "top_items_count": 20,
    "top_items_count_options": [20, 50, 100],
    "dates": ["2026-02-16", "2026-02-23"],
    "rows": [
      {
        "asin": "B000000001",
        "total_page_views": 1997,
        "buy_box_percentage": 81.5,
        "page_views_by_date": {
          "2026-02-16": 999,
          "2026-02-23": 998
        },
        "item": {
          "id": 12345,
          "model_number": "SKU-1",
          "business_id": 101,
          "supplier_id": 15
        }
      }
    ],
    "total_page_views_by_date": {
      "2026-02-16": 24675,
      "2026-02-23": 24650
    },
    "links": [
      { "rel": "self", "href": "https://app.shipmentbot.com/api/v1/traffic?top_items_count=20", "method": "GET" },
      { "rel": "api_root", "href": "https://app.shipmentbot.com/api/v1", "method": "GET" },
      { "rel": "sellers", "href": "https://app.shipmentbot.com/api/v1/sellers", "method": "GET" },
      { "rel": "sales_week_over_week", "href": "https://app.shipmentbot.com/api/v1/sales_week_over_week", "method": "GET" },
      { "rel": "sales_month_over_month", "href": "https://app.shipmentbot.com/api/v1/sales_month_over_month", "method": "GET" },
      { "rel": "sales_ytd", "href": "https://app.shipmentbot.com/api/v1/sales_ytd", "method": "GET" },
      { "rel": "sales_ltm", "href": "https://app.shipmentbot.com/api/v1/sales_ltm", "method": "GET" }
    ]
  }
}

ASIN detail response (`200`)

{
  "traffic": {
    "mode": "asin",
    "asin": "B000000001",
    "available_dates": ["2026-02-16", "2026-02-23"],
    "start_date": "2026-02-16",
    "end_date": "2026-02-23",
    "series": {
      "page_views_by_week": {
        "2026-02-16": 999,
        "2026-02-23": 998
      },
      "sessions_by_week": {
        "2026-02-16": 200,
        "2026-02-23": 199
      }
    },
    "rows": [
      {
        "time_period": "2026-02-23",
        "page_views": 998,
        "sessions": 199,
        "buy_box_percentage": 81.0,
        "units_ordered": 19,
        "ordered_product_sales_cents": 99900,
        "conversion_rate": 1.9
      }
    ],
    "links": [
      { "rel": "self", "href": "https://app.shipmentbot.com/api/v1/traffic?asin=B000000001&start_date=2026-01-01&end_date=2026-02-28", "method": "GET" },
      { "rel": "api_root", "href": "https://app.shipmentbot.com/api/v1", "method": "GET" },
      { "rel": "sellers", "href": "https://app.shipmentbot.com/api/v1/sellers", "method": "GET" },
      { "rel": "sales_week_over_week", "href": "https://app.shipmentbot.com/api/v1/sales_week_over_week", "method": "GET" },
      { "rel": "sales_month_over_month", "href": "https://app.shipmentbot.com/api/v1/sales_month_over_month", "method": "GET" },
      { "rel": "sales_ytd", "href": "https://app.shipmentbot.com/api/v1/sales_ytd", "method": "GET" },
      { "rel": "sales_ltm", "href": "https://app.shipmentbot.com/api/v1/sales_ltm", "method": "GET" }
    ]
  }
}

Error Examples

Invalid or expired access token (`401`)

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

Unknown ASIN in detail mode (`404`)

{
  "error": "Not Found",
  "message": "No traffic data found for ASIN B000009999"
}

API Controller: api/v1/traffic