Skip to content
Shortcut: /, ⌘K or Ctrl+K

Billing

View as Markdown

The billing priorities object

Attributes

  • revisionintegerrequiredrange0–2147483646

    Specifies revision for this management billing priority.

  • projectsarray of objectrequired

    Projects associated with this management billing priority.

    Show 3 child fields
  • customersarray of objectrequired

    Customers associated with this management billing priority.

    Show 4 child fields
  • numbersarray of objectrequired

    Numbers associated with this management billing priority.

    Show 4 child fields
The billing priorities object
{
  "revision": 0,
  "projects": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "priority": 0
    }
  ],
  "customers": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "priority": 0
    }
  ],
  "numbers": [
    {
      "id": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "priority": 0
    }
  ]
}

List usage meters

GET/platform/billing/usagePlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Public Management API. Team keys require billing:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/billing/usagecURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

List billing transactions

GET/platform/billing/transactionsPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Public Management API. Team keys require billing:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/billing/transactionscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/transactions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

List tier pricing

GET/platform/billing/pricingPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Public Management API. Team keys require billing:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/billing/pricingcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/pricing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

Get billing

GET/platform/billingPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Public Management API. Team keys require billing:read. Project tokens are not accepted.

Responses

  • 200Success
    • dataanyrequired

      Operation result.

    Show 3 headers
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
GET /platform/billingcURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": null
}

Get resource billing controls

GET/platform/billing/controls/{scope}/{resourceId}Platform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Reads one project, customer or real number without loading the team directory. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:read. Project tokens are not accepted.

Path parameters

  • scopestringrequired

    Specifies scope for this path parameter.

    Allowed valuesprojectcustomernumber
  • resourceIdstring (uuid)required

    Identifier of the resource affected by this event.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
GET /platform/billing/controls/{scope}/{resourceId}cURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/controls/<scope>/<resourceId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "budget": {
      "scope": "project",
      "resourceId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "limitCredits": 0,
      "spentCredits": 0,
      "reservedCredits": 0,
      "revision": 0
    },
    "priority": 0,
    "priorityRevision": 0
  }
}

Get billing limits

GET/platform/billing/limitsPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Reads attributed charges and active reservations in Polymorfa credits. Months reset at 00:00 UTC on the first day. Omit projectId for project limits across the team; pass it to include that project's customer and number limits. Pass scope=project to read only project limits. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:read. Project tokens are not accepted.

Query parameters

  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

  • scopestring

    Specifies scope for this query parameter.

    Allowed valuesproject

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 7 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
GET /platform/billing/limitscURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/limits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "checkedAt": "2026-09-22T12:00:00Z",
    "periodStart": "2026-09-22T12:00:00Z",
    "periodEnd": "2026-09-22T12:00:00Z",
    "todayCredits": 0,
    "monthCredits": 0,
    "daily": [
      {
        "date": "2026-09-22",
        "credits": 0
      }
    ],
    "budgets": [
      {
        "scope": "project",
        "resourceId": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "limitCredits": 0,
        "spentCredits": 0,
        "reservedCredits": 0,
        "revision": 0
      }
    ]
  }
}

Get billing priorities

GET/platform/billing/prioritiesPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:read

Lists active projects, customers and real numbers. Pass scope=project to read only project ranks. Pass projectId to read one project and its customer/number leaderboard. Project priority takes precedence. Within a project, numbers inherit their customer priority; a higher number priority overrides it. Number priority then breaks ties before renewal due time and stable number identity. Numbers are ranked within a project. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:read. Project tokens are not accepted.

Query parameters

  • scopestring

    Specifies scope for this query parameter.

    Allowed valuesproject
  • projectIdstring (uuid)

    Identifier of the Polymorfa project that owns this resource.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
GET /platform/billing/prioritiescURL
Not available with the Test key. Use a team key or project token.
curl "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22"
Response
{
  "data": {
    "revision": 0,
    "projects": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "customers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "numbers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ]
  }
}

Set resource billing controls

PUT/platform/billing/controls/{scope}/{resourceId}Platform API
Base URL
https://api.polymorfa.com
Required permission
billing:manage

Saves the monthly limit and priority together, atomically. Both observed revisions are required. Conflicts leave both settings unchanged. Null removes a limit; zero blocks new charges. Existing paid service continues. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:manage. Project tokens are not accepted.

Path parameters

  • scopestringrequired

    Specifies scope for this path parameter.

    Allowed valuesprojectcustomernumber
  • resourceIdstring (uuid)required

    Identifier of the resource affected by this event.

Body

  • limitCreditsnumberrequirednullablerange0–1000000multiple of0.000001

    Specifies limit credits for this schema.

  • priorityintegerrequiredrange0–1000000

    Specifies priority for this schema.

  • expectedBudgetRevisionintegerrequiredrange0–2147483646

    Specifies expected budget revision for this schema.

  • expectedPriorityRevisionintegerrequiredrange0–2147483646

    Specifies expected priority revision for this schema.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 3 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
PUT /platform/billing/controls/{scope}/{resourceId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/billing/controls/<scope>/<resourceId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "limitCredits": 0,
  "priority": 0,
  "expectedBudgetRevision": 0,
  "expectedPriorityRevision": 0
}'
Response
{
  "data": {
    "budget": {
      "scope": "project",
      "resourceId": "00000000-0000-4000-8000-000000000000",
      "projectId": "00000000-0000-4000-8000-000000000000",
      "name": "string",
      "limitCredits": 0,
      "spentCredits": 0,
      "reservedCredits": 0,
      "revision": 0
    },
    "priority": 0,
    "priorityRevision": 0
  }
}

Set billing limit

PUT/platform/billing/limits/{scope}/{resourceId}Platform API
Base URL
https://api.polymorfa.com
Required permission
billing:manage

Zero blocks new charges; null removes the limit. Existing paid service continues to its paid-window end. Reservations count toward admission. Supply the revision from the limit read; a stale revision returns 409. Retrying the same successful update is harmless. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:manage. Project tokens are not accepted.

Path parameters

  • scopestringrequired

    Specifies scope for this path parameter.

    Allowed valuesprojectcustomernumber
  • resourceIdstring (uuid)required

    Identifier of the resource affected by this event.

Body

  • limitCreditsnumberrequirednullablerange0–1000000multiple of0.000001

    Specifies limit credits for this schema.

  • expectedRevisionintegerrequiredrange0–2147483646

    Specifies expected revision for this schema.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 1 child field
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
PUT /platform/billing/limits/{scope}/{resourceId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/billing/limits/<scope>/<resourceId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "limitCredits": 0,
  "expectedRevision": 0
}'
Response
{
  "data": {
    "saved": true
  }
}

Reorder billing priorities

PUT/platform/billing/prioritiesPlatform API
Base URL
https://api.polymorfa.com
Required permission
billing:manage

resourceIds is the complete list in highest-first order. Project order includes every active project; customer and number orders include every active customer or real number in projectId. Use scope=resource with projectId and a complete resources array of {scope: customer or number, resourceId} for one mixed leaderboard. Saves the whole order atomically. Concurrent changes or an incomplete list return 409. Retrying the same successful order is harmless. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:manage. Project tokens are not accepted.

Body

One of
  • scopestringrequired

    Specifies scope for this one of.

    Allowed valuesresource
  • projectIdstring (uuid)required

    Identifier of the Polymorfa project that owns this resource.

  • resourcesarray of objectrequiredmax items1000000unique items

    Resources associated with this one of.

    Show 2 child fields
  • expectedRevisionintegerrequiredrange0–2147483646

    Specifies expected revision for this one of.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
PUT /platform/billing/prioritiescURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "scope": "resource",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "resources": [
    {
      "scope": "customer",
      "resourceId": "00000000-0000-4000-8000-000000000000"
    }
  ],
  "expectedRevision": 0
}'
Response
{
  "data": {
    "revision": 0,
    "projects": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "customers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "numbers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ]
  }
}

Set billing priority

PUT/platform/billing/priorities/{scope}/{resourceId}Platform API
Base URL
https://api.polymorfa.com
Required permission
billing:manage

Changes future funding protection and recovery order without shortening paid service. Supply the team-wide revision from the priorities read. A stale revision returns 409. Requires a team key with the stated billing scope, or a signed-in team owner or admin. Project and client credentials cannot access these controls. Billing must be configured. Writes require Pay-As-You-Go. These controls never enable charging of unpriced usage.

Team keys require billing:manage. Project tokens are not accepted.

Path parameters

  • scopestringrequired

    Specifies scope for this path parameter.

    Allowed valuesprojectcustomernumber
  • resourceIdstring (uuid)required

    Identifier of the resource affected by this event.

Body

  • priorityintegerrequiredrange0–1000000

    Specifies priority for this schema.

  • expectedRevisionintegerrequiredrange0–2147483646

    Specifies expected revision for this schema.

Responses

  • 200Success
    • dataobjectrequired

      Structured data carried by this object.

      Show 4 child fields
    Show 3 headers
  • 400A path, query, or request-body value did not pass validation.
  • 401Missing/invalid credential for this audience.
  • 403Authenticated but lacks the required scope/role/audience.
  • 404The requested resource was not found inside the authenticated team or project scope.
  • 409The request conflicts with the resource's current state.
  • 503The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
PUT /platform/billing/priorities/{scope}/{resourceId}cURL
Not available with the Test key. Use a team key or project token.
curl -X PUT "https://api.polymorfa.com/platform/billing/priorities/<scope>/<resourceId>" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "priority": 0,
  "expectedRevision": 0
}'
Response
{
  "data": {
    "revision": 0,
    "projects": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "customers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ],
    "numbers": [
      {
        "id": "00000000-0000-4000-8000-000000000000",
        "projectId": "00000000-0000-4000-8000-000000000000",
        "name": "string",
        "priority": 0
      }
    ]
  }
}