# Create an order and pay from account balance



Source: https://docs.blazingfast.io/howto/api/order-and-pay-from-balance



Discover valid locations and OS choices, review the price, create an unpaid order and pay separately.



## Choose the ordering and payment workflow

| Workflow | Use when | Payment |
| --- | --- | --- |
| Separate order and invoice | You need invoice review, a mixed cart, or separate payment approval | Quote → create an unpaid draft → inspect the invoice → explicitly pay → track provisioning |
| Atomic deployment | You authorize one discovered regional product and payment of the full final order amount from account balance together | Quote optionally → POST /v1/deploy/{region}/{productCode}/{variantCode} → payment of the full final order amount from account balance and queued provisioning |

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:

```bash
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`:

```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.

```bash
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:

```bash
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.