Change the subscription plan (tier switch with proration) | Voicebip

{
  "subscription": {
    "id": "sub_abc123",
    "workspace_id": "ws_abc123",
    "plan": "starter",
    "status": "active",
    "period_start": "2024-01-15T09:30:00Z",
    "period_end": "2024-01-15T09:30:00Z",
    "created_at": "2024-01-15T09:30:00Z",
    "updated_at": "2024-01-15T09:30:00Z"
  },
  "proration": {
    "refund_minor": 1000000,
    "charge_minor": 1000000,
    "net_minor": 1000000,
    "proration_ratio": 1.1,
    "days_remaining": 1,
    "period_days": 1,
    "currency": "NGN",
    "description": "20 days remaining, upgraded starter → builder"
  },
  "quota_after": {
    "voice_minutes_remaining": 1000000,
    "sms_remaining": 1000000,
    "whatsapp_remaining": 1000000,
    "numbers_included": 1
  }
}

Switches the workspace to the requested plan with mid-period proration applied atomically. The response envelope includes:

subscription: the updated row.
proration: refund of unused old-tier base + prorated new-tier base, net of both. Positive net_minor = debit; negative = credit. Charges recorded in the recurring_charges ledger.
quota_after: absolute voice/SMS/WhatsApp remaining counts AFTER carryover. Unused quota from the old tier is preserved and added to the new tier’s included quantities.

Errors:

400 NO_OP if already on that plan.
400 TIER_SWITCH_UNSUPPORTED on PAYG workspaces.
402 INSUFFICIENT_BALANCE if the upgrade’s net charge exceeds the workspace balance; customer must top up first.
404 NO_ACTIVE_SUBSCRIPTION when nothing to switch.

Retries are idempotent: a client that sends the same PATCH twice (e.g. after a network timeout) will not be double-billed. The second call either returns NO_OP (if the first apply completed) or replays the first call’s response (if the client retried while the first was in flight).

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

planenumRequired

Target plan. Must differ from the current plan.

Allowed values:

Response

Subscription updated with proration

subscriptionobject

prorationobject

quota_afterobject

Errors

400

Update Subscription Request Bad Request Error

401

Update Subscription Request Unauthorized Error

402

Update Subscription Request Payment Required Error

404

Update Subscription Request Not Found Error

500

Update Subscription Request Internal Server Error

503

Update Subscription Request Service Unavailable Error