Amazon Sync API Reference

GraphQL API for querying synced Amazon Selling Partner data.

Getting Started

Endpoint

POST https://api.datawarehouse.jls.dev/v1/graphql

Authentication

Every request requires three auth headers:

Header Value Description
x-hasura-admin-secret <secret> API secret — stored in GCP Secret Manager (HASURA_ADMIN_SECRET). Ask the team for access.
x-hasura-role client Always set to client. This enforces row-level security.
x-hasura-client-id <integer> Your seller/organization ID. All queries are automatically scoped to this client's data.

Note: The x-hasura-* prefix is a convention of the underlying GraphQL engine. Treat these as standard API headers.

You don't need to filter by client_id in your queries — it's enforced server-side on every table.

Quick Test

# Set these once
export API_URL="https://api.datawarehouse.jls.dev/v1/graphql"
export API_SECRET="<ask team for secret>"
export CLIENT_ID=7

curl -X POST "$API_URL" \
  -H "x-hasura-admin-secret: $API_SECRET" \
  -H "x-hasura-role: client" \
  -H "x-hasura-client-id: $CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ daily_fba_inventory(limit: 3) { seller_sku asin fulfillable } }"}'

Available Data

Table What It Contains Updated
daily_fba_inventory FBA warehouse stock levels per SKU Every 30 min
daily_fbm_inventory Merchant-fulfilled stock per SKU Every 30 min
daily_sc_inventory Seller Central listings with pricing Every 30 min
daily_shipping_inventory In-transit and receiving inventory Hourly
daily_sales Daily sales (units, revenue, refunds) per SKU Every 30 min
daily_orders_summary Order counts by status per SKU per day Every 30 min
order_items Individual order line items with full details Every 30 min
inventory_snapshots Historical point-in-time inventory records Every sync
returns FBA customer returns with reasons Unavailable — pending SP-API permission approval
reimbursements FBA reimbursements (lost/damaged inventory) Unavailable — pending SP-API permission approval
daily_fba_fees Estimated FBA fee breakdown per SKU Daily
inventory_ledger Inventory balance changes (receipts, shipments, adjustments) Every 3 hours
financial_events Financial charges, fees, and refunds per order Daily
daily_product_pricing Competitive pricing (buy box, lowest offers) Daily
settlements Settlement report line items Daily
removals FBA removal/disposal orders Daily
catalog Product catalog (title, brand, dimensions, images) Daily
daily_sales_traffic Traffic metrics (page views, sessions, conversion) Daily
seller_performance Seller health metrics (defect rate, late shipment) Daily
promotions Promotion performance (units sold, revenue by promo) Daily
replacements FBA replacement shipments Unavailable — pending SP-API permission approval

Key Concepts

All data is at the seller SKU level. A single ASIN can have multiple SKUs (e.g., New vs Refurbished). Use aggregate queries to roll up to ASIN level when needed.

Common fields across all tables:

Example Queries

Current FBA inventory

{
  daily_fba_inventory(
    where: { client_id: { _eq: 7 }, date: { _eq: "2026-03-28" } }
    order_by: { fulfillable: desc }
  ) {
    seller_sku
    asin
    fulfillable
    reserved
    days_of_supply
  }
}

Sales for last 7 days (aggregated)

{
  daily_sales_aggregate(
    where: {
      client_id: { _eq: 7 }
      date: { _gte: "2026-03-21" }
    }
  ) {
    aggregate {
      sum { units_sold revenue refund_amount }
    }
  }
}

Sales by ASIN (summing across all SKUs)

{
  daily_sales_aggregate(
    where: {
      client_id: { _eq: 7 }
      asin: { _eq: "B001234" }
      date: { _gte: "2026-03-01" }
    }
  ) {
    aggregate {
      sum { units_sold revenue }
    }
  }
}

Recent orders

{
  order_items(
    where: {
      client_id: { _eq: 7 }
      purchase_date: { _gte: "2026-03-21T00:00:00Z" }
    }
    order_by: { purchase_date: desc }
    limit: 20
  ) {
    order_id
    seller_sku
    asin
    purchase_date
    order_status
    item_price
    quantity
  }
}

Low stock alerts

{
  daily_fba_inventory(
    where: {
      client_id: { _eq: 7 }
      date: { _eq: "2026-03-28" }
      days_of_supply: { _lt: 7 }
      fulfillable: { _gt: 0 }
    }
    order_by: { days_of_supply: asc }
  ) {
    seller_sku
    asin
    fulfillable
    days_of_supply
  }
}

Returns for last 30 days

Note: Returns data is currently unavailable. Our SP-API application is pending permission approval for FBA returns reports. The table schema exists but contains no data.

{
  returns(
    where: { client_id: { _eq: 7 }, return_date: { _gte: "2026-03-01" } }
    order_by: { return_date: desc }
  ) {
    order_id
    seller_sku
    asin
    return_date
    quantity
    reason
    disposition
  }
}

Financial events summary

{
  financial_events_aggregate(
    where: {
      client_id: { _eq: 7 }
      posted_date: { _gte: "2026-03-01T00:00:00Z" }
    }
  ) {
    aggregate {
      sum { amount }
      count
    }
  }
}

Buy box status

{
  daily_product_pricing(
    where: {
      client_id: { _eq: 7 }
      date: { _eq: "2026-03-28" }
      is_buy_box_winner: { _eq: true }
    }
  ) {
    seller_sku
    asin
    buy_box_price
    listing_price
    number_of_offers
  }
}

Traffic and conversion

{
  daily_sales_traffic(
    where: {
      client_id: { _eq: 7 }
      date: { _gte: "2026-03-21" }
    }
    order_by: { date: desc }
  ) {
    asin
    date
    page_views
    sessions
    units_ordered
    unit_session_percentage
  }
}

Filtering

Operator Meaning
_eq Equals
_gt / _gte Greater than (or equal)
_lt / _lte Less than (or equal)
_in In a list of values
_like Pattern match (% wildcard)
_is_null Check for null

Aggregation

Append _aggregate to any table name. Available functions: sum, avg, count, min, max.

Row-Level Security

All queries use the client role (set via x-hasura-role: client and x-hasura-client-id headers). This automatically scopes every query to that seller's data — no need to add client_id filters in your GraphQL queries.