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:readto read andbilling:manageto 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:
curl "https://api.polymorfa.com/platform/billing/controls/customer/$CUSTOMER_ID" \
-H "Authorization: Bearer $POLYMORFA_API_KEY"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 (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.
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
- Open Usage. With All projects selected, Funding controls ranks projects. With a project selected, it ranks that project's customers and Numbers together.
- Choose Funding order, then drag rows into highest-first order, or enter a rank and press Enter.
- 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; 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. 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:
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
}'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.