Create an order and pay from account balance

Choose the ordering and payment workflow

The atomic deploy endpoint always attempts payment of the full final order amount from account balance; it never silently creates an unpaid order or uses a card/top-up. Insufficient credit returns HTTP 402 with error.code=insufficient_credit, without a committed new order, invoice or debit. The final tax/setup/add-on-inclusive amount must satisfy max_total. Both billing.order.create and billing.invoice.pay permissions are required.

A separate invoice payment may be partial if wallet funds are insufficient; read its remaining amount. That behavior is different from atomic deploy's all-or-nothing payment. A successful payment does not mean the guest or provider is ready.

Use one stable Idempotency-Key per intended write. Same key and exact request is a retry; a different request with that key is rejected. Separate order and payment requests need separate keys. CLI write keys are optional: an omitted key is generated, saved and printed before dispatch. Preserve it for retries. SDKs never automatically retry writes.

After a timeout or unknown response, inspect the original order, invoice, service or returned operation URL before retrying. Reuse the original key and exact payload; never create a new identity simply because a response was lost. Inspect fullyPaid/paidNow and the invoice status to confirm payment. Poll the operation until succeeded and check service readiness to confirm provisioning; accepted, pending or unknown does not confirm completion. A later provisioning failure must be handled separately from payment; inspect billing state rather than assuming an automatic refund.

Use bf billing order-preview/order-create and bf billing invoice-pay for the separate workflow. Use bf deploy or bf billing deploy for atomic deployment; bf dedicated deploy creates an unpaid order unless its explicit payment option is supplied.

Review the product and price before creating a draft, then inspect its invoice before paying.

Find a product and its configuration

In your AI assistant, ask for the product, location, operating system, quantity and billing period you want. The assistant uses the product catalog and order-options tool to find eligible configurations.

Using the CLI:

bf billing products --query 1G
bf billing order-options PRODUCT_UUID VARIANT_UUID
bf billing order-preview PRODUCT_UUID VARIANT_UUID --currency EUR --unit MONTH --count 1

Replace IDs with the catalog results. Use the exact returned location and OS codes. Eligible options do not reserve stock or guarantee capacity.

Create the unpaid order

Put your chosen configuration in order.json:

{
  "currency": "EUR",
  "items": [{
    "productId": "PRODUCT_UUID",
    "variantId": "VARIANT_UUID",
    "qty": 1,
    "billing": {"unit": "MONTH", "count": 1},
    "userConfig": {
      "hostname": "myserver",
      "location": "LOCATION_CODE",
      "os": {"code": "OS_CODE"}
    }
  }]
}

This VPS example uses placeholders, not universal configuration codes. Other products can require different fields; read their options or use the dashboard if API ordering is unsupported.

bf billing order-create --file order.json --request-key order-myserver-001
bf billing invoices

The response identifies the order and invoice. Check the resulting total and currency. The CLI uses current server-side pricing; the earlier preview is not a price lock.

Pay the invoice

Read your balance and the invoice's outstanding amount. When you decide to pay that invoice:

bf billing balance
bf billing invoice-pay INVOICE_UUID --request-key pay-myserver-001
bf billing invoices

This uses existing account balance, not a card. If balance is insufficient, a partial payment may leave the invoice unpaid. Check the returned payment result and remaining amount.

In ChatGPT, make an explicit request such as “Pay invoice INV-... from my account balance.” The selected AI policy determines whether dashboard approval is needed.

Track provisioning

Payment can start provisioning. List services and inspect the service's status. Dedicated deployment tasks have their own progress endpoints. A paid invoice does not prove installation is complete.

Retry an uncertain request

Keep the same request key and payload for the same action. Use different keys for order creation and payment. If a request times out, read the order or invoice before retrying; never create a new key just because the response was lost. SDKs do not automatically retry writes. Server deduplication has a finite retention window.

The API permissions are billing.products.read for discovery, billing.order.create for ordering, billing.invoice.pay for payment, and the relevant invoice/balance read permissions.