FurniOpsDocs
API referenceBilling

Buy FurniOps AI credit

Starts a purchase of the amount, in the billing currency and whole units, as a one-off invoice with tax, and answers the payment the browser confirms with Stripe's Payment Element; then poll getCreditPurchase. Credit is added only once Stripe reports the invoice paid, and expires 12 months later. The same Idempotency-Key answers the same purchase. Owner only, on a paid plan with Ask AI (403 feature_unavailable): refused while a renewal is past due, a payment is disputed or the organisation is being deleted (409), in a currency credit is not sold in (422 currency_unsupported), or outside the amounts and balance limit getCreditBalance states (422). While billing is switched off, it answers 409 conflict.

POST/v1/billing/credits/purchases

Starts a purchase of the amount, in the billing currency and whole units, as a one-off invoice with tax, and answers the payment the browser confirms with Stripe's Payment Element; then poll getCreditPurchase. Credit is added only once Stripe reports the invoice paid, and expires 12 months later. The same Idempotency-Key answers the same purchase. Owner only, on a paid plan with Ask AI (403 feature_unavailable): refused while a renewal is past due, a payment is disputed or the organisation is being deleted (409), in a currency credit is not sold in (422 currency_unsupported), or outside the amounts and balance limit getCreditBalance states (422). While billing is switched off, it answers 409 conflict.

Authorization

apiKey
AuthorizationBearer <token>

An API key (fo_live_… / fo_test_…) as a bearer token

In: header

Header Parameters

FurniOps-Version?string

Dated API version; pinned per organisation on first use and overridable per request

Value in

  • "2026-10-01"
  • "2026-10-04"
FurniOps-Mode?string

The data the request acts on: test is the organisation's sandbox. An OAuth token picks it (live by default); an API key's mode is fixed, and naming the other one is refused

Value in

  • "live"
  • "test"
Idempotency-Key*string

Unique key for this operation, reused on retries (24 h)

Length1 <= length <= 257
FurniOps-Dry-Run?string

This operation cannot be previewed (Stripe invoices at once; price it with previewCreditPurchase): 422 preview_unsupported, nothing changes

Value in

  • "true"
  • "explain"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Credit to buy

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/v1/billing/credits/purchases" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "amount": {      "amount": 1,      "currency": "usd"    }  }'
{  "object": "credit_purchase",  "id": "string",  "kind": "manual",  "status": "requires_payment",  "amount": {    "amount": -9007199254740991,    "currency": "usd"  },  "tax": {    "amount": -9007199254740991,    "currency": "usd"  },  "total": {    "amount": -9007199254740991,    "currency": "usd"  },  "credit_micros": 1,  "confirmation": {    "object": "billing_confirmation",    "kind": "payment",    "client_secret": "string",    "subscription": {      "status": "incomplete",      "plan": "string",      "current_period_end": "2019-08-24T14:15:22Z",      "cancel_at_period_end": true,      "interval": "month",      "cancel_at": "2019-08-24T14:15:22Z",      "discount": {        "name": "string",        "percent_off": 1,        "amount_off": 0,        "ends_at": "2019-08-24T14:15:22Z"      },      "scheduled_change": {        "plan": "string",        "interval": "month",        "effective_at": "2019-08-24T14:15:22Z"      }    }  },  "invoice": {    "id": "string",    "number": "string",    "hosted_invoice_url": "http://example.com",    "invoice_pdf": "http://example.com"  },  "refunded": {    "amount": -9007199254740991,    "currency": "usd"  },  "created_at": "2019-08-24T14:15:22Z",  "paid_at": "2019-08-24T14:15:22Z",  "expires_at": "2019-08-24T14:15:22Z"}

Cancel at the period's end POST

The subscription ends when the fee's term does (the year, for an annual plan); the plan stays until then and returns to the free plan after, leaving live mode. Resume it any time before. While billing is switched off, it answers 409 `conflict`. Without a subscription, 409.

Read billing GET

The organisation's plan, subscription and card, and the plans on sale with their prices. `enabled` is false until selling starts.