> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview and Execute Your Mail Subscription Upgrade

> Preview the prorated cost with GET /v1/billing/upgrade/preview, then apply the change with POST /v1/billing/upgrade using a saved bank card.

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.

<Warning>
  Only saved bank cards can be used for instant upgrades. Mobile money methods are not accepted.
</Warning>

***

## 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

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The ID of the organization whose subscription will be upgraded.
</ParamField>

### Query parameters

<ParamField query="newPlan" type="string" required>
  Target plan. One of `core`, `growth`, or `scale`.
</ParamField>

<ParamField query="newSeats" type="number" required>
  Target number of mailbox seats.
</ParamField>

<ParamField query="newCycle" type="string" required>
  Target billing cycle. One of `monthly` or `yearly`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` on a successful request.
</ResponseField>

<ResponseField name="data" type="object">
  Proration details.

  <Expandable title="properties">
    <ResponseField name="amountDueToday" type="number">
      Amount in KES charged immediately. `0` if no payment is required (e.g. downgrade with credit).
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
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>'
```

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

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The ID of the organization whose subscription will be upgraded.
</ParamField>

### Request body

<ParamField body="newPlan" type="string" required>
  Target plan. One of `core`, `growth`, or `scale`.
</ParamField>

<ParamField body="newSeats" type="number" required>
  Target number of mailbox seats.
</ParamField>

<ParamField body="newCycle" type="string" required>
  Target billing cycle. One of `monthly` or `yearly`.
</ParamField>

<ParamField body="paymentMethodId" type="string">
  ID of a saved bank card. Required if `amountDueToday` from the preview is greater than `0`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` on a successful upgrade.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

### Example

```bash theme={null}
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..."
  }'
```

```json theme={null}
{
  "success": true,
  "message": "Subscription upgraded successfully!"
}
```