> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get brand billing state

> Billing profile, contract, current period, meter summary and forecast for the brand.

### Path parameters

<ParamField path="brand_id" type="string (uuid)" required />

### Response

`object`

<ResponseField name="profile" type="object">
  Billing profile

  <Expandable title="profile">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="brand_id" type="string (uuid)" required />

    <ResponseField name="tenant_id" type="string (uuid)" required />

    <ResponseField name="provider" type="string" required />

    <ResponseField name="billing_org_id" type="string" />

    <ResponseField name="stripe_customer_id" type="string" />

    <ResponseField name="stripe_subscription_id" type="string" />

    <ResponseField name="billing_email" type="string" />

    <ResponseField name="pricing_model" type="string" required />

    <ResponseField name="default_currency" type="string" required />

    <ResponseField name="meter_event_namespace" type="string" required />

    <ResponseField name="meter_event_overrides" type="object" required />

    <ResponseField name="enabled" type="boolean" required />

    <ResponseField name="metadata" type="object" required />

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />
  </Expandable>
</ResponseField>

<ResponseField name="contract" type="object">
  Billing contract

  <Expandable title="contract">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="brand_id" type="string (uuid)" required />

    <ResponseField name="tenant_id" type="string (uuid)" required />

    <ResponseField name="billing_profile_id" type="string (uuid)" />

    <ResponseField name="provider" type="string" required />

    <ResponseField name="contract_type" type="string" required />

    <ResponseField name="status" type="string" required />

    <ResponseField name="currency" type="string" required />

    <ResponseField name="period" type="string" required />

    <ResponseField name="display_name" type="string" required />

    <ResponseField name="commitment_label" type="string" required />

    <ResponseField name="commitment_fee_minor" type="integer" required />

    <ResponseField name="default_unit_amount_minor" type="integer" required />

    <ResponseField name="included_quantity" type="integer" required />

    <ResponseField name="starts_at" type="string (date-time)" />

    <ResponseField name="ends_at" type="string (date-time)" />

    <ResponseField name="metadata" type="object" required />

    <ResponseField name="rates" type="object[]" required>
      <Expandable title="rates">
        <ResponseField name="id" type="string (uuid)" required />

        <ResponseField name="contract_id" type="string (uuid)" required />

        <ResponseField name="outcome_type" type="string" required />

        <ResponseField name="display_name" type="string" />

        <ResponseField name="unit_amount_minor" type="integer" required />

        <ResponseField name="included_quantity" type="integer" required />

        <ResponseField name="committed_unit_amount_minor" type="integer" />

        <ResponseField name="metadata" type="object" required />

        <ResponseField name="created_at" type="string (date-time)" required />

        <ResponseField name="updated_at" type="string (date-time)" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />
  </Expandable>
</ResponseField>

<ResponseField name="current_period" type="object">
  Billing contract period

  <Expandable title="current_period">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="contract_id" type="string (uuid)" required />

    <ResponseField name="brand_id" type="string (uuid)" required />

    <ResponseField name="period_start" type="string (date-time)" required />

    <ResponseField name="period_end" type="string (date-time)" required />

    <ResponseField name="status" type="string" required />

    <ResponseField name="currency" type="string" required />

    <ResponseField name="commitment_fee_minor" type="integer" required />

    <ResponseField name="included_quantity" type="integer" required />

    <ResponseField name="consumed_quantity" type="integer" required />

    <ResponseField name="covered_quantity" type="integer" required />

    <ResponseField name="overage_quantity" type="integer" required />

    <ResponseField name="estimated_overage_minor" type="integer" required />

    <ResponseField name="estimated_savings_minor" type="integer" required />

    <ResponseField name="invoice_summary" type="object" required />

    <ResponseField name="closed_at" type="string (date-time)" />

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  <Expandable title="summary">
    <ResponseField name="pending_events" type="integer" required />

    <ResponseField name="failed_events" type="integer" required />

    <ResponseField name="sent_events" type="integer" required />

    <ResponseField name="skipped_events" type="integer" required />

    <ResponseField name="pending_billable_outcomes" type="integer" required />

    <ResponseField name="last_sent_at" type="string (date-time)" />
  </Expandable>
</ResponseField>

<ResponseField name="forecast" type="object">
  <Expandable title="forecast">
    <ResponseField name="configured" type="boolean" required />

    <ResponseField name="pricing_model" type="string" required />

    <ResponseField name="currency" type="string" required />

    <ResponseField name="period_start" type="string (date-time)" required />

    <ResponseField name="period_end" type="string (date-time)" required />

    <ResponseField name="metered_quantity" type="integer" required />

    <ResponseField name="estimated_subtotal_minor" type="integer" required />

    <ResponseField name="estimated_base_fee_minor" type="integer" required />

    <ResponseField name="estimated_total_minor" type="integer" required />

    <ResponseField name="notes" type="string[]" required />

    <ResponseField name="committed_use" type="object">
      <Expandable title="committed_use">
        <ResponseField name="enabled" type="boolean" required />

        <ResponseField name="active" type="boolean" required />

        <ResponseField name="display_name" type="string" required />

        <ResponseField name="period" type="string" required />

        <ResponseField name="starts_at" type="string (date-time)" />

        <ResponseField name="ends_at" type="string (date-time)" />

        <ResponseField name="commitment_fee_minor" type="integer" required />

        <ResponseField name="included_quantity" type="integer" required />

        <ResponseField name="consumed_quantity" type="integer" required />

        <ResponseField name="covered_quantity" type="integer" required />

        <ResponseField name="overage_quantity" type="integer" required />

        <ResponseField name="remaining_quantity" type="integer" required />

        <ResponseField name="estimated_overage_minor" type="integer" required />

        <ResponseField name="estimated_savings_minor" type="integer" required />

        <ResponseField name="currency" type="string" required />
      </Expandable>
    </ResponseField>

    <ResponseField name="line_items" type="object[]" required>
      <Expandable title="line_items">
        <ResponseField name="key" type="string" required />

        <ResponseField name="kind" type="string" required />

        <ResponseField name="label" type="string" required />

        <ResponseField name="outcome_type" type="string" />

        <ResponseField name="quantity" type="integer" required />

        <ResponseField name="included_quantity" type="integer" required />

        <ResponseField name="billable_quantity" type="integer" required />

        <ResponseField name="committed_quantity" type="integer" required />

        <ResponseField name="overage_quantity" type="integer" required />

        <ResponseField name="unit_amount_minor" type="integer" required />

        <ResponseField name="committed_unit_amount_minor" type="integer" />

        <ResponseField name="overage_unit_amount_minor" type="integer" />

        <ResponseField name="subtotal_minor" type="integer" required />

        <ResponseField name="savings_minor" type="integer" required />

        <ResponseField name="currency" type="string" required />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recent_events" type="object[]" required>
  <Expandable title="recent_events">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="brand_id" type="string (uuid)" required />

    <ResponseField name="outcome_id" type="string (uuid)" required />

    <ResponseField name="billing_profile_id" type="string (uuid)" />

    <ResponseField name="provider" type="string" required />

    <ResponseField name="event_name" type="string" required />

    <ResponseField name="event_identifier" type="string" required />

    <ResponseField name="status" type="string" required />

    <ResponseField name="payload" type="object" required />

    <ResponseField name="response_body" type="object" />

    <ResponseField name="external_event_id" type="string" />

    <ResponseField name="last_error" type="string" />

    <ResponseField name="attempt_count" type="integer" required />

    <ResponseField name="queued_at" type="string (date-time)" required />

    <ResponseField name="last_attempt_at" type="string (date-time)" />

    <ResponseField name="sent_at" type="string (date-time)" />

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />
  </Expandable>
</ResponseField>

<ResponseField name="recent_rated_outcomes" type="object[]" required>
  <Expandable title="recent_rated_outcomes">
    <ResponseField name="id" type="string (uuid)" required />

    <ResponseField name="brand_id" type="string (uuid)" required />

    <ResponseField name="outcome_id" type="string (uuid)" required />

    <ResponseField name="billing_profile_id" type="string (uuid)" />

    <ResponseField name="contract_id" type="string (uuid)" />

    <ResponseField name="period_id" type="string (uuid)" />

    <ResponseField name="provider" type="string" required />

    <ResponseField name="outcome_type" type="string" required />

    <ResponseField name="occurred_at" type="string (date-time)" required />

    <ResponseField name="rating_kind" type="string" required />

    <ResponseField name="currency" type="string" required />

    <ResponseField name="quantity" type="integer" required />

    <ResponseField name="included_quantity" type="integer" required />

    <ResponseField name="committed_quantity" type="integer" required />

    <ResponseField name="overage_quantity" type="integer" required />

    <ResponseField name="unit_amount_minor" type="integer" required />

    <ResponseField name="committed_unit_amount_minor" type="integer" />

    <ResponseField name="subtotal_minor" type="integer" required />

    <ResponseField name="savings_minor" type="integer" required />

    <ResponseField name="commitment_applied" type="boolean" required />

    <ResponseField name="rated_at" type="string (date-time)" required />

    <ResponseField name="metadata" type="object" required />

    <ResponseField name="created_at" type="string (date-time)" required />

    <ResponseField name="updated_at" type="string (date-time)" required />
  </Expandable>
</ResponseField>

### Status codes

| Code  | Meaning                                                                              |
| ----- | ------------------------------------------------------------------------------------ |
| `200` | Billing profile, contract, current period, meter summary and forecast for the brand. |
| `400` | Validation error                                                                     |
| `401` | Unauthorized                                                                         |
| `404` | Not found                                                                            |
| `429` | Rate limited                                                                         |
| `500` | Internal error                                                                       |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.workstream.stateset.com/v1/brands/{brand_id}/billing' \
    --header "x-api-key: $STATESET_TEMPORAL_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "profile": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "provider": "string",
      "billing_org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "stripe_customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "stripe_subscription_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "billing_email": "string",
      "pricing_model": "string",
      "default_currency": "USD",
      "meter_event_namespace": "string",
      "meter_event_overrides": {},
      "enabled": true,
      "metadata": {},
      "created_at": "2026-08-31T14:22:05Z",
      "updated_at": "2026-08-31T14:22:05Z"
    },
    "contract": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "billing_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "provider": "string",
      "contract_type": "string",
      "status": "pending",
      "currency": "USD",
      "period": "string",
      "display_name": "Ada Lovelace",
      "commitment_label": "string",
      "commitment_fee_minor": 4900,
      "default_unit_amount_minor": 4900,
      "included_quantity": 1,
      "starts_at": "2026-08-31T14:22:05Z",
      "ends_at": "2026-08-31T14:22:05Z",
      "metadata": {},
      "rates": [
        {
          "id": null,
          "contract_id": null,
          "outcome_type": null,
          "display_name": null,
          "unit_amount_minor": null,
          "included_quantity": null,
          "committed_unit_amount_minor": null,
          "metadata": null,
          "created_at": null,
          "updated_at": null
        }
      ],
      "created_at": "2026-08-31T14:22:05Z",
      "updated_at": "2026-08-31T14:22:05Z"
    },
    "current_period": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "contract_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "period_start": "2026-08-31T14:22:05Z",
      "period_end": "2026-08-31T14:22:05Z",
      "status": "pending",
      "currency": "USD",
      "commitment_fee_minor": 4900,
      "included_quantity": 1,
      "consumed_quantity": 1,
      "covered_quantity": 1,
      "overage_quantity": 1,
      "estimated_overage_minor": 1,
      "estimated_savings_minor": 1,
      "invoice_summary": {},
      "closed_at": "2026-08-31T14:22:05Z",
      "created_at": "2026-08-31T14:22:05Z",
      "updated_at": "2026-08-31T14:22:05Z"
    },
    "summary": {
      "pending_events": 1,
      "failed_events": 1,
      "sent_events": 1,
      "skipped_events": 1,
      "pending_billable_outcomes": 1,
      "last_sent_at": "2026-08-31T14:22:05Z"
    },
    "forecast": {
      "configured": true,
      "pricing_model": "string",
      "currency": "USD",
      "period_start": "2026-08-31T14:22:05Z",
      "period_end": "2026-08-31T14:22:05Z",
      "metered_quantity": 1,
      "estimated_subtotal_minor": 4900,
      "estimated_base_fee_minor": 4900,
      "estimated_total_minor": 4900,
      "notes": [
        "Two-person tent, green — replacement for damaged pole set."
      ],
      "committed_use": {
        "enabled": true,
        "active": true,
        "display_name": "Ada Lovelace",
        "period": "string",
        "starts_at": "2026-08-31T14:22:05Z",
        "ends_at": "2026-08-31T14:22:05Z",
        "commitment_fee_minor": 4900,
        "included_quantity": 1,
        "consumed_quantity": 1,
        "covered_quantity": 1,
        "overage_quantity": 1,
        "remaining_quantity": 1,
        "estimated_overage_minor": 1,
        "estimated_savings_minor": 1,
        "currency": "USD"
      },
      "line_items": [
        {
          "key": null,
          "kind": null,
          "label": null,
          "outcome_type": null,
          "quantity": null,
          "included_quantity": null,
          "billable_quantity": null,
          "committed_quantity": null,
          "overage_quantity": null,
          "unit_amount_minor": null,
          "committed_unit_amount_minor": null,
          "overage_unit_amount_minor": null,
          "subtotal_minor": null,
          "savings_minor": null,
          "currency": null
        }
      ]
    },
    "recent_events": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "outcome_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "billing_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "provider": "string",
        "event_name": "string",
        "event_identifier": "string",
        "status": "pending",
        "payload": {},
        "response_body": {},
        "external_event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "last_error": "string",
        "attempt_count": 1,
        "queued_at": "2026-08-31T14:22:05Z",
        "last_attempt_at": "2026-08-31T14:22:05Z",
        "sent_at": "2026-08-31T14:22:05Z",
        "created_at": "2026-08-31T14:22:05Z",
        "updated_at": "2026-08-31T14:22:05Z"
      }
    ],
    "recent_rated_outcomes": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "brand_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "outcome_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "billing_profile_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "contract_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "period_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "provider": "string",
        "outcome_type": "string",
        "occurred_at": "2026-08-31T14:22:05Z",
        "rating_kind": "string",
        "currency": "USD",
        "quantity": 2,
        "included_quantity": 1,
        "committed_quantity": 1,
        "overage_quantity": 1,
        "unit_amount_minor": 4900,
        "committed_unit_amount_minor": 4900,
        "subtotal_minor": 4900,
        "savings_minor": 1,
        "commitment_applied": true,
        "rated_at": "2026-08-31T14:22:05Z",
        "metadata": {},
        "created_at": "2026-08-31T14:22:05Z",
        "updated_at": "2026-08-31T14:22:05Z"
      }
    ]
  }
  ```
</ResponseExample>