---
title: "Add Enterprise User Subscription"
method: POST
path: "/admin/enterprise_user_subscription"
tags: ["accepts-api-key"]
---

# Add Enterprise User Subscription

`POST /admin/enterprise_user_subscription`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/admin/enterprise_user_subscription`
- Auth: none declared

Put users on an enterprise subscription, outside Stripe. Admin only.

Enterprise unlocks every feature and shows in the app as an Enterprise
plan. Each user gets ``monthly_tokens`` now and every month after, a
``storage_gb`` quota, and ``instant_tokens`` once, expiring after
``instant_tokens_expiration_days``. The subscription ends by itself after
``duration_months``.

A user already on enterprise gets the new terms and period instead, with
no new monthly tokens. Every email is handled on its own: one that can't be
(no account, or a Stripe subscription to cancel first) is listed in
``issues`` and the others still go through.

## Headers

- `x-api-key` string, nullable
- `authorization` string, nullable

## Request body

- EnterpriseUserSubscriptionAddRequest
  - `emails` string[], required: Emails of the users to put on the enterprise subscription
  - `monthly_tokens` number, required: Tokens each user gets every month, the first month on being added. Each month's tokens expire after one month.
  - `storage_gb` integer, required: Storage quota of each user, in GB
  - `duration_months` integer, required: Months from now the subscription lasts. For a user already on enterprise, the period is reset to end this many months from now.
  - `instant_tokens` number, required: One-off tokens granted to each user now, on top; 0 for none
  - `instant_tokens_expiration_days` integer, required: Days from today after which the one-off tokens expire

## Response `200`

Successful Response

- EnterpriseUserSubscriptionAddResponse
  - `members` EnterpriseUserSubscriptionMember[], required: Users put on, or kept on, the enterprise subscription
    - `email` string, required: Email of the user
    - `action` 'added' | 'updated', required: added: the user was put on enterprise and got this month's tokens; updated: the user was already on it and only the terms changed
    - `instant_grant_id` string, uuid, nullable, required: Id of the one-off grant, null when none was made
    - `subscription` ApiUserSubscription, required
      - `type` 'Monthly' | 'Yearly' | 'Enterprise', required: User-facing subscription cadence label. Enterprise is a plan set up by the Tellers team, billed outside the app: it unlocks every feature and cannot be changed or cancelled from the app.
      - `tier` 'basic' | 'pro' | 'expert' | 'enterprise_user', required: Named subscription offer; subscriptions that predate tiers read as basic. ``enterprise_user`` is granted by hand outside Stripe (see :mod:`tellers_common.enterprise_user_subscription`) and ranks above every paid tier.
      - `pricing_tier` string, nullable: Billing catalog plan `tier_id` the subscription is on (for example `monthly` or `pro_yearly`), including existing subscribers on retired prices; null when it matches no catalog plan.
      - `can_configure_tokens` boolean, required: True when the user can buy extra tokens on top of the plan (expert only).
      - `monthly_tokens` number, required: Subscription token amount available each month.
      - `storage_quota_gb` integer, required: Total storage quota available to the user in GB.
      - `pricing` ApiUserSubscriptionPricingLine[]: Current Stripe subscription price lines with price id and quantity.
        - `id` string, required: Stripe price id for this subscription line.
        - `quantity` integer, required: Quantity for this Stripe price line.
      - `currency` string, nullable: Lowercase ISO 4217 code the subscription is billed in. Stripe can't change it, so plan changes are priced in it. Null for a subscription not synced since this was added.
      - `cancel_at_period_end` boolean: True when Stripe will cancel the subscription at period end.
      - `cancel_at` string, nullable: UTC ISO-8601 time when Stripe will cancel the subscription.
      - `current_period_end` string, nullable: UTC ISO-8601 end of the current subscription period.
      - `tokens_renew_at` string, nullable: UTC ISO-8601 time the plan's monthly tokens are next granted: the renewal for a monthly plan, the next monthly drop for a yearly one. Null when no further grant is due (e.g. the subscription is set to cancel first).
      - `latest_payment_issue` object, nullable: When set, an invoice needs payment or customer action (e.g. 3DS). Fields may include invoice_id, invoice_status, hosted_invoice_url, customer_action_url.
  - `issues` EnterpriseUserSubscriptionIssue[], required: Emails left unchanged, each with the reason
    - `email` string, required: Email as sent, trimmed and lowercased
    - `detail` string, required: Why nothing was done for this email

## Other responses

- `422`: Validation Error

---

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