Billing & usage

Consumption analytics and the organization's view of its subscription, billing profile, and invoices.

Common responses

These responses apply across endpoints in this section unless an endpoint documents an additional response.

Status	Meaning	Body
`200`	Request succeeded.	Endpoint response object.
`201`	Resource created.	Created resource object.
`400`	Invalid request.	Error envelope.
`401`	Missing or invalid bearer token.	Error envelope.
`404`	Resource not found or not visible to the current organization.	Error envelope.

Usage

Get usage summary

Get a one-shot cost and token summary for the given date range, plus a delta percentage versus the preceding period of equal length. The `from` and `to` dates are inclusive; the range must be ≤ 365 days.

GET/v1/organization/usage/summary

Query parameters

Name	Type	Required	Description
`from`	`string`	Required	Start date in `YYYY-MM-DD` format (inclusive).
`to`	`string`	Required	End date in `YYYY-MM-DD` format (inclusive). Must be on or after `from`.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/organization/usage/summary?from=example&to=example" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "total_cost_cents": 184200,
  "total_input_tokens": 9420000,
  "total_output_tokens": 1830000,
  "total_cached_input_tokens": 2100000,
  "call_count": 3740,
  "period_cost_cents": 184200,
  "previous_period_cost_cents": 162400,
  "delta_pct": 13.4
}

Get usage timeseries

Get cost and token usage bucketed over time for charting. Use `granularity=daily` (default) for ranges up to 365 days, or `granularity=hourly` for ranges up to 7 days (168 hours).

GET/v1/organization/usage/timeseries

Query parameters

Name	Type	Required	Description
`from`	`string`	Required	Start date in `YYYY-MM-DD` format (inclusive).
`to`	`string`	Required	End date in `YYYY-MM-DD` format (inclusive).
`granularity`	`string`	Optional	Bucket size. One of: `daily` (default), `hourly`. Hourly is capped at a 168-hour window.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/organization/usage/timeseries?from=example&to=example" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "granularity": "daily",
  "items": [
    {
      "date": "2026-05-01",
      "cost_cents": 5820,
      "input_tokens": 298000,
      "output_tokens": 61000
    },
    {
      "date": "2026-05-02",
      "cost_cents": 6140,
      "input_tokens": 314000,
      "output_tokens": 65000
    },
    {
      "date": "2026-05-03",
      "cost_cents": 5490,
      "input_tokens": 281000,
      "output_tokens": 57000
    }
  ]
}

Get usage breakdown

Get cost and call-count broken down by a single dimension. Results are sorted by cost descending and capped at 50 rows. `percentOfTotal` is a percentage (0–100) rounded to one decimal place.

GET/v1/organization/usage/breakdown

Query parameters

Name	Type	Required	Description
`from`	`string`	Required	Start date in `YYYY-MM-DD` format (inclusive).
`to`	`string`	Required	End date in `YYYY-MM-DD` format (inclusive).
`dimension`	`string`	Required	Breakdown dimension. One of: `model`, `agent`, `channel`, `department`, `user`.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/organization/usage/breakdown?from=example&to=example" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "dimension": "model",
  "items": [
    {
      "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
      "label": "Claude claude-sonnet-4-5",
      "cost_cents": 124800,
      "call_count": 2580,
      "percent_of_total": 67.8
    },
    {
      "id": "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "label": "Claude claude-haiku-4-5",
      "cost_cents": 59400,
      "call_count": 1160,
      "percent_of_total": 32.2
    }
  ]
}

Get spend over time by dimension

Spend over time grouped by `department` or `user`. Returns the top-N values by total spend (default 6, max 20) as per-bucket series aligned to a `buckets` array spanning the full range, plus an `Other` series aggregating the rest (and any unattributed spend). Powers the Spending dashboard's per-dimension over-time charts.

GET/v1/organization/usage/timeseries-by

Query parameters

Name	Type	Required	Description
`from`	`string`	Required	Start date `YYYY-MM-DD` (inclusive).
`to`	`string`	Required	End date `YYYY-MM-DD` (inclusive).
`granularity`	`string`	Optional	`daily` (default) or `hourly` (hourly capped at 168 hours).
`dimension`	`string`	Required	`department` or `user`.
`limit`	`number`	Optional	Top-N series to return (default 6, max 20); the remainder is summed into `Other`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/usage/timeseries-by \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "granularity": "daily",
  "buckets": [
    "2026-04-14",
    "2026-04-15",
    "2026-04-16"
  ],
  "series": [
    {
      "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
      "label": "Ana Ng",
      "points": [
        100,
        200,
        0
      ]
    },
    {
      "id": "other",
      "label": "Other",
      "points": [
        0,
        50,
        0
      ]
    }
  ]
}

Wallet

Get wallet balance

Read-only view of the organization's prepaid wallet: `balance_minor`, `currency` (`USD`), `enforcement_enabled`, `low_balance_threshold_minor`. Amounts are in USD minor units (cents). Returns 404 (`no_wallet`) when no wallet is configured — treat that as "unlimited / not configured". Top-ups, enforcement, and limits are operator-managed (see the system Billing endpoints).

GET/v1/organization/wallet

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/wallet \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`404`	No wallet configured for the organization.	`{ error, code: 'no_wallet' }`
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "…",
  "organization_id": "…",
  "balance_minor": 4250,
  "currency": "usd",
  "enforcement_enabled": true,
  "low_balance_threshold_minor": 1000
}

Spend limits

Get spend limits

Read-only view of the organization's enabled monthly spend limits enriched with current calendar-month spend from rollup counters. Powers spending dashboard progress rows. Limits are sub-caps within the prepaid wallet and apply only when enforcement is enabled on the wallet.

GET/v1/organization/spend-limits

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/spend-limits \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "period_start": "2026-05-01",
  "period_end": "2026-05-31",
  "limits": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "scope": "organization",
      "scope_id": null,
      "label": "Organization",
      "amount_minor": 50000,
      "spent_minor": 18420,
      "remaining_minor": 31580,
      "percent_used": 36.84
    }
  ]
}

Subscription

Get subscription

Return the organization's live subscription joined with the plan name. "Live" means status is `trialing`, `active`, or `past_due`. Returns 404 if no live subscription exists.

GET/v1/organization/subscription

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/subscription \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`
`404`	No live subscription exists.	`{ error, code, request_id }`

200 OKjson

{
  "id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "plan_name": "Free",
  "plan_slug": "free",
  "status": "active",
  "billing_source": "manual",
  "stripe_subscription_id": null,
  "trial_ends_at": null,
  "started_at": "2026-05-18T10:24:31.000Z",
  "current_period_start": null,
  "current_period_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Change subscription plan

Switch the organization to a different plan. Atomically cancels the current live subscription (kept for audit) and inserts a new active subscription on the requested plan. Returns the new subscription row joined with the plan name. Returns 409 `same_plan` if the org is already on the requested plan, or 409 `managed_externally` if the subscription is Stripe-managed.

POST/v1/organization/subscription/change-plan

Request body

Name	Type	Required	Description
`planId`	`string (UUID)`	Required	ID of the plan to switch to. Use `GET /admin/plans` to list available plan IDs.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/subscription/change-plan \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"plan_id":"e3a7f2c8-1b9d-4e6a-87c5-3f9c2b1e6d54"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "7c3e1a85-4f2d-4b9c-a071-9e6d8b2c5f10",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "plan_id": "e3a7f2c8-1b9d-4e6a-87c5-3f9c2b1e6d54",
  "plan_name": "Pro",
  "plan_slug": "pro",
  "status": "active",
  "billing_source": "manual",
  "stripe_subscription_id": null,
  "trial_ends_at": null,
  "started_at": "2026-05-21T12:00:00.000Z",
  "current_period_start": null,
  "current_period_end": null,
  "cancel_at_period_end": false,
  "canceled_at": null,
  "created_at": "2026-05-21T12:00:00.000Z",
  "updated_at": "2026-05-21T12:00:00.000Z"
}

Cancel subscription

Cancel the organization's live subscription immediately. After this call the org has no live subscription — runtime requests will be rejected with HTTP 402 `no_active_subscription` until a new subscription is created via change-plan. The canceled row stays in the table for audit. Returns the bare subscription row (no `planName` join). Returns 409 `managed_externally` if the subscription is Stripe-managed.

POST/v1/organization/subscription/cancel

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/subscription/cancel \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "plan_id": "9a5e0f10-3c0a-4e88-8a89-d6e0b71b9d22",
  "status": "canceled",
  "billing_source": "manual",
  "stripe_subscription_id": null,
  "trial_ends_at": null,
  "started_at": "2026-05-18T10:24:31.000Z",
  "current_period_start": null,
  "current_period_end": null,
  "cancel_at_period_end": false,
  "canceled_at": "2026-05-21T12:00:00.000Z",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-21T12:00:00.000Z"
}

Billing profile

Get billing profile

Return the organization's default billing profile (`is_default = true`, or the oldest profile when none is marked default). Returns 404 `no_billing_profile` if no profile exists.

GET/v1/organization/billing-profile

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profile \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme HQ",
  "is_default": true,
  "legal_name": "Acme Inc.",
  "tax_id": "US-12-3456789",
  "registration_number": "C-4821990",
  "billing_email": "ap@acme.test",
  "billing_contact_name": "Dana Reyes",
  "billing_contact_phone": "+1 415 555 0142",
  "address_line1": "100 Market St",
  "address_line2": "Suite 400",
  "address_country": "US",
  "address_city": "San Francisco",
  "address_postal_code": "94103",
  "currency": "USD",
  "payment_terms": "net_30",
  "default_payment_method": "wire",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

List billing profiles

List all billing profiles for the organization. One profile may be marked `is_default`.

GET/v1/organization/billing-profiles

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profiles \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "name": "Acme HQ",
      "is_default": true,
      "legal_name": "Acme Inc.",
      "tax_id": "US-12-3456789",
      "registration_number": "C-4821990",
      "billing_email": "ap@acme.test",
      "billing_contact_name": "Dana Reyes",
      "billing_contact_phone": "+1 415 555 0142",
      "address_line1": "100 Market St",
      "address_line2": "Suite 400",
      "address_country": "US",
      "address_city": "San Francisco",
      "address_postal_code": "94103",
      "currency": "USD",
      "payment_terms": "net_30",
      "default_payment_method": "wire",
      "created_at": "2026-05-18T10:24:31.000Z",
      "updated_at": "2026-05-18T10:24:31.000Z"
    }
  ]
}

Get billing profile by ID

Return a single billing profile by ID. Returns 404 if the profile does not exist on this organization.

GET/v1/organization/billing-profiles/:profileId

Path parameters

Name	Type	Required	Description
`profileId`	`string`	Required	UUID of the billing profile.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profiles/b2c8d3a1-4567-89ab-cdef-012345678901 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme HQ",
  "is_default": true,
  "legal_name": "Acme Inc.",
  "tax_id": "US-12-3456789",
  "registration_number": "C-4821990",
  "billing_email": "ap@acme.test",
  "billing_contact_name": "Dana Reyes",
  "billing_contact_phone": "+1 415 555 0142",
  "address_line1": "100 Market St",
  "address_line2": "Suite 400",
  "address_country": "US",
  "address_city": "San Francisco",
  "address_postal_code": "94103",
  "currency": "USD",
  "payment_terms": "net_30",
  "default_payment_method": "wire",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Create billing profile

Create a billing profile for the organization. An org may have multiple profiles (e.g. regional legal entities). The first profile becomes the default. Only `name` and `legalName` are required. Every optional field accepts `null` to clear it, and an empty string is stored as `null` rather than as `""`. The organization's Stripe customer lives on the organization, not the profile, and is assigned automatically when the first card is saved.

POST/v1/organization/billing-profiles

Request body

Name	Type	Required	Description
`name`	`string`	Required	The name you use for this profile, e.g. `Acme HQ`. 1–120 characters.
`legalName`	`string`	Required	Registered legal entity name as it should appear on invoices. 1–255 characters.
`taxId`	`string \| null`	Optional	Tax / VAT registration number. Maximum 64 characters.
`registrationNumber`	`string \| null`	Optional	Company registration number for the legal entity. Maximum 64 characters.
`billingEmail`	`string \| null`	Optional	Where invoices and billing notices are delivered. Lowercased server-side. Maximum 255 characters.
`billingContactName`	`string \| null`	Optional	Person to contact about billing. Maximum 255 characters.
`billingContactPhone`	`string \| null`	Optional	Billing contact phone number. Length-bounded only — no format is enforced, so international numbers pass through as sent. Maximum 32 characters.
`addressLine1`	`string \| null`	Optional	Invoice address, first line. Maximum 255 characters.
`addressLine2`	`string \| null`	Optional	Invoice address, second line. Maximum 255 characters.
`addressCountry`	`string \| null`	Optional	Invoice address country as an ISO 3166-1 alpha-2 code, e.g. `AE`. Uppercased server-side. Exactly 2 characters; not checked against a country list.
`addressCity`	`string \| null`	Optional	Invoice address city. Maximum 120 characters.
`addressPostalCode`	`string \| null`	Optional	Invoice address postal code. Maximum 32 characters.
`isDefault`	`boolean`	Optional	Set true to make this the organization's default profile, demoting the current default.
`defaultPaymentMethod`	`string`	Optional	One of `wire`, `check`. Defaults to `wire` on create.
`currency`	`string`	Optional	Invoicing currency — `AED` or `USD`. Defaults to `AED`.
`paymentTerms`	`string`	Optional	One of `due_on_receipt`, `net_15`, `net_30`, `net_60`. Defaults to `net_30`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profiles \
  -X POST \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "Acme HQ",
    "legal_name": "Acme Inc.",
    "tax_id": "US-12-3456789",
    "registration_number": "C-4821990",
    "billing_email": "ap@acme.test",
    "billing_contact_name": "Dana Reyes",
    "billing_contact_phone": "+1 415 555 0142",
    "address_line1": "100 Market St",
    "address_line2": "Suite 400",
    "address_country": "US",
    "address_city": "San Francisco",
    "address_postal_code": "94103",
    "currency": "USD",
    "payment_terms": "net_30"
  }'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

201 Createdjson

{
  "id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme HQ",
  "is_default": true,
  "legal_name": "Acme Inc.",
  "tax_id": "US-12-3456789",
  "registration_number": "C-4821990",
  "billing_email": "ap@acme.test",
  "billing_contact_name": "Dana Reyes",
  "billing_contact_phone": "+1 415 555 0142",
  "address_line1": "100 Market St",
  "address_line2": "Suite 400",
  "address_country": "US",
  "address_city": "San Francisco",
  "address_postal_code": "94103",
  "currency": "USD",
  "payment_terms": "net_30",
  "default_payment_method": "wire",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-18T10:24:31.000Z"
}

Update billing profile

Update editable fields on a billing profile. All fields are optional, and an absent field is left untouched — so a single address line can be changed without resending the rest. Every optional field accepts `null` to clear it, and an empty string is stored as `null` rather than as `""`. `name` and `legalName` are the exception: they can be changed but not cleared. Strict-body — passing any unknown field returns 400. Returns 404 if the profile does not exist on this organization.

PATCH/v1/organization/billing-profiles/:profileId

Path parameters

Name	Type	Required	Description
`profileId`	`string`	Required	The profileId value from the endpoint path.

Request body

Name	Type	Required	Description
`name`	`string`	Optional	New profile name. 1–120 characters. Cannot be set to null or blank.
`legalName`	`string`	Optional	New legal entity name. 1–255 characters. Cannot be set to null or blank.
`taxId`	`string \| null`	Optional	Tax / VAT registration number. Maximum 64 characters.
`registrationNumber`	`string \| null`	Optional	Company registration number for the legal entity. Maximum 64 characters.
`billingEmail`	`string \| null`	Optional	Where invoices and billing notices are delivered. Lowercased server-side. Maximum 255 characters.
`billingContactName`	`string \| null`	Optional	Person to contact about billing. Maximum 255 characters.
`billingContactPhone`	`string \| null`	Optional	Billing contact phone number. Length-bounded only — no format is enforced, so international numbers pass through as sent. Maximum 32 characters.
`addressLine1`	`string \| null`	Optional	Invoice address, first line. Maximum 255 characters.
`addressLine2`	`string \| null`	Optional	Invoice address, second line. Maximum 255 characters.
`addressCountry`	`string \| null`	Optional	Invoice address country as an ISO 3166-1 alpha-2 code, e.g. `AE`. Uppercased server-side. Exactly 2 characters; not checked against a country list.
`addressCity`	`string \| null`	Optional	Invoice address city. Maximum 120 characters.
`addressPostalCode`	`string \| null`	Optional	Invoice address postal code. Maximum 32 characters.
`isDefault`	`boolean`	Optional	Set true to make this the organization's default profile, demoting the current default.
`defaultPaymentMethod`	`string`	Optional	One of `wire`, `check`. Defaults to `wire` on create.
`currency`	`string`	Optional	Invoicing currency — `AED` or `USD`.
`paymentTerms`	`string`	Optional	One of `due_on_receipt`, `net_15`, `net_30`, `net_60`.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profiles/b2c8d3a1-4567-89ab-cdef-012345678901 \
  -X PATCH \
  -H "Authorization: Bearer $CORTEX_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"address_city":"Dubai","address_country":"AE"}'

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`422`	Request body failed validation.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "name": "Acme HQ",
  "is_default": true,
  "legal_name": "Acme Inc.",
  "tax_id": "US-12-3456789",
  "registration_number": "C-4821990",
  "billing_email": "ap@acme.test",
  "billing_contact_name": "Dana Reyes",
  "billing_contact_phone": "+1 415 555 0142",
  "address_line1": "100 Market St",
  "address_line2": "Suite 400",
  "address_country": "AE",
  "address_city": "Dubai",
  "address_postal_code": "94103",
  "currency": "USD",
  "payment_terms": "net_30",
  "default_payment_method": "wire",
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-21T13:00:00.000Z"
}

Delete billing profile

Delete one of the organization's billing profiles. If the deleted profile was the default, the oldest remaining profile is promoted to default automatically. Invoices that referenced the profile keep the `billing_snapshot` they were issued with and have their `billing_profile_id` set to null.

DELETE/v1/organization/billing-profiles/:profileId

Path parameters

Name	Type	Required	Description
`profileId`	`string`	Required	The profileId value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/billing-profiles/b2c8d3a1-4567-89ab-cdef-012345678901 \
  -X DELETE \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`204`	Billing profile deleted. No response body.	—
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Profile not found on this organization.	`{ error, code: 'billing_profile_not_found' }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

Invoices

List invoices

List invoices for the organization, sorted newest first. Optionally filter by `status` (`draft`, `open`, `paid`, `void`, `uncollectible`).

GET/v1/organization/invoices

Query parameters

Name	Type	Required	Description
`status`	`string`	Optional	Filter by invoice status. One of `draft`, `open`, `paid`, `void`, `uncollectible`.

Example requestbash

curl "https://api.cortex.cognit-dx.com/v1/organization/invoices?status=example" \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "data": [
    {
      "id": "2a7f8b1c-5e3d-49a6-b8c2-7d1f5e9c3a48",
      "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
      "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
      "billing_profile_id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
      "status": "open",
      "total_usd_minor": 10000,
      "total_minor": 36725,
      "currency": "AED",
      "fx_rate": "3.672500",
      "due_date": "2026-06-15T00:00:00.000Z",
      "issued_at": "2026-05-21T09:00:00.000Z",
      "paid_at": null,
      "billing_snapshot": {
        "name": "Acme HQ",
        "legal_name": "Acme Inc.",
        "tax_id": "US-12-3456789",
        "registration_number": "C-4821990",
        "billing_email": "ap@acme.test",
        "billing_contact_name": "Dana Reyes",
        "billing_contact_phone": "+1 415 555 0142",
        "address_line1": "100 Market St",
        "address_line2": "Suite 400",
        "address_country": "US",
        "address_city": "San Francisco",
        "address_postal_code": "94103",
        "currency": "AED",
        "payment_terms": "net_30",
        "default_payment_method_id": null
      },
      "subscription_snapshot": {},
      "amount_paid_minor": 0,
      "amount_due_minor": 36725,
      "payments": [],
      "line_items": [
        {
          "description": "AI usage — May 2026",
          "amount_minor": 10000,
          "currency": "USD"
        }
      ],
      "notes": null,
      "created_at": "2026-05-18T10:24:31.000Z",
      "updated_at": "2026-05-21T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get invoice

Get a single invoice by ID, scoped to the caller's organization. Returns 404 for invoices that belong to a different org — cross-organization ID enumeration is not possible.

GET/v1/organization/invoices/:id

Path parameters

Name	Type	Required	Description
`id`	`string`	Required	The id value from the endpoint path.

Example requestbash

curl https://api.cortex.cognit-dx.com/v1/organization/invoices/9f7c9d3a-1234-5678-9abc-def012345678 \
  -H "Authorization: Bearer $CORTEX_TOKEN"

Response codes

Status	Meaning	Body
`401`	Missing or invalid credential.	`{ error, code, request_id }`
`404`	Resource not found in the caller's organization.	`{ error, code, request_id }`
`403`	Forbidden — caller must be an organization admin.	`{ error, code, request_id }`

200 OKjson

{
  "id": "2a7f8b1c-5e3d-49a6-b8c2-7d1f5e9c3a48",
  "organization_id": "f1ba15e0-ebe8-4187-afe6-03ccb25b8815",
  "subscription_id": "4b8a2f17-9d3e-4c5a-bc18-6e2f9d3a7b1c",
  "billing_profile_id": "8e5c1f93-6a2d-4b78-9f1c-3a5e7b2c8f14",
  "status": "open",
  "total_usd_minor": 10000,
  "total_minor": 36725,
  "currency": "AED",
  "fx_rate": "3.672500",
  "due_date": "2026-06-15T00:00:00.000Z",
  "issued_at": "2026-05-21T09:00:00.000Z",
  "paid_at": null,
  "billing_snapshot": {
    "name": "Acme HQ",
    "legal_name": "Acme Inc.",
    "tax_id": "US-12-3456789",
    "registration_number": "C-4821990",
    "billing_email": "ap@acme.test",
    "billing_contact_name": "Dana Reyes",
    "billing_contact_phone": "+1 415 555 0142",
    "address_line1": "100 Market St",
    "address_line2": "Suite 400",
    "address_country": "US",
    "address_city": "San Francisco",
    "address_postal_code": "94103",
    "currency": "AED",
    "payment_terms": "net_30",
    "default_payment_method_id": null
  },
  "subscription_snapshot": {},
  "amount_paid_minor": 0,
  "amount_due_minor": 36725,
  "payments": [],
  "line_items": [
    {
      "description": "AI usage — May 2026",
      "amount_minor": 10000,
      "currency": "USD"
    }
  ],
  "notes": null,
  "created_at": "2026-05-18T10:24:31.000Z",
  "updated_at": "2026-05-21T09:00:00.000Z"
}