Skip to main content
POST
Upgrade Service
Submit a move to a higher-ranked plan in your broker catalog. Requires admin:full.

Choose a plan

  1. Use List Plans to find active plans for your broker.
  2. Choose a plan with an upgrade_rank higher than the current plan’s rank and the same billing_type.
  3. Send its slug, id, or display name in new_plan. Slugs and display names are matched case-insensitively.
Plan names and eligibility are broker-specific. The current plan and an equal-ranked plan are not valid targets. Use Downgrade Service to move in the other direction. Sandbox plan changes use fixed standard plans rather than this live catalog behavior. See Sandbox Mode.

Track the result

HTTP 200 with request_status: "accepted" means the work was queued, not that the plan has changed. HTTP 202 with nycservers_review means NYCServers must review the request. Do not resubmit it.
Save the request_id and check List Requests. Check the related service for its current plan and specifications, and follow any setup or reboot instructions sent to the client. Use Errors and Retries to handle uncertain outcomes and X-Idempotency-Key safely.

Endpoint errors

For authentication, permissions, rate limits, and safe retries, see Errors and Retries. A change between monthly and hourly billing is rejected with 400 invalid_state; it requires cancellation and recreation rather than a plan change.

Authorizations

Authorization
string
header
required

Send the API key in the Authorization bearer header. Production keys begin with sk_live_.

Headers

X-Idempotency-Key
string

Unique key for one intended operation. Reuse with unchanged input for retries. Supported by service creation, plan changes, cancellation, and request approval (not denial). Creation replays by key without checking changed input; action payload conflicts can return 409. See /api/errors-and-retries for endpoint-specific behavior.

Path Parameters

service_number
integer<int64>
required

Public service number parsed as a base-10 integer.

Body

application/json
new_plan
string
required

Active broker catalog plan id, slug, or display name. Slugs and display names are matched case-insensitively. Use GET /v1/plans for available choices. Live direction follows upgrade_rank and billing_type must match. Sandbox plan changes use the four standard plans instead.

Response

Upgrade accepted for processing.

success
boolean
required
data
object
required
message
string
pagination
object
Last modified on September 8, 2026