# Spending budgets

> Cap monthly credit spending for a project, customer or Number, and choose which Numbers stay funded first.

A spending budget caps the credits a project, customer or Number can be charged
in a calendar month. Funding priority decides which Numbers keep running first
when credit is short. Together they keep one project or customer from using
the whole team balance.

## Before you begin

- The team must be on Pay-As-You-Go. Owners and admins on Free can read these
  controls but not change them.
- You need the owner or admin role on the team.
- Through the API, use a team key with `billing:read` to read and
  `billing:manage` to change. Project tokens and client tokens cannot access
  them.

## How limits work

- Limits are in credits and reset at 00:00 UTC on the first day of each month.
- A Number must fit its own limit, its customer's and its project's. A
  customer's Numbers share its limit.
- Charged Number service and active pairing reservations count toward a limit.
  A reservation counts until it is used, released or expires.
- A charge that would exceed any limit is refused. Service already paid runs
  until its window ends.
- An empty limit removes the cap. Zero blocks new charges.

Limits cover Polymorfa credits charged for Number service. They exclude credit
purchases, refunds, unbilled usage and charges Meta bills to you directly.

## Set a limit

**Console:**

- **Project**: open **Usage** with **All projects** selected, find the project
  in **Funding controls** and select **Edit limit**. Or select a project and
  edit its limit above its table. **Remove limit** removes it.
- **Number**: open the Number in **Numbers** and select **Edit limits and
  priority**, or select **Budget** in its row menu. You can also set starting
  values when you create a real Number.
- **Customer**: open the customer, open the **Limits and priority** tab and
  select **Edit limits and priority**.

Enter the monthly limit and select **Save changes**.

**API:**

Read one resource's controls, then save them with the revisions from that
read:

```bash cURL
curl "https://api.polymorfa.com/platform/billing/controls/customer/$CUSTOMER_ID" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"
```

```typescript TypeScript
const controls = await platform.raw.request({
  method: "GET",
  path: `/platform/billing/controls/customer/${customerId}`,
});
console.log(controls.data);
```

Send `expectedBudgetRevision` and `expectedPriorityRevision` from the read to
[Set resource billing controls](https://docs.polymorfa.com/api/billing/set-resource-billing-controls)
(`PUT` on the same path), with `limitCredits` and `priority`. `limitCredits:
null` removes a limit; `0` blocks new charges. The scope is `project`,
`customer` or `number`. See also
[Get billing limits](https://docs.polymorfa.com/api/billing/get-billing-limits).

*TypeScript:*

The SDK has no typed billing-control methods yet, so send these requests with
the team client's `raw.request`. Project tokens and client tokens cannot make
them. Reads need `billing:read`, and saves need `billing:manage` on a
Pay-As-You-Go team.

If another person or request changed the setting since you read it, the save
is refused. Reload and try again. A Number or customer saves its limit and
priority together: a conflict leaves both unchanged.

Raising or removing a limit lets Polymorfa reconsider suspended Numbers; the
team still needs enough credit.

## Set funding priority

When credit is short, higher priority is funded first: it protects the next
renewal before lower-priority spending, including new pairings. Priority never
shortens a window already paid.

- Project priority comes first.
- Within a project, Numbers inherit their customer's priority. A higher Number
  priority overrides it.
- Number priority then breaks ties, before renewal time.
- Higher values mean higher priority.

**Console:**

1. Open **Usage**. With **All projects** selected, **Funding controls** ranks
   projects. With a project selected, it ranks that project's customers and
   Numbers together.
2. Choose **Funding order**, then drag rows into highest-first order, or enter
   a rank and press **Enter**.
3. Select **Save order**.

Search, filters and sorting keep the complete order, including rows outside
the visible page. **Reset view** clears them without discarding your changes.

**API:**

Read the current order with
[Get billing priorities](https://docs.polymorfa.com/api/billing/get-billing-priorities); add
`projectId` for one project's customers and Numbers.

To reorder a project's customers and Numbers, send `scope: "resource"`,
`projectId`, `expectedRevision` and a complete highest-first `resources` array
to [Reorder billing priorities](https://docs.polymorfa.com/api/billing/reorder-billing-priorities).
Each entry is `{ "scope": "customer" | "number", "resourceId": "UUID" }`. An
incomplete, duplicate, foreign or stale list is refused with no partial change.

To reorder projects, send `scope: "project"` and every project ID, highest
first, with the revision from the read:

```bash cURL
curl "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY"

curl -X PUT "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer $POLYMORFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "resourceIds": ["PROJECT_ID_1", "PROJECT_ID_2"],
    "expectedRevision": 5
  }'
```

```typescript TypeScript
const response = await platform.raw.request<{
  data: { revision: number; projects: Array<{ id: string }> };
}>({ method: "GET", path: "/platform/billing/priorities" });

await platform.raw.request({
  method: "PUT",
  path: "/platform/billing/priorities",
  body: {
    scope: "project",
    // Highest priority first. Reorder these IDs to change who funds first.
    resourceIds: response.data.data.projects.map(project => project.id),
    expectedRevision: response.data.data.revision,
  },
});
```

A conflict means the order changed: read it again before choosing a new order.

*TypeScript:*

The SDK has no typed priority methods yet; use the team client's
`raw.request`.

Forecast top-ups and balance warnings use the same priorities.

## Check progress

- Team and project overview cards show spent plus reserved credits against the
  limit. A warning appears at 80% and a reached state at the limit.
- **Usage** shows credits charged, the limit, reserved credits and what remains,
  for the current UTC month. An unset limit shows **No limit**.

## See also

- [Usage](https://docs.polymorfa.com/billing/usage)
- [Buy credits](https://docs.polymorfa.com/billing/credits)
- [Group Numbers by customer](https://docs.polymorfa.com/customers)
