Change organization plan

patch

https://api.benjipays.com/v2/organizations/{organizationId}/plan

Access: Requires DISTRIBUTOR actor type

Changes the billing plan assigned to an Organization. Used when an MSP upgrades or downgrades a customer's subscription.

Workflow:

Validates organization belongs to authenticated distributor
Validates new plan is visible to distributor (in their plan catalog)
Checks that new plan is different from current plan
Updates billing.planId and billing.details on organization
Creates activity log entry with previous and new plan details

Billing Implications:

Plan change takes effect immediately
Current month billed at new plan rate (no proration for now)
Usage/overages calculated against new plan's included transactions

Validations:

Cannot change to the same plan (returns 409)
New plan must belong to distributor's catalog (returns 404 if not)
Organization must belong to distributor (returns 404 if not)

Requires JWT authentication and 'partners:organizations:change-plan' scope.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

organizationId

string

required

^[0-9a-fA-F]{24}$

MongoDB ObjectId of the organization

Body Params

planId

string

required

^[0-9a-fA-F]{24}$

MongoDB ObjectId of the new plan to assign

Headers

X-Request-ID

uuid

Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.

X-Correlation-ID

uuid

Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.

Idempotency-Key

string

length between 1 and 255

^[a-zA-Z0-9]+$

Optional client-supplied key that makes retries safe for POST/PATCH/PUT. Scoped per actor; cached for 24 hours. Replays return the cached response with X-Idempotency-Replayed: true. Same key with a different body returns 409. In-flight duplicates return 429 with Retry-After. See the Idempotency section in the API overview.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Plan changed successfully

400Bad Request - Invalid planId format

401Unauthorized - Invalid or missing authentication token

403Forbidden - Distributor actor type required

404Not Found - Organization or plan not found, or plan not visible to distributor

409Conflict - Organization is already on this plan

429Too Many Requests - Rate limit exceeded