# Billing

## Endpoints

- `GET /platform/billing/usage`: [List usage meters](https://docs.polymorfa.com/api/billing/list-usage-meters)
- `GET /platform/billing/transactions`: [List billing transactions](https://docs.polymorfa.com/api/billing/list-billing-transactions)
- `GET /platform/billing/pricing`: [List tier pricing](https://docs.polymorfa.com/api/billing/list-tier-pricing)
- `GET /platform/billing`: [Get billing](https://docs.polymorfa.com/api/billing/get-billing)
- `GET /platform/billing/controls/{scope}/{resourceId}`: [Get resource billing controls](https://docs.polymorfa.com/api/billing/get-resource-billing-controls)
- `GET /platform/billing/limits`: [Get billing limits](https://docs.polymorfa.com/api/billing/get-billing-limits)
- `GET /platform/billing/priorities`: [Get billing priorities](https://docs.polymorfa.com/api/billing/get-billing-priorities)
- `PUT /platform/billing/controls/{scope}/{resourceId}`: [Set resource billing controls](https://docs.polymorfa.com/api/billing/set-resource-billing-controls)
- `PUT /platform/billing/limits/{scope}/{resourceId}`: [Set billing limit](https://docs.polymorfa.com/api/billing/set-billing-limit)
- `PUT /platform/billing/priorities`: [Reorder billing priorities](https://docs.polymorfa.com/api/billing/reorder-billing-priorities)
- `PUT /platform/billing/priorities/{scope}/{resourceId}`: [Set billing priority](https://docs.polymorfa.com/api/billing/set-billing-priority)

## The billing priorities object

### Attributes

- `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing priority.
- `projects` (array of object, required). Projects associated with this management billing priority.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this project.
- `customers` (array of object, required). Customers associated with this management billing priority.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this customer.
- `numbers` (array of object, required). Numbers associated with this management billing priority.
  - `id` (string (uuid), required, format uuid). Identifier for this resource.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `name` (string, required). Human-readable name for this resource.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this number.
```json
{
  "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 https://api.polymorfa.com/platform/billing/usage` (Platform API)

Required permission: `billing:read`

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

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/usage" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (any, required). Operation result.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": null
}
```

#### 401

Missing/invalid credential for this audience.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## List billing transactions

`GET https://api.polymorfa.com/platform/billing/transactions` (Platform API)

Required permission: `billing:read`

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

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/transactions" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (any, required). Operation result.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": null
}
```

#### 401

Missing/invalid credential for this audience.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## List tier pricing

`GET https://api.polymorfa.com/platform/billing/pricing` (Platform API)

Required permission: `billing:read`

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

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/pricing" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (any, required). Operation result.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": null
}
```

#### 401

Missing/invalid credential for this audience.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## Get billing

`GET https://api.polymorfa.com/platform/billing` (Platform API)

Required permission: `billing:read`

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

### Request

```bash
curl "https://api.polymorfa.com/platform/billing" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (any, required). Operation result.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": null
}
```

#### 401

Missing/invalid credential for this audience.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 401.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

## Get resource billing controls

`GET https://api.polymorfa.com/platform/billing/controls/{scope}/{resourceId}` (Platform API)

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

- `scope` (string, required). Specifies scope for this path parameter. Values: `project`, `customer`, `number`.
- `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/controls/<scope>/<resourceId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `budget` (object, required). Specifies budget for this management resource billing control.
    - `scope` (string, required). Specifies scope for this management billing limit. Values: `project`, `customer`, `number`.
    - `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `limitCredits` (number, required, nullable, range 0–1000000, multiple of 0.000001). Specifies limit credits for this management billing limit.
    - `spentCredits` (number, required, min 0, multiple of 0.000001). Specifies spent credits for this management billing limit.
    - `reservedCredits` (number, required, min 0, multiple of 0.000001). Specifies reserved credits for this management billing limit.
    - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing limit.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this management resource billing control.
  - `priorityRevision` (integer, required, range 0–2147483646). Specifies priority revision for this management resource billing control.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Get billing limits

`GET https://api.polymorfa.com/platform/billing/limits` (Platform API)

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

- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.
- `scope` (string). Specifies scope for this query parameter. Values: `project`.

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/limits" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `checkedAt` (string (date-time), required, format date-time). Timestamp for checked at.
  - `periodStart` (string (date-time), required, format date-time). Specifies period start for this management billing limit.
  - `periodEnd` (string (date-time), required, format date-time). Specifies period end for this management billing limit.
  - `todayCredits` (number, required, min 0, multiple of 0.000001). Specifies today credits for this management billing limit.
  - `monthCredits` (number, required, min 0, multiple of 0.000001). Specifies month credits for this management billing limit.
  - `daily` (array of object, required). Daily associated with this management billing limit.
    - `date` (string (date), required, format date). Specifies date for this daily.
    - `credits` (number, required, min 0, multiple of 0.000001). Specifies credits for this daily.
  - `budgets` (array of object, required). Budgets associated with this management billing limit.
    - `scope` (string, required). Specifies scope for this management billing limit. Values: `project`, `customer`, `number`.
    - `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `limitCredits` (number, required, nullable, range 0–1000000, multiple of 0.000001). Specifies limit credits for this management billing limit.
    - `spentCredits` (number, required, min 0, multiple of 0.000001). Specifies spent credits for this management billing limit.
    - `reservedCredits` (number, required, min 0, multiple of 0.000001). Specifies reserved credits for this management billing limit.
    - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing limit.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Get billing priorities

`GET https://api.polymorfa.com/platform/billing/priorities` (Platform API)

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

- `scope` (string). Specifies scope for this query parameter. Values: `project`.
- `projectId` (string (uuid), format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing priority.
  - `projects` (array of object, required). Projects associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this project.
  - `customers` (array of object, required). Customers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this customer.
  - `numbers` (array of object, required). Numbers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this number.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Set resource billing controls

`PUT https://api.polymorfa.com/platform/billing/controls/{scope}/{resourceId}` (Platform API)

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

- `scope` (string, required). Specifies scope for this path parameter. Values: `project`, `customer`, `number`.
- `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.

### Body

- `limitCredits` (number, required, nullable, range 0–1000000, multiple of 0.000001). Specifies limit credits for this schema.
- `priority` (integer, required, range 0–1000000). Specifies priority for this schema.
- `expectedBudgetRevision` (integer, required, range 0–2147483646). Specifies expected budget revision for this schema.
- `expectedPriorityRevision` (integer, required, range 0–2147483646). Specifies expected priority revision for this schema.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/billing/controls/<scope>/<resourceId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "limitCredits": 0,
  "priority": 0,
  "expectedBudgetRevision": 0,
  "expectedPriorityRevision": 0
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `budget` (object, required). Specifies budget for this management resource billing control.
    - `scope` (string, required). Specifies scope for this management billing limit. Values: `project`, `customer`, `number`.
    - `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `limitCredits` (number, required, nullable, range 0–1000000, multiple of 0.000001). Specifies limit credits for this management billing limit.
    - `spentCredits` (number, required, min 0, multiple of 0.000001). Specifies spent credits for this management billing limit.
    - `reservedCredits` (number, required, min 0, multiple of 0.000001). Specifies reserved credits for this management billing limit.
    - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing limit.
  - `priority` (integer, required, range 0–1000000). Specifies priority for this management resource billing control.
  - `priorityRevision` (integer, required, range 0–2147483646). Specifies priority revision for this management resource billing control.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Set billing limit

`PUT https://api.polymorfa.com/platform/billing/limits/{scope}/{resourceId}` (Platform API)

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

- `scope` (string, required). Specifies scope for this path parameter. Values: `project`, `customer`, `number`.
- `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.

### Body

- `limitCredits` (number, required, nullable, range 0–1000000, multiple of 0.000001). Specifies limit credits for this schema.
- `expectedRevision` (integer, required, range 0–2147483646). Specifies expected revision for this schema.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/billing/limits/<scope>/<resourceId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "limitCredits": 0,
  "expectedRevision": 0
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `saved` (boolean, required). Whether saved.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "data": {
    "saved": true
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Reorder billing priorities

`PUT https://api.polymorfa.com/platform/billing/priorities` (Platform API)

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:
  - `resources` (object).
    - `scope` (string, required). Specifies scope for this one of. Values: `resource`.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `resources` (array of object, required, max items 1000000, unique items). Resources associated with this one of.
      - `scope` (string, required). Specifies scope for this resource. Values: `customer`, `number`.
      - `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.
    - `expectedRevision` (integer, required, range 0–2147483646). Specifies expected revision for this one of.
  - `Option 2` (object).
    - `scope` (string, required). Specifies scope for this one of. Values: `project`.
    - `resourceIds` (array of string (uuid), required, max items 1000000, unique items, item format uuid). Resource ids associated with this one of.
    - `expectedRevision` (integer, required, range 0–2147483646). Specifies expected revision for this one of.
  - `Option 3` (object).
    - `scope` (string, required). Specifies scope for this one of. Values: `customer`, `number`.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `resourceIds` (array of string (uuid), required, max items 1000000, unique items, item format uuid). Resource ids associated with this one of.
    - `expectedRevision` (integer, required, range 0–2147483646). Specifies expected revision for this one of.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/billing/priorities" \
  -H "Authorization: Bearer <POLYMORFA_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
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing priority.
  - `projects` (array of object, required). Projects associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this project.
  - `customers` (array of object, required). Customers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this customer.
  - `numbers` (array of object, required). Numbers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this number.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Set billing priority

`PUT https://api.polymorfa.com/platform/billing/priorities/{scope}/{resourceId}` (Platform API)

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

- `scope` (string, required). Specifies scope for this path parameter. Values: `project`, `customer`, `number`.
- `resourceId` (string (uuid), required, format uuid). Identifier of the resource affected by this event.

### Body

- `priority` (integer, required, range 0–1000000). Specifies priority for this schema.
- `expectedRevision` (integer, required, range 0–2147483646). Specifies expected revision for this schema.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/platform/billing/priorities/<scope>/<resourceId>" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "priority": 0,
  "expectedRevision": 0
}'
```

### Responses

#### 200

Success
- `data` (object, required). Structured data carried by this object.
  - `revision` (integer, required, range 0–2147483646). Specifies revision for this management billing priority.
  - `projects` (array of object, required). Projects associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this project.
  - `customers` (array of object, required). Customers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this customer.
  - `numbers` (array of object, required). Numbers associated with this management billing priority.
    - `id` (string (uuid), required, format uuid). Identifier for this resource.
    - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
    - `name` (string, required). Human-readable name for this resource.
    - `priority` (integer, required, range 0–1000000). Specifies priority for this number.

Headers:

- `X-Request-Id` (string). Stable request correlation identifier.
- `X-Trace-Id` (string, pattern ^[0-9a-f]{32}$). W3C trace ID of this request. Your `traceparent` trace ID when you sent a valid one.
- `Polymorfa-Version` (string). API version applied to this response.

```json
{
  "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
      }
    ]
  }
}
```

#### 400

A path, query, or request-body value did not pass validation.
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable failure code. Use this value for programmatic handling.
  - `message` (string, required). Safe explanation of the failure.
  - `param` (string, required, nullable). Invalid request field, or null when no field applies.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Documentation link to this failure code.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing/invalid credential for this audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but lacks the required scope/role/audience.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

The requested resource was not found inside the authenticated team or project scope.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 409

The request conflicts with the resource's current state.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "conflict_error",
    "code": "state_conflict",
    "message": "The request conflicts with the resource state.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#state-conflict"
}
```

#### 503

The change was stored, but a connected number has not confirmed it. Retry the request; the stored setting is already correct and is retried automatically.
Same fields as 400.

Headers:

- `X-Request-Id`, `X-Trace-Id`, `Polymorfa-Version`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```
