> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/llms.txt

# Pay and set a spending limit

Add a card and set a monthly spending limit, so that your organization's work runs and its bill stays under an amount you choose.

**You will have:** a card on file and a spending limit, shown by `yard org card your-org` and `yard org limit your-org`.
**Works with:** the board (billing page) and `yard` for a signed-in person. The card is entered on Stripe's page, and the limit is changed on the billing page, both in a browser. No key, agent or MCP tool can change billing.
**Takes:** about 5 minutes.

This page is about the hosted Switchyard at app.switchyard.so. The [pricing page](/pricing) has the rates. What an agent sees at the limit is on the [working as an agent](/docs/agents) page.

## Before you start

- You are an owner, admin or billing member of the organization.
- You are signed in to [app.switchyard.so](https://app.switchyard.so) in a browser. Changing the limit needs a browser sign-in from the last 15 minutes.

## Step 1 — Add a card

Add a card so that Switchyard can charge your organization's statements. Open the billing page and add the card there, or print the page's link from the terminal:

```sh
yard org card add your-org
```

`yard` prints the link to Stripe's page. When hosted Switchyard does not require a card, Stripe checks the card and charges nothing:

```
Output
add or change your-org's card on Stripe's page: <link> (nothing is charged there; the card is checked and kept for the month's bill)
```

When hosted Switchyard requires a card ([when a card is required](#when-a-card-is-required)), the first card pays the plan's minimum for the rest of the month:

```
Output
add your-org's card and pay the launch plan's $<amount> minimum for <month> on Stripe's page: <link> (it counts toward the month's usage, and the card is kept for the month's statement)
```

Enter the card on Stripe's page. Switchyard never receives the card number. Stripe's page shows prices in US dollars.

Billing starts on the day the organization's first card is added. The plan's minimum for that first month is pro-rated from that day.

You have a card on file. Next, you set the limit.

## Step 2 — Set the spending limit

Set a monthly spending limit and a warning amount on the billing page. `yard org limit set` prints the link to that page with the amount filled in:

```sh
yard org limit set your-org 500
```

```
Output
confirm it on the billing page, signed in in a browser: https://app.switchyard.so/billing?org=your-org&limit=500#limit
```

Open the link and confirm the change. Use `none` in place of the amount to remove the limit. `yard` refuses the command when an agent or a script runs it.

The limit is set. The billing contacts get an email at 80% and at 100% of the limit.

## Verify

Run `yard org card your-org` to see the card and where payments stand. Run `yard org limit your-org` to see the limit, what is spent of it, the warnings sent and the forecast.

## What you pay

Each organization is on a plan: Launch ($20 a month minimum), Scale ($200 a month minimum) or Enterprise (by contract). The minimum is the least that a month costs. Four meters measure all usage, at the rates on the [pricing page](/pricing). The usage counts against the minimum, and a month costs the larger of the two:

- **check minutes**: each second that a check command runs, on a small or a large machine;
- **engine time**: each second that a project's Git engine runs; 50 hours a month are included on Launch and 500 on Scale;
- **AI suggestions**: each suggested merge of a conflicted file written on Switchyard's key, for organizations that turn AI fixes on;
- **repository storage**: the gigabyte-months that your projects' Git data takes, measured once a day.

Agents, tasks, merges and people are not metered. A check run that joins a pass already made on the same code costs nothing. Checks on your own CI cost nothing here. A GitHub Actions job with `runs-on: switchyard` runs on Switchyard's machines and is billed as check time.

Prices are in US dollars.

## The billing page

Each organization has a billing page in the app for its owners, admins and billing members. It shows this month's usage by meter and by project, the forecast, the statements and their invoices, the card, the warning amount, the spending limit and who gets the billing emails.

The terminal reads the same: `yard org billing`, `yard org usage`, `yard org limit`, `yard org card` and `yard org invoices`. `yard org billing your-org --csv` lists every check run of the month, billed or not. `yard org billing contacts your-org` lists who gets the billing emails; with `--add <email>` or `--remove <email>` it prints the billing page, where a person changes the other addresses in a browser signed in within 15 minutes. The routes are under `/api/orgs/<org>/` on the [REST API](/docs/api) page. Agents never read money amounts: when an agent or a script runs these commands, yard says so with each request and Switchyard refuses them, saying a person reads billing on the billing page. That is yard's own word, so it holds for agents that run yard as it is. An agent reads only the percent of the limit used, with `yard_spending_limit` over MCP or `GET /v1/projects/<project>/spending-limit`.

## Statements and charges

Switchyard makes a statement for each month on the 4th of the next month. A person at Switchyard reviews each month's statement before it is charged.

Switchyard also makes a statement during the month when the usage not yet charged passes the charge threshold. The billing page shows the threshold under "next charge", and `yard org card your-org` prints it.

- When hosted Switchyard requires a card, an organization that pays by card is charged at the threshold with no review. The threshold is $50 until the organization has paid 3 statements, and $100 after that.
- When hosted Switchyard does not require a card, the threshold is $100, and a person at Switchyard reviews the statement before it is charged.
- An organization on invoice terms always has the $100 threshold and the review.

Switchyard charges each statement to the card on file and emails the invoice to the billing contacts. An organization on invoice terms gets each statement as a Stripe invoice instead ([invoice terms](#invoice-terms)).

You add a card through Stripe Checkout, on Stripe's own page. Switchyard never sees the card number. The billing page tells you whether adding the card pays the plan's minimum:

- If it does, Stripe charges the minimum for the rest of the month and keeps the card for later charges. This payment counts toward the month's usage, so the month's statement charges only the usage above it.
- If it does not, Stripe only checks the card. Nothing is charged at that moment.

## At the spending limit

At the limit, new work is **held, not lost**. Switchyard takes a push or a submit and keeps it. Held work is tested and merged when a person raises the limit.

The hold lasts 24 hours from the moment the limit was reached, or until $2 of engine time has run while held, whichever comes first. After that, Switchyard refuses new work before it takes anything:

- `yard` exits with status 6 and the error code `spending_limit`.
- An MCP tool answers with an error.
- The work stays in the agent's checkout.

A task that is already held keeps its place and merges when the limit is raised.

To raise the limit, a person opens the billing page in a browser, or the link in the warning email, and chooses one of: **+$100**, **+$500**, **remove the limit**, or **allow for 24 hours**. The email's link opens the billing page, where the person confirms. No agent or key can raise the limit. The MCP tool `yard_spending_limit` only reads how much of the limit is used and who can raise it.

## When a payment fails

When a charge fails, Stripe tries the card again, and the organization has 3 days to pay. `yard org card your-org` and the billing page say when the hold starts. After 3 days, new work is held as at the spending limit, and then refused 24 hours later. Paying, or updating the card, ends the hold at once. Switchyard deletes nothing for a failed payment.

## When a card is required

The hosted Switchyard can require a card on file before new work runs on its machines. The billing contacts get an email before the requirement starts. Without a card, Switchyard refuses new work before it takes anything:

- `yard` exits with status 10 and the error code `card_required`.
- An MCP tool answers with an error that says an owner, admin or billing member can add a card.

An organization made before the requirement started is held for 24 hours or $2 of engine time first, then refused. Held work goes on when a card is added.

While a card is required, the first card pays the minimum of the plan you choose, Launch or Scale, for the rest of the month. The set-up page asks for it in its **card and plan** step, and `yard org card add your-org --plan scale` chooses it from the terminal. The board shows an **add a card** link while a card is needed. The payment counts toward the month's usage. An organization on invoice terms never needs a card.

When hosted Switchyard does not require a card, no work waits for one, and adding a card charges nothing at that moment.

## Invoice terms

An Enterprise organization, or a Launch or Scale organization that Switchyard gave invoice terms, pays by invoice. Each statement becomes a Stripe invoice, payable within the terms (30 days unless agreed otherwise), sent to the billing address you name. A person at Switchyard reviews each statement before it is sent. The organization never needs a card. To ask for invoice terms, write to [support@switchyard.so](/contact?topic=billing).

## Engine time and machine size

A project's Git engine runs while agents push, fetch and merge, and stops when idle. Engine time is billed by the second while the engine runs. A repository of 4 GiB or more starts on a larger engine, billed at the large rate. A smaller repository is billed at the small rate.

Under load, for example many agents that clone or push at once, an engine moves to a larger machine at its next start. The engine is billed at that size until it has been calm for 30 minutes, and then the billing goes back. An owner or admin can keep engines small: `yard org engine-sizing your-org small`. Letting engines grow again (`grows`) needs a browser sign-in from the last 15 minutes.

A project also runs extra Git engines for clones and reads while its clones and fetches wait. It adds one more a minute while they wait: on the project's own engine, or more than 5 seconds on an extra engine. Pushes never add one. There are at most 2 for a repository under 1 GB, 4 under 2 GB and 8 from 2 GB. After each 30 minutes in which no extra engine was used, it stops one. An extra engine counts as used when it was about a third busy over those 30 minutes, or a clone waited more than 5 seconds on it. A project with 50 or more open tasks keeps one while it is in use, and a project with no calls for 10 minutes runs none. Each extra engine is billed as engine time, by the second at its size, from its first call. When engines are kept small, a project runs no extra engines. The billing page says how many of a project's engine hours ran on extra engines.

When a project's Git engines run as a pool, each engine of the pool is billed like any engine, by the second at its size. The billing page says how many of the project's engine hours ran on the pool, and on how many engines. The runs CSV says it for each day.

The included engine hours are used in the order of the days. The first hours of a month are included and the last hours are billed.

A history copy that a storage move stopped part of the way keeps what it copied, and the engine time of that part is billed.

## Leaving

Deleting an organization makes its final statement at once: the usage so far, with the plan's minimum pro-rated to that day, less what was already charged. The final statement is reviewed and charged like any other. The receipt goes to the billing contacts. An organization whose billing never started owes nothing.

## Who can do what

| Act | Who |
| --- | --- |
| Read usage, the bill and the statements | owners, admins and billing members |
| Set, raise or remove the spending limit | owners, admins and billing members, signed in in a browser in the last 15 minutes |
| Add or change the card | owners, admins and billing members; the card is entered on Stripe's page |
| Choose the billing contacts | owners, admins and billing members, on the billing page |
| Turn AI suggestions on Switchyard's key on or off | owners and admins, signed in in a browser in the last 15 minutes |
| Keep engines small | owners and admins |
| Let engines grow under load | owners and admins, signed in in a browser in the last 15 minutes |
| Delete the organization | owners |

To ask about a bill, before or after the charge, write to [support@switchyard.so](/contact?topic=billing).

## Next

- [Manage teams, roles and keys](/docs/keys-and-teams): give someone the billing role.
- [Limits](/docs/limits): check machines per plan and repository size by plan.
