GET Usage

Read your daily seat-day ledger, its Stripe reporting state and the current number of open seats. This is a read of recorded usage, not a request to compute usage or submit a Stripe event. See Billing and usage for how seats are counted.

Endpoint

GET https://app.crosstrade.io/v1/api/partner/usage

Headers

Name	Required	Value
Authorization	Yes	Bearer <partner access token> with partner:read (also implied by partner:provision)

Query parameters

Name	Type	Required	Description
from	date	With to	First UTC day, inclusive, as YYYY-MM-DD
to	date	With from	Last UTC day, inclusive, as YYYY-MM-DD

Supply both dates or omit both. The requested range may span at most 92 days. Only closed UTC days are reported: a to value reaching today or later is capped at yesterday. With no dates, the range is the current month's closed days; on the first of a month, days is empty, total is zero and to is the previous month's final day.

No request body or pagination. Unknown or repeated query parameters are rejected.

Code examples

Set PARTNER_TOKEN. Replace the dates with your reporting window, or omit both to read the current month.

Python

import json
import os
import requests

response = requests.get(
    "https://app.crosstrade.io/v1/api/partner/usage",
    headers={"Authorization": f"Bearer {os.environ['PARTNER_TOKEN']}"},
    params={"from": "2026-10-01", "to": "2026-10-02"},
    timeout=15,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

const query = new URLSearchParams({ from: "2026-10-01", to: "2026-10-02" });
const response = await fetch(`https://app.crosstrade.io/v1/api/partner/usage?${query}`, {
  headers: { Authorization: `Bearer ${process.env.PARTNER_TOKEN}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log(JSON.stringify(await response.json(), null, 2));

cURL

curl -sS --get "https://app.crosstrade.io/v1/api/partner/usage" \
  -H "Authorization: Bearer $PARTNER_TOKEN" \
  --data-urlencode "from=2026-10-01" \
  --data-urlencode "to=2026-10-02"

Response

200 OK. This example shows one accepted day and one awaiting computation. A missing quantity is null, not proof of zero usage.

{
  "success": true,
  "usage": {
    "from": "2026-10-01",
    "to": "2026-10-02",
    "days": [
      {
        "day": "2026-10-01",
        "quantity": 11,
        "state": "accepted",
        "delivery_state": "accepted",
        "computed_at": "2026-10-02T00:20:03Z",
        "accepted_at": "2026-10-02T00:20:04Z",
        "reconciled_at": null,
        "reconciliation_state": "pending",
        "invoice": null,
        "error": null,
        "difference": null
      },
      {
        "day": "2026-10-02",
        "quantity": null,
        "state": "pending_computation",
        "delivery_state": "pending",
        "computed_at": null,
        "accepted_at": null,
        "reconciled_at": null,
        "reconciliation_state": "pending",
        "invoice": null,
        "error": null,
        "difference": null
      }
    ],
    "total": 11,
    "total_is_estimate": true,
    "open_seats": 12,
    "as_of": "2026-10-03T00:10:05Z"
  },
  "meta": {
    "requestId": "preq_b1c2d3e4f5a60718"
  }
}

Field	Meaning
from, to	Effective inclusive report window; to never reaches the open UTC day
days	Recorded days and pending days since billing began, ordered oldest first
days[].day, quantity	UTC date and known seat-day quantity, or null while computation is pending
days[].state	pending_computation, computed, submitting, accepted, reconciled, unknown, rejected or manual_review
days[].delivery_state	pending before computation, not_required for zero usage, accepted after Stripe accepts it, otherwise the ledger state
days[].computed_at, accepted_at, reconciled_at	UTC timestamps for computation, Stripe acceptance and daily reconciliation; null until available
days[].reconciliation_state	pending, matched or mismatch
days[].invoice	Invoice reference with id, quantity, period_start and period_end, or null. Quantity covers the invoice period
days[].error	Last submission error, or null
days[].difference	Invoice-period quantity minus the ledger total for that period, or null before comparison
total	Sum of known quantities; days awaiting computation contribute zero to the sum
total_is_estimate	true until every returned day is reconciled
open_seats	Seats open when this report was read, independent of the requested historical range
as_of	UTC time the report was built

Zero-seat days reconcile locally with delivery_state: not_required. A reconciled nonzero day has been checked against Stripe's daily meter summary; it can be reconciled before an invoice exists. The report shows seat-day quantities, not the invoice's monetary total, base fee, taxes or discounts.

Errors

Status	Error	Meaning
400	validation_failed	Invalid date, missing paired date, reversed range, range longer than 92 days, unsupported query parameter or unexpected body
401	unauthorized	Invalid partner token
403	insufficient_scope, partner_not_enabled, partner_disabled	Scope or service policy refuses the read
429	rate_limited, too_many_concurrent_requests	Honor Retry-After
503	storage_unavailable, policy_unavailable, auth_unavailable, partner_api_unavailable	Retry with backoff

See Partner errors for response shapes.