API Endpoint Group: /api/v1/sales_*

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

Endpoints

GET /api/v1/sales_ltm

Returns last-twelve-month aggregated sales ranking by SKU for the seller tied to the API key.

Query Options

• limit (optional): Minimum 25 rows returned. Values lower than 25 are coerced to 25.
• summary_rank (optional): Ranking metric used to sort rows. Allowed values: ordered_product_sales_cents, units_ordered.

Request Examples

Last twelve months sales by units

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/sales_ltm?summary_rank=units_ordered&limit=25"

Response Examples

Success (200)

{
  "sales": {
    "type": "ltm",
    "summary_rank": "units_ordered",
    "limit": 25,
    "period_label": "L12M",
    "rows": [
      {
        "seller_sku": "SKU-101",
        "asin": "B000000101",
        "title": "Example Product",
        "shipped_cogs_cents": 425000,
        "shipped_units": 388
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://app.shipmentbot.com/api/v1/sales_ltm?summary_rank=units_ordered&limit=25",
        "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": "traffic",
        "href": "https://app.shipmentbot.com/api/v1/traffic",
        "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"
      }
    ],
    "metadata": {
      "other_sales_endpoints": [
        {
          "key": "sales_week_over_week",
          "url": "https://app.shipmentbot.com/api/v1/sales_week_over_week"
        },
        {
          "key": "sales_month_over_month",
          "url": "https://app.shipmentbot.com/api/v1/sales_month_over_month"
        },
        {
          "key": "sales_ytd",
          "url": "https://app.shipmentbot.com/api/v1/sales_ytd"
        }
      ]
    }
  }
}

Error Examples

Missing access token (401)

{
  "error": "Unauthorized",
  "message": "Missing access token"
}

GET /api/v1/sales_month_over_month

Returns month-over-month sales ranking by SKU for the seller tied to the API key.

Query Options

• limit (optional): Minimum 25 rows returned. Values lower than 25 are coerced to 25.
• summary_rank (optional): Ranking metric used to sort rows. Allowed values: ordered_product_sales_cents, units_ordered.

Request Examples

Month-over-month sales by revenue

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/sales_month_over_month?summary_rank=ordered_product_sales_cents&limit=25"

Response Examples

Success (200)

{
  "sales": {
    "type": "month_over_month",
    "summary_rank": "ordered_product_sales_cents",
    "limit": 25,
    "older_period": "2026-01-01",
    "sooner_period": "2026-02-01",
    "rows": [
      {
        "seller_sku": "SKU-101",
        "asin": "B000000101",
        "title": "Example Product",
        "older_shipped_cogs_cents": 45000,
        "sooner_shipped_cogs_cents": 57000,
        "cogs_diff": 26.6667,
        "older_shipped_units": 40,
        "sooner_shipped_units": 52,
        "units_diff": 30.0
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://app.shipmentbot.com/api/v1/sales_month_over_month?summary_rank=ordered_product_sales_cents&limit=25",
        "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": "traffic",
        "href": "https://app.shipmentbot.com/api/v1/traffic",
        "method": "GET"
      },
      {
        "rel": "sales_week_over_week",
        "href": "https://app.shipmentbot.com/api/v1/sales_week_over_week",
        "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"
      }
    ],
    "metadata": {
      "other_sales_endpoints": [
        {
          "key": "sales_week_over_week",
          "url": "https://app.shipmentbot.com/api/v1/sales_week_over_week"
        },
        {
          "key": "sales_ytd",
          "url": "https://app.shipmentbot.com/api/v1/sales_ytd"
        },
        {
          "key": "sales_ltm",
          "url": "https://app.shipmentbot.com/api/v1/sales_ltm"
        }
      ]
    }
  }
}

Error Examples

Missing access token (401)

{
  "error": "Unauthorized",
  "message": "Missing access token"
}

GET /api/v1/sales_week_over_week

Returns week-over-week sales ranking by SKU for the seller tied to the API key.

Query Options

• limit (optional): Minimum 25 rows returned. Values lower than 25 are coerced to 25.
• summary_rank (optional): Ranking metric used to sort rows. Allowed values: ordered_product_sales_cents, units_ordered.

Request Examples

Week-over-week sales by units

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/sales_week_over_week?summary_rank=units_ordered&limit=50"

Response Examples

Success (200)

{
  "sales": {
    "type": "week_over_week",
    "summary_rank": "units_ordered",
    "limit": 50,
    "older_period": "2026-02-16",
    "sooner_period": "2026-02-23",
    "rows": [
      {
        "seller_sku": "SKU-101",
        "asin": "B000000101",
        "title": "Example Product",
        "older_shipped_cogs_cents": 9900,
        "sooner_shipped_cogs_cents": 12500,
        "cogs_diff": 26.2626,
        "older_shipped_units": 9,
        "sooner_shipped_units": 12,
        "units_diff": 33.3333
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://app.shipmentbot.com/api/v1/sales_week_over_week?summary_rank=units_ordered&limit=50",
        "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": "traffic",
        "href": "https://app.shipmentbot.com/api/v1/traffic",
        "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"
      }
    ],
    "metadata": {
      "other_sales_endpoints": [
        {
          "key": "sales_month_over_month",
          "url": "https://app.shipmentbot.com/api/v1/sales_month_over_month"
        },
        {
          "key": "sales_ytd",
          "url": "https://app.shipmentbot.com/api/v1/sales_ytd"
        },
        {
          "key": "sales_ltm",
          "url": "https://app.shipmentbot.com/api/v1/sales_ltm"
        }
      ]
    }
  }
}

Error Examples

Missing access token (401)

{
  "error": "Unauthorized",
  "message": "Missing access token"
}

GET /api/v1/sales_ytd

Returns year-to-date aggregated sales ranking by SKU for the seller tied to the API key.

Query Options

• limit (optional): Minimum 25 rows returned. Values lower than 25 are coerced to 25.
• summary_rank (optional): Ranking metric used to sort rows. Allowed values: ordered_product_sales_cents, units_ordered.

Request Examples

Year-to-date sales

curl -s \
  -H "Authorization: Bearer oc_sk_your_key_here" \
  "https://app.shipmentbot.com/api/v1/sales_ytd?summary_rank=ordered_product_sales_cents&limit=100"

Response Examples

Success (200)

{
  "sales": {
    "type": "ytd",
    "summary_rank": "ordered_product_sales_cents",
    "limit": 100,
    "period_label": "YTD",
    "rows": [
      {
        "seller_sku": "SKU-101",
        "asin": "B000000101",
        "title": "Example Product",
        "shipped_cogs_cents": 185000,
        "shipped_units": 166
      }
    ],
    "links": [
      {
        "rel": "self",
        "href": "https://app.shipmentbot.com/api/v1/sales_ytd?summary_rank=ordered_product_sales_cents&limit=100",
        "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": "traffic",
        "href": "https://app.shipmentbot.com/api/v1/traffic",
        "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_ltm",
        "href": "https://app.shipmentbot.com/api/v1/sales_ltm",
        "method": "GET"
      }
    ],
    "metadata": {
      "other_sales_endpoints": [
        {
          "key": "sales_week_over_week",
          "url": "https://app.shipmentbot.com/api/v1/sales_week_over_week"
        },
        {
          "key": "sales_month_over_month",
          "url": "https://app.shipmentbot.com/api/v1/sales_month_over_month"
        },
        {
          "key": "sales_ltm",
          "url": "https://app.shipmentbot.com/api/v1/sales_ltm"
        }
      ]
    }
  }
}

Error Examples

Missing access token (401)

{
  "error": "Unauthorized",
  "message": "Missing access token"
}