Billing

Get current user's billing period statement

Returns a customer-safe JSON statement for one billing period, combining the ledger, endpoint breakdown, optional billing events, and Stripe invoice evidence. Closed periods normally return a pre-frozen snapshot created during period close; historical closed periods without a snapshot are lazily frozen on read. Repair errors and raw webhook audit details are not exposed.

get/billing/me/periods/{period_key}/statement

Request

  • Base URL: https://api.crawlora.net/api/v1
  • URL: https://api.crawlora.net/api/v1/billing/me/periods/{period_key}/statement
  • Auth: API key in header x-api-key

Path parameters

period_keystring required

Billing period key in YYYY-MM format

Query parameters

include_eventsboolean

Include recent billing events. Defaults to true.

event_limitinteger

Maximum billing events to include. Defaults to 100 and clamps to 500.

Headers

x-api-keystring required

API key required unless an authenticated JWT is already present

Response

Billing period statement

codeinteger
msgstring

Example response

{
  "code": 200,
  "data": {
    "accounts_receivable": {
      "amount_due_cents": 7900,
      "amount_paid_cents": 7900,
      "due_date": "2026-05-08T00:00:00Z",
      "effective_due_date": "2026-05-08T00:00:00Z",
      "finalized_at": "2026-05-01T01:00:00Z",
      "invoice_status": "paid",
      "paid_at": "2026-05-01T01:01:00Z",
      "payment_failed_at": "2026-05-01T01:01:00Z"
    },
    "adjustment_events": [
      {
        "amount_cents": 500,
        "currency": "usd",
        "event_created": "2026-05-02T01:01:00Z",
        "event_id": "evt_adj_123",
        "event_type": "credit_note.created",
        "kind": "credit_note",
        "match_status": "matched",
        "processed_at": "2026-05-02T01:01:02Z",
        "reconciliation_status": "matched",
        "repair_attempts": 1,
        "repair_status": "succeeded",
        "resource_id": "cn_123",
        "resource_status": "issued",
        "stripe_invoice_id": "in_123"
      }
    ],
    "endpoint_breakdown": [
      {
        "charged_requests": 1150,
        "credits": 3450,
        "endpoint": "google/search",
        "failed_requests": 5,
        "non_billable_requests": 45,
        "requests": 1200
      }
    ],
    "events": [
      {
        "billable": true,
        "created_at": "2026-04-16T10:00:00Z",
        "credit_cost": 3,
        "endpoint": "google/search",
        "event_status": "charged",
        "request_id": "req-1",
        "status_code": 200
      }
    ],
    "expected": {
      "credits_used": 3450,
      "currency": "usd",
      "expected_subscription_amount_cents": 7900,
      "expected_total_amount_cents": 7900,
      "included_credits": 400000,
      "overage_price_per_1000": 0.3,
      "pricing_source": "plan_default",
      "subscription_price_cents": 7900
    },
    "generated_at": "2026-05-01T02:00:00Z",
    "invoice": {
      "amount_due_cents": 7900,
      "amount_paid_cents": 7900,
      "currency": "usd",
      "due_date": "2026-05-08T00:00:00Z",
      "effective_due_date": "2026-05-08T00:00:00Z",
      "finalized_at": "2026-05-01T01:00:00Z",
      "hosted_invoice_url": "https://invoice.stripe.com/i/acct_...",
      "invoice_pdf": "https://pay.stripe.com/invoice/.../pdf",
      "line_items": [
        {
          "amount_cents": 7900,
          "category": "subscription",
          "currency": "usd",
          "description": "Pro plan",
          "line_id": "il_123",
          "period_end": "2026-05-01T00:00:00Z",
          "period_start": "2026-04-01T00:00:00Z",
          "source_ref": "sub_123",
          "type": "subscription"
        }
      ],
      "paid_at": "2026-05-01T01:01:00Z",
      "period_end": "2026-05-01T00:00:00Z",
      "period_start": "2026-04-01T00:00:00Z",
      "reconciliation_status": "paid",
      "repair_attempts": 1,
      "repair_status": "succeeded",
      "stripe_invoice_id": "in_123",
      "stripe_invoice_number": "C8F8C2D-0001",
      "stripe_invoice_status": "paid"
    },
    "invoice_events": [
      {
        "event_created": "2026-05-01T01:01:00Z",
        "event_id": "evt_123",
        "event_type": "invoice.paid",
        "match_status": "matched",
        "processed_at": "2026-05-01T01:01:02Z",
        "reconciliation_status": "paid",
        "repair_attempts": 1,
        "repair_status": "succeeded",
        "stripe_invoice_id": "in_123",
        "stripe_invoice_status": "paid"
      }
    ],
    "period": {
      "closed_at": "2026-05-01T00:15:00Z",
      "period_end": "2026-05-01T00:00:00Z",
      "period_key": "2026-04",
      "period_start": "2026-04-01T00:00:00Z",
      "status": "closed"
    },
    "plan": "Pro",
    "repair": {
      "repair_attempts": 1,
      "repair_last_attempt_at": "2026-05-01T02:00:00Z",
      "repair_status": "succeeded",
      "stripe_sync_attempts": 1,
      "stripe_sync_status": "synced",
      "stripe_synced_at": "2026-05-01T00:30:01Z"
    },
    "snapshot": {
      "canonical_json_sha256": "7f83b1657ff1fc53b92dc18148a1d65dfa1355e5545b1e8d2b0e9f8c9e48a5d8",
      "frozen_at": "2026-05-01T02:00:00Z",
      "generated_at": "2026-05-01T02:00:00Z",
      "revision": 1,
      "snapshot_status": "frozen",
      "source_ledger_updated_at": "2026-05-01T00:15:00Z",
      "source_snapshot_updated_at": "2026-05-01T01:01:00Z",
      "statement_id": "bps:user-1:2026-04:1",
      "statement_version": "v1"
    },
    "stripe_actual": {
      "amount_due_cents": 7900,
      "amount_paid_cents": 7900,
      "currency": "usd",
      "net_cash_cents": 7900,
      "snapshot_updated_at": "2026-05-01T01:01:00Z",
      "subscription_cents": 7900,
      "total_cents": 7900
    },
    "user": {
      "email": "alice@example.com",
      "plan": "Pro",
      "stripe_customer_id": "cus_123",
      "user_id": "user-1",
      "username": "alice"
    }
  },
  "msg": "OK"
}

Changes

No recorded changes to this operation across all 3 revisions of this API.