---
title: "Set additional email-user credits"
method: POST
path: "/v1/account/email-credits"
tags: ["Account"]
---

# Set additional email-user credits

`POST /v1/account/email-credits`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/account/email-credits`
- Auth: HTTP bearer

Sets the account's additional email-user credits (the per-user addon) to a
target total, mirroring the Settings > Subscription dashboard flow. Adds,
updates, or removes the addon line item on the main plan subscription (the
change is prorated and charged immediately to the default payment method),
then updates `email_user_limit_additional_credits` and `email_user_limit`.

`quantity` is the target TOTAL additional credits (not a delta), so the call
is idempotent and safe to retry. Effective email user limit = base plan limit
+ additional credits.

Floor: additional credits can never be set below
`max(0, email_users_used - email_user_limit_base)` — i.e. the total allowance
can never drop below the mailboxes currently in use. To go lower, delete email
users first.

Not available for reseller / Connected-Account sub-accounts (returns 400 — use
the dashboard).

## Request body

- object
  - `quantity` integer, required: Target total additional email-user credits

## Response `200`

Credits updated (or no-op, or pending payment verification)

- object
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time
  - `data` object
    - `action` 'created' | 'updated' | 'removed' | 'unchanged' | 'requires_action': What happened. `unchanged` = already at this quantity (no charge); `requires_action` = payment needs 3D Secure verification.
    - `additional_credits` integer: Additional credits after the change
    - `email_user_limit` integer: Effective email user limit (base plan limit + additional_credits)
    - `requires_action` boolean: True when the payment needs customer verification (3D Secure)
    - `payment_url` string: Hosted invoice URL to complete verification (only when requires_action is true)

## Other responses

- `400`: Invalid quantity, no active subscription, or reseller-managed account
- `401`: Authentication required or token invalid
- `402`: Payment failed (card declined). Credits were not changed.
- `409`: Resource conflict

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)