Skip to main content
PUT
Update user plan
This endpoint gives one of your users one of your plans, for customers who pay you outside your platform, for example by bank transfer, with your own payment links or on invoice. The user gets the plan’s limits and minute rate, and its included minutes if you choose so, and sees the plan on their plans page as managed by you, without the buttons to change or cancel it. It is the Plan action on the Users page of your administration panel.
This endpoint is available to the account owner (with an active plan) and to team members with Billing Access. Other users receive a 403 Forbidden error. Only users of your platform can be changed: any other ID, including the owner account, returns 404.

Minutes

The plan’s minutes come from the owner’s balance, with its chat credits at 9 credits per minute (the cost_in_minutes of List plans). With minutes you choose how:
  • none: only the plan, its limits and minute rate. Nothing is taken from the owner’s balance and nothing renews, for example when you move minutes yourself with Transfer balance.
  • monthly: giving the plan takes one month of minutes and chat credits. Every month the user is topped back up to the plan’s minutes and gets its chat credits again, and the owner’s balance pays only for the minutes they used.
  • yearly: giving the plan takes 12 months at once, and the user gets them month by month. Nothing more is taken for a year. After 12 months, what is left goes back to the owner’s balance and the next 12 months are taken.
If the owner’s balance is too low to give the plan, nothing changes and the request returns 422. Top up your balance first.
  • Moving the user to another plan or minutes option first returns the unused minutes of the current plan, and what is left of a yearly prepayment, to the owner’s balance.
  • Sending the user’s current plan with the same minutes changes only billing, ends_at and when_short. No minutes move.
  • Minutes the user had before, outside a plan you gave, stay with them. Chat credits already given stay with the user.
A user who subscribed on your platform, with a trial or a paid subscription, cannot be given a plan until that subscription ends.

Renewals

Renewals run every hour for the plans whose renewal day has come. When the owner’s balance cannot cover one:
  • The renewal waits, and it is tried again every hour. The user keeps the plan, its limits and the minutes they have left. Get user plan shows renewal.status as pending, with the minutes missing.
  • The owner gets a notification in the administration panel and an email, at most once a day.
  • With when_short set to auto_top_up, the owner’s auto top-up starts, with the amount and card set on the Credits page, even when the balance is above its threshold. It starts at most once a day. With wait, the renewal waits for you to top up.
  • After a top-up, Renew user plan renews right away instead of within the hour.
  • A plan whose last day comes on or before its renewal day is not renewed again: it ends on that day.
With auto top-up on, giving and renewing plans also check the owner’s balance the same way calls do, and top it up under the threshold.

Path Parameters

integer
required
The ID of the user. Administrators can list user IDs with Get platform users.

Request Body

integer
required
One of your plans, from List plans. Inactive plans can be given too.
string
default:"monthly"
none, monthly or yearly, as described above. Left out, a plan you gave before keeps its option, and a new plan is monthly.
string
default:"wait"
auto_top_up or wait: what happens when the owner’s balance cannot cover a renewal, as described above. Left out, a plan you gave before keeps its choice, and a new plan waits. Plans with minutes set to none never renew, so it does not apply to them.
string
default:"monthly"
With minutes set to none only: monthly or yearly, which of the plan’s prices the user sees as theirs. With monthly or yearly minutes, the user sees the matching price. If the plan has no price for it, its other price is used. Left out, a plan you gave before keeps its billing, and a new plan is monthly.
string
The last day of the plan, as YYYY-MM-DD, after today. The plan ends at the end of that day, and its unused minutes go back to the owner’s balance. Left out, a plan you gave before keeps its end date, and a new plan has none. Send null to remove the end date, so the plan stays until you remove it.
Unknown fields are refused, and then nothing is saved.

Response

string
Plan saved.
object
The user’s plan, as in Get user plan

Rate limit

The platform settings, default limits, user settings and plan endpoints share a limit of 60 requests per minute for each account. Above it they return 429, and the Retry-After response header tells you how many seconds to wait.

Example: Give a plan with monthly minutes

Example: A year paid upfront

Example: Only the plan’s limits, until the end of the year

Managed accounts

With Allow New Sign-ups off in your appearance settings, you can run every account yourself: create the user with Register, give them a plan with this endpoint, and remove it with Delete user plan when they cancel with you.