Billing
Every call needs Authorization: Bearer <key>. 4 calls:
- Plan, lines billed, payment method and past-due state:
GET /v1/billing - List invoices:
GET /v1/billing/invoices - Open the Stripe customer portal:
POST /v1/billing/portal - Start adding a bank account (ACH) or card:
POST /v1/billing/setup-intent
Plan, lines billed, payment method and past-due state
GET /v1/billing
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
credits_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
current_period_end | string (date-time) or null | ISO 8601 timestamp. |
estimated_monthly_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
line_quantity | integer | From 0 to 9007199254740991. |
mandate_accepted_at | string (date-time) or null | ISO 8601 timestamp. |
mandate_status | string or null | |
past_due | object or null | |
past_due.amount_due_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
past_due.banner | boolean | |
past_due.day | integer | From 0 to 9007199254740991. |
past_due.hosted_invoice_url | string or null | |
past_due.invoice_id | string (uuid) | |
past_due.invoice_number | string | |
past_due.next_action | string or null | |
payment_method | object or null | |
payment_method.bank_name | string or null | |
payment_method.last4 | string or null | |
payment_method.type | enum | One of: us_bank_account, card. |
payment_setup | object | |
payment_setup.status | enum | One of: none, pending, requires_action, verified. |
payment_setup.verification_url | string or null | |
payments_mode | enum | One of: mock, stripe. |
per_line_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
plan | enum | One of: pilot, growth, enterprise. |
platform_fee_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
subscription_status | string or null |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List invoices
GET /v1/billing/invoices
From the Stripe mirror, newest first. Drafts are not shown.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | From 1 to 100. Default 50. |
cursor | string | No | Opaque cursor from next_cursor. Up to 512 characters. |
status | enum | No | One of: draft, open, processing, paid, failed, void, uncollectible. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].amount_due_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
data[].amount_paid_cents | integer | Amount in US cents. From -9007199254740991 to 9007199254740991. |
data[].description | string or null | |
data[].due_at | string (date-time) or null | ISO 8601 timestamp. |
data[].failure_code | string or null | |
data[].hosted_invoice_url | string or null | |
data[].id | string (uuid) | |
data[].issued_at | string (date-time) or null | ISO 8601 timestamp. |
data[].method | enum or null | One of: us_bank_account, card. |
data[].number | string | |
data[].paid_at | string (date-time) or null | ISO 8601 timestamp. |
data[].status | enum | One of: draft, open, processing, paid, failed, void, uncollectible. |
next_cursor | string or null | Pass as cursor to get the next page; null at the end. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Open the Stripe customer portal
POST /v1/billing/portal
A one-time portal link. return_url must be on the dashboard; it defaults to Settings > Billing.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
return_url | string (uri) | No | HTTPS URL. Up to 2048 characters. |
Response 201
| Field | Type | Description |
|---|---|---|
url | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Start adding a bank account (ACH) or card
POST /v1/billing/setup-intent
Returns a Stripe SetupIntent client secret for Stripe.js (Financial Connections for us_bank_account). Not stored for idempotent replay.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
method | enum | No | One of: us_bank_account, card. Default "us_bank_account". |
Response 201
| Field | Type | Description |
|---|---|---|
client_secret | string | |
method | enum | One of: us_bank_account, card. |
payments_mode | enum | One of: mock, stripe. |
setup_intent_id | string | |
status | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.