Skip to main content
Upgrading a subscription is a two-step process: first preview the cost, then execute the change. The preview endpoint calculates the exact prorated charge for the remainder of the current billing period. If an amount is due, a saved bank card is required to complete the upgrade instantly.
Only saved bank cards can be used for instant upgrades. Mobile money methods are not accepted.

​
Preview an upgrade

GET /v1/billing/upgrade/preview
Returns the amount due today, along with the full proration calculation. Call this before executing an upgrade to show the user what they will be charged.

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <token>
​
X-Organization-Id
string
required
The ID of the organization whose subscription will be upgraded.

​
Query parameters

​
newPlan
string
required
Target plan. One of core, growth, or scale.
​
newSeats
number
required
Target number of mailbox seats.
​
newCycle
string
required
Target billing cycle. One of monthly or yearly.

​
Response

​
success
boolean
true on a successful request.
​
data
object
Proration details.

​
Example

curl --request GET \
  --url 'https://api.nyotaimara.com/v1/billing/upgrade/preview?newPlan=growth&newSeats=20&newCycle=monthly' \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <org-id>'

{
  "success": true,
  "data": {
    "amountDueToday": 1500
  }
}

​
Execute an upgrade

POST /v1/billing/upgrade
Charges the prorated amount to the saved bank card and immediately applies the new plan, seat count, and billing cycle to the subscription.

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <token>
​
X-Organization-Id
string
required
The ID of the organization whose subscription will be upgraded.

​
Request body

​
newPlan
string
required
Target plan. One of core, growth, or scale.
​
newSeats
number
required
Target number of mailbox seats.
​
newCycle
string
required
Target billing cycle. One of monthly or yearly.
​
paymentMethodId
string
ID of a saved bank card. Required if amountDueToday from the preview is greater than 0.

​
Response

​
success
boolean
true on a successful upgrade.
​
message
string
Confirmation message.

​
Example

curl --request POST \
  --url https://api.nyotaimara.com/v1/billing/upgrade \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <org-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "newPlan": "growth",
    "newSeats": 20,
    "newCycle": "monthly",
    "paymentMethodId": "pm_01j9k2x..."
  }'

{
  "success": true,
  "message": "Subscription upgraded successfully!"
}