---
title: billing
description: Manage contracts, credit balances, invoices, monthly spending, and
  spending settings.
canonical_url: https://orchestor.io/docs/en/cli/billing
markdown_url: https://orchestor.io/docs/en/cli/billing.md
contentType: reference
---

# billing

`orc billing` inspects the organization contract, credit balance, invoices, and monthly spending that apply to a Workspace. Configure JPY spending limits and automatic recharge, quote additional usage credits, and proceed to Stripe checkout.

Log in and verify the target Workspace before execution. Select it with `--workspace`; the contract and billing destination belong to the parent organization billing account. Changes to spending limits and automatic recharge, purchases, and access to the contract management portal require a human organization owner or admin. API keys and service accounts cannot perform these operations.

## Usage

```bash title="terminal"
orc billing current --workspace wks_example
```

*Inspect the target Workspace contract*

```bash title="terminal"
orc billing monthly-spend get --workspace wks_example
```

*Inspect spending this month*

## Reading results

| Operation | Main output |
| --- | --- |
| `current` | `organizationId`, `billingAccountId`, `workspaceId`, `planTier`, `seatCount`, `creditBalance`, `entitlements`, `usage`, subscription state |
| `monthly-spend get` | `currency: JPY`, `used`, `reserved`, `limit`, `periodStart`, `periodEnd`, `timeZone`, `revision` |
| `invoices list` | Invoice IDs, issue timestamps, states, amounts, currencies, and URLs in `invoices` |
| `purchase quote` | JPY credit amount, discount, tax, tax-inclusive total, `calculationId`, and `expiresAt` |

`--json` returns an envelope containing `success`, `data`, and `metadata`. Read field details in `data`. Credit balance, purchase price, and monthly spending have different purposes; do not treat them as the same value.

## Subcommands

### `current`

Returns a snapshot of the organization contract applied to the Workspace. Inspect the plan, seat count, API credit balance, entitlements and usage, Stripe subscription state, cancellation scheduled for period end, and contract period end. `current_period_end` is returned when available; it is not an expiry for each credit bucket.

```bash title="terminal"
orc billing current [options]
```

#### Examples

```bash title="terminal"
orc billing current --workspace wks_example
```

*Inspect contract and balance*

```bash title="terminal"
orc billing current --workspace wks_example --json
```

*Receive the contract snapshot as JSON*

### `invoices list`

Returns the latest 12 invoices for the Workspace parent billing account. Includes invoice ID, issue timestamp, description, payment state, amount, currency, and invoice URL when available. Returns an empty list for an unregistered billing destination.

```bash title="terminal"
orc billing invoices list [options]
```

#### Examples

```bash title="terminal"
orc billing invoices list --workspace wks_example --json
```

*List invoices*

### `portal`

Creates an administrator Stripe contract management session and opens the returned URL in the default browser. Use it to manage the registered billing destination, payment methods, and subscription. Check the outcome of actions in the browser.

```bash title="terminal"
orc billing portal [options]
```

#### Unique options

##### `--no-browser`

Return the billing URL without opening a browser

Type: `boolean`. Optional.

```bash title="terminal"
orc billing portal --no-browser
```

#### Examples

```bash title="terminal"
orc billing portal --workspace wks_example
```

*Open contract management*

### `monthly-spend get`

Returns spending and the spending limit for the current month in `Asia/Tokyo`, in JPY. `used` is posted spending and `reserved` is reserved spending. Both become `null` when pricing cannot be calculated; do not treat them as zero spending. Also returns `periodStart`, `periodEnd`, `revision`, and `canManage` indicating whether settings can be changed.

```bash title="terminal"
orc billing monthly-spend get [options]
```

#### Examples

```bash title="terminal"
orc billing monthly-spend get --workspace wks_example --json
```

*Inspect monthly spending and limit*

### `monthly-spend update`

Save the spending limit with `limit` and the most recently retrieved `revision`. `limit` is an integer in JPY from 0 to 1,000,000,000; `null` means no limit. Do not supply `currency`. This changes settings only and does not purchase credits. Supply all required input; omitted fields do not produce a partial update.

```bash title="terminal"
orc billing monthly-spend update [options]
```

#### Unique options

##### `--revision`

(required) Body field: revision

Type: `number`. Optional.

```bash title="terminal"
orc billing monthly-spend update --revision <value>
```

#### Examples

```bash title="terminal"
orc billing monthly-spend get --workspace wks_example --json
```

*Read settings before changing the limit*

```bash title="terminal"
orc billing monthly-spend update --workspace wks_example --stdin --dry-run < spending-limit.json
```

*Review the limit update request*

```bash title="terminal"
orc billing monthly-spend update --workspace wks_example --stdin < spending-limit.json
```

*Save the limit*

### `auto-recharge get`

Returns automatic recharge `enabled`, JPY `thresholdJpy` and `targetJpy`, `revision`, management permission `canManage`, and saved payment method eligibility `available` and `unavailableReason`. Reading does not charge.

```bash title="terminal"
orc billing auto-recharge get [options]
```

#### Examples

```bash title="terminal"
orc billing auto-recharge get --workspace wks_example --json
```

*Inspect automatic recharge state*

### `auto-recharge update`

Supply `enabled`, `thresholdJpy`, `targetJpy`, and the retrieved `revision`. The threshold is an integer from 0 to 99,999,999 JPY and the target balance from 1 to 99,999,999 JPY; the target must exceed the threshold by at least 50 JPY. Applies to the purchased JPY balance. When balance reaches or falls below the threshold, the setting purchases the shortfall to reach the target. Enabling requires a saved card or Link eligible for automatic payment. Changes require confirmation; pass `--yes` in non-interactive environments.

```bash title="terminal"
orc billing auto-recharge update [options]
```

#### Unique options

##### `--enabled`

(required) Body field: enabled

Type: `string`. Optional.

```bash title="terminal"
orc billing auto-recharge update --enabled <value>
```

##### `--revision`

(required) Body field: revision

Type: `number`. Optional.

```bash title="terminal"
orc billing auto-recharge update --revision <value>
```

##### `--target-jpy`

(required) Body field: targetJpy

Type: `number`. Optional.

```bash title="terminal"
orc billing auto-recharge update --target-jpy <value>
```

##### `--threshold-jpy`

(required) Body field: thresholdJpy

Type: `number`. Optional.

```bash title="terminal"
orc billing auto-recharge update --threshold-jpy <value>
```

#### Examples

```bash title="terminal"
orc billing auto-recharge update --workspace wks_example --stdin --dry-run < auto-recharge.json
```

*Review changes in advance*

```bash title="terminal"
orc billing auto-recharge update --workspace wks_example --stdin < auto-recharge.json
```

*Confirm and save settings*

### `purchase create`

Start Stripe Checkout with `amountJpy`, UUID `attemptId`, and Unix millisecond `attemptAt`. This operation does not take `calculationId`. After CLI confirmation, open checkout, verify the billing destination and final tax-inclusive total in Stripe, and pay. Non-interactive execution requires `--yes`. A successful `url` response means checkout was created, not that payment or a credit grant completed.

```bash title="terminal"
orc billing purchase create [options]
```

#### Unique options

##### `--amount-jpy`

(required) Body field: amountJpy

Type: `number`. Optional.

```bash title="terminal"
orc billing purchase create --amount-jpy <value>
```

##### `--attempt-at`

(required) Body field: attemptAt

Type: `number`. Optional.

```bash title="terminal"
orc billing purchase create --attempt-at <value>
```

##### `--attempt-id`

(required) Body field: attemptId

Type: `string`. Optional.

```bash title="terminal"
orc billing purchase create --attempt-id <value>
```

##### `--no-browser`

Return the billing URL without opening a browser

Type: `boolean`. Optional.

```bash title="terminal"
orc billing purchase create --no-browser
```

#### Examples

```bash title="terminal"
orc billing purchase create --workspace wks_example --stdin --dry-run < purchase-attempt.json
```

*Review the purchase attempt request*

```bash title="terminal"
orc billing purchase create --workspace wks_example --stdin < purchase-attempt.json
```

*Proceed to checkout after confirmation*

Use the same file when retrying. Check payment state before creating a new attempt.

```bash title="terminal"
orc billing purchase create --workspace wks_example --stdin < purchase-attempt.json
```

*Resend the same purchase attempt*

### `purchase quote`

Supply the JPY value of usage credits to purchase as `amountJpy`, an integer from 1 to 99,999,999. Returns `creditAmountJpy`, discount amount and rate, tax, total including tax, Stripe tax calculation ID `calculationId`, and `expiresAt` in Unix seconds. This quotes using the billing destination; it does not purchase or grant credits.

```bash title="terminal"
orc billing purchase quote [options]
```

#### Unique options

##### `--amount-jpy`

(required) Body field: amountJpy

Type: `number`. Optional.

```bash title="terminal"
orc billing purchase quote --amount-jpy <value>
```

#### Examples

```bash title="terminal"
orc billing purchase quote --workspace wks_example --amount-jpy 15000 --json
```

*Quote 15,000 JPY of usage credits*

## Examples

### Monthly spending limit input

`revision` is an example. Replace it with the latest get response for the target Workspace. Set `limit` to `null` for no limit.

```json title="spending-limit.json"
{
  "limit": 10000,
  "revision": 0
}
```

*Monthly spending limit input*

### Automatic recharge settings input

Use the latest revision. Once enabled, the saved payment method is charged when the configured conditions are met.

```json title="auto-recharge.json"
{
  "enabled": true,
  "thresholdJpy": 1000,
  "targetJpy": 5000,
  "revision": 0
}
```

*Automatic recharge settings input*

### Prepare a purchase attempt from a quote

After checking the quote amount, discount, tax, and expiry, create an attempt file once per purchase. Retain that saved file when retrying the same purchase.

```bash title="terminal"
orc billing purchase quote --workspace wks_example --amount-jpy 15000 --json
node --input-type=module -e 'import { randomUUID } from "node:crypto"; console.log(JSON.stringify({ amountJpy: 15000, attemptId: randomUUID(), attemptAt: Date.now() }))' > purchase-attempt.json
```

*Prepare a purchase attempt from a quote*

### Check state after payment

Do not consider a purchase complete just because the browser opened. Check the checkout result and its reflection in the contract and invoices.

```bash title="terminal"
orc billing current --workspace wks_example --json
orc billing invoices list --workspace wks_example --json
```

*Check state after payment*

## Purchase and settings workflow

Before purchasing, check amount and tax with `purchase quote`, and prepare an attempt for the same `amountJpy`. `purchase create` requests confirmation and opens the returned Stripe Checkout URL. Final tax and billing destination review and payment take place in Stripe. The quote `calculationId` identifies a tax calculation; it is not a purchase authorization ID.

`attemptAt` is the creation time in Unix milliseconds. The server rejects attempts older than 23 hours or more than 60 seconds in the future. On communication failure, retain `attemptId` and `attemptAt` when retrying; check payment state first for old attempts.

For spending limits and automatic recharge, pass the `revision` retrieved by get to update. The confirmation-required `purchase create` and `auto-recharge update` operations need [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation) when execution cannot be interactive. `--dry-run` reviews the planned request; it does not guarantee server authorization, billing destination checks, or amount calculation will succeed.

## Permissions

Reads also require authentication and access to the target Workspace. Run `monthly-spend update`, `auto-recharge update`, `purchase create`, and `portal` in a human organization owner or admin session. If permissions are insufficient, ask an organization administrator rather than retrying credentials to bypass the restriction.

## Global Options

The following [global options](https://orchestor.io/docs/cli/global-flags.md) can be used with `orc billing`:

- [`--help`](https://orchestor.io/docs/cli/global-flags.md#help)
- [`--workspace`](https://orchestor.io/docs/cli/global-flags.md#workspace)
- [`--json`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--pretty`](https://orchestor.io/docs/cli/global-flags.md#json-output)
- [`--format`](https://orchestor.io/docs/cli/global-flags.md#output-format)
- [`--field`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--fields`](https://orchestor.io/docs/cli/global-flags.md#field-selection)
- [`--raw`](https://orchestor.io/docs/cli/global-flags.md#raw-output)
- [`--output`](https://orchestor.io/docs/cli/global-flags.md#file-output)
- [`--no-pager`](https://orchestor.io/docs/cli/global-flags.md#pager)
- [`--dry-run`](https://orchestor.io/docs/cli/global-flags.md#dry-run)
- [`--yes`](https://orchestor.io/docs/cli/global-flags.md#confirmation)
- [`--limit`](https://orchestor.io/docs/cli/global-flags.md)
- [`--stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--from-stdin`](https://orchestor.io/docs/cli/global-flags.md#standard-input)
- [`--page-all`](https://orchestor.io/docs/cli/global-flags.md#all-pages)
- [`--timing`](https://orchestor.io/docs/cli/global-flags.md#request-timing)

For details and examples, see [global options](https://orchestor.io/docs/cli/global-flags.md).

## Troubleshooting

### Permission denied

Check the target Workspace and logged-in organization. Billing changes require a human owner/admin session. Expanding API key permissions does not remove this restriction.

### Settings changed elsewhere

For a revision conflict, run get again, inspect current settings, and rebuild the needed change. Do not repeatedly send an old revision.

### Missing billing destination or payment method

Quotes require a billing destination. Enabling automatic recharge also requires a payment method eligible for automatic payment. Check `available` and `unavailableReason` from `auto-recharge get`; an administrator can configure billing information in `billing portal`.

### Unknown purchase or automatic recharge result

Do not treat Checkout URL creation as payment completion. Check Stripe, `current`, and invoices. Retain the attempt while retrying the same purchase. If an incomplete previous automatic charge prevents settings changes, follow the displayed guidance instead of changing amounts to bypass it.

### Monthly spending is `null`

Pricing cannot be calculated. Do not replace `used` and `reserved` with zero; check the pricing state. When handling API or network failures in scripts, use exit codes rather than stderr wording.

## Related

- [Authentication](https://orchestor.io/docs/cli/auth.md)
- [Workspace](https://orchestor.io/docs/cli/workspace.md)
- [Organizations](https://orchestor.io/docs/cli/organization.md)
- [Global options](https://orchestor.io/docs/cli/global-flags.md)

---

[Documentation index](https://orchestor.io/docs/llms.txt)