Hellou AI Plan Upgrades API

openapi: 3.2.0
info:
  title: HellouOne Plan Upgrades API
  version: 1.0.0
  description: 'The HellouOne REST API: everything the dashboard does, available to your

    own systems — CRMs, bots, BI tools and back-office automation.'
  termsOfService: https://hellou.ai/en/legal/terms/
  contact:
    name: HellouOne support
    email: support@hellou.ai
servers:
- url: https://one.hellou.ai
  description: HellouOne cloud
security:
- userApiKey: []
tags:
- name: Plan Upgrades
  description: 'Buy a higher plan for the account. The card on file is charged and the account moves to the plan

    without anyone from HellouOne stepping in. The purchase runs in the background: start it, then poll

    it until it settles. Administrators only.'
paths:
  /api/v1/accounts/{account_id}/plan_upgrades:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Plan Upgrades
      operationId: listPlanUpgrades
      summary: List plan upgrades
      description: 'The account''s last 10 plan purchases, newest first, with where each one stands.


        **Administrators only.**'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_list'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
    post:
      tags:
      - Plan Upgrades
      operationId: createPlanUpgrade
      summary: Start a plan upgrade
      description: 'Buys a plan for the account: the card on file is charged and the account moves to the plan. Charging takes

        longer than a request may, so this call only records the purchase and answers at once; the work continues

        in the background. Follow it with Get a plan upgrade until `status` is

        `completed`, `failed` or `needs_review`.


        Send an `idempotency_key` (any unique string, for example a UUID) and reuse it when you retry: a repeated

        request returns the purchase it started instead of charging twice. The plan is checked before the key is

        looked up, so a repeat after the purchase completed is refused with `422` `already_on_plan`, a plan since

        taken off sale with `422`, and an installation without billing with `503`. When the account had no card

        (`status: awaiting_card`), add one in Settings → Billing and send the same key again to resume.


        Only one purchase can be open per account. While one is running, a new request is answered with `409` and

        the open upgrade; an upgrade that has not reached the charge yet is replaced by the new request.


        Works on an account whose trial has ended, since paying is what such an account needs to do. Only moves to

        a higher-priced plan are self-serve.


        **Administrators only.**'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - plan_id
              properties:
                plan_id:
                  type: integer
                  description: The plan to buy.
                idempotency_key:
                  type: string
                  description: A unique string for this purchase. Reuse it to retry safely. Omitted, the server makes one and a retry may start a second purchase.
      responses:
        '202':
          description: The purchase was recorded and is running.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_show'
        '200':
          description: The `idempotency_key` matches an earlier purchase of this account whose plan can still be bought; that purchase is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_show'
        '409':
          description: Another upgrade is already open. `error` is `upgrade_in_progress` and `plan_upgrade` is the open one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_show'
        '422':
          description: The request was refused. See `error` for the code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_refusal'
        '503':
          description: Billing is not set up on this installation (`error` is `porta_unconfigured`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_refusal'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
  /api/v1/accounts/{account_id}/plan_upgrades/preview:
    parameters:
    - $ref: '#/components/parameters/account_id'
    get:
      tags:
      - Plan Upgrades
      operationId: previewPlanUpgrade
      summary: Preview the cost of a plan
      description: 'What buying the plan would charge today, so you can show the amount before asking for confirmation. For a

        move between paid plans the amount covers the days left in the billing period (`prorated: true`); a first

        purchase pays the full month. When the billing system is slow to answer, the list price comes back instead

        with `prorated: false`.


        Plans that cannot be bought are refused here with the same codes as when starting an

        upgrade, before any price is looked up.


        **Administrators only.**'
      parameters:
      - in: query
        name: plan_id
        required: true
        schema:
          type: integer
        description: The plan to quote.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_preview'
        '422':
          description: The plan cannot be bought. `error` is `plan_not_found`, `plan_requires_quote`, `plan_not_billable`, `plan_not_purchasable`, `already_on_plan`, `downgrade_not_supported` or `plan_change_managed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_refusal'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
  /api/v1/accounts/{account_id}/plan_upgrades/{plan_upgrade_id}:
    parameters:
    - $ref: '#/components/parameters/account_id'
    - $ref: '#/components/parameters/plan_upgrade_id'
    get:
      tags:
      - Plan Upgrades
      operationId: getPlanUpgrade
      summary: Get a plan upgrade
      description: 'One plan purchase. Poll it after starting an upgrade until `status` is

        `completed`, `failed` or `needs_review`, or `awaiting_card` when the account has to add a card.


        **Administrators only.**'
      parameters:
      - $ref: '#/components/parameters/plan_upgrade_id'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/plan_upgrade_show'
        '404':
          description: The upgrade does not exist in this account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
components:
  schemas:
    plan_upgrade_list:
      type: object
      description: The account's most recent plan upgrades.
      properties:
        plan_upgrades:
          type: array
          description: Up to 10 upgrades, newest first.
          items:
            $ref: '#/components/schemas/plan_upgrade'
      required:
      - plan_upgrades
    plan_upgrade_preview:
      type: object
      description: What buying a plan would cost today.
      properties:
        preview:
          type: object
          description: The quote.
          properties:
            plan_id:
              type: integer
              description: The plan quoted.
            amount_cents:
              type: integer
              description: What would be charged today, in cents of `currency`, activation fee included.
            setup_fee_cents:
              type: integer
              description: The one-time activation fee inside `amount_cents`, in cents. `0` when none applies.
            monthly_cents:
              type: integer
              description: The plan's monthly price, in cents.
            currency:
              type: string
              description: ISO 4217 currency code of the amounts.
            prorated:
              type: boolean
              description: '`true` when the amount covers only the days left in the current period. `false` when it is the list price for a full month, including when the billing system was too slow to answer.'
          required:
          - plan_id
          - amount_cents
          - setup_fee_cents
          - monthly_cents
          - currency
          - prorated
      required:
      - preview
    plan_upgrade:
      type: object
      description: 'One purchase of a plan. The charge and the plan change happen in the background, so the `status` moves

        on its own: poll the upgrade until it is `completed`, `failed` or `needs_review`, or until it asks for

        a card (`awaiting_card`).

        '
      properties:
        id:
          type: integer
          description: The upgrade id.
        status:
          type: string
          enum:
          - pending
          - provisioned
          - awaiting_card
          - preparing
          - charging
          - charged
          - subscribed
          - reconciled
          - completed
          - failed
          - needs_review
          description: 'The last step reached. `awaiting_card` means the account has no card on file: add one in Settings →

            Billing, then send the same `idempotency_key` again to resume. `completed` means the account is on the

            plan. `failed` means nothing was charged and the account kept its plan; see `error_code`. `needs_review`

            means a payment may have been taken and the HellouOne team will finish it by hand. Every other value is

            a step in progress.

            '
        amount_cents:
          type: integer
          description: What is charged today, in cents of `currency`. A full month, or the days left in the period when `prorated` is `true`; the activation fee is included.
        setup_fee_cents:
          type: integer
          description: The one-time activation fee inside `amount_cents`, in cents. `0` when none applies.
        monthly_cents:
          type: integer
          description: The plan's monthly price, in cents.
        prorated:
          type: boolean
          description: '`true` when `amount_cents` covers only the days left in the current period, `false` when it is a full month.'
        currency:
          type: string
          description: ISO 4217 currency code of the amounts.
        error_code:
          type:
          - string
          - 'null'
          enum:
          - provisioning_failed
          - card_check_failed
          - no_card
          - charge_unsupported
          - charge_declined
          - charge_timeout
          - charge_unknown
          - charge_unverified
          - subscription_failed
          - activation_failed
          - superseded
          - operator_resolved
          - plan_not_purchasable
          - null
          description: 'Why the upgrade failed or needs review, or `null`. `no_card` and `charge_declined` are the ones a

            customer can fix by updating the card; `superseded` means a newer purchase replaced this one before

            any charge; `operator_resolved` means the HellouOne team closed it by hand.

            '
        card_brand:
          type:
          - string
          - 'null'
          description: Brand of the card charged, once known.
        card_last4:
          type:
          - string
          - 'null'
          description: Last four digits of the card charged, once known.
        created_at:
          type: string
          format: date-time
          description: When the purchase was requested.
        charged_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the payment was confirmed, or `null` before that.
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the upgrade finished (completed or failed), or `null` while it is open.
        plan:
          type: object
          description: The plan being bought.
          properties:
            id:
              type: integer
              description: The plan id.
            name:
              type: string
              description: The plan name.
            tier:
              type:
              - string
              - 'null'
              description: The plan tier.
        previous_plan:
          type:
          - object
          - 'null'
          description: The plan the account was on when it asked, or `null` for an account without one.
          properties:
            id:
              type: integer
              description: The plan id.
            name:
              type: string
              description: The plan name.
            tier:
              type:
              - string
              - 'null'
              description: The plan tier.
        requested_by:
          type:
          - object
          - 'null'
          description: The administrator who asked for the purchase, or `null` if that user was removed.
          properties:
            id:
              type: integer
              description: The user id.
            name:
              type: string
              description: The user's name.
    plan_upgrade_show:
      type: object
      description: A plan upgrade, with the reason a request was refused when it conflicts with an open one.
      properties:
        error:
          type: string
          description: Present only on a `409` response. Always `upgrade_in_progress`; the open upgrade that blocks the request is in `plan_upgrade`.
        plan_upgrade:
          $ref: '#/components/schemas/plan_upgrade'
      required:
      - plan_upgrade
    plan_upgrade_refusal:
      type: object
      description: A plan upgrade request that was refused.
      properties:
        error:
          type: string
          enum:
          - plan_not_found
          - plan_requires_quote
          - plan_not_billable
          - plan_not_purchasable
          - already_on_plan
          - downgrade_not_supported
          - plan_change_managed
          - upgrade_conflict
          - porta_unconfigured
          description: 'Why the request was refused. `plan_not_found`: no such plan. `plan_not_purchasable`: the plan is not on

            the self-serve price list. `plan_requires_quote`: a price-list plan sold through sales. `plan_not_billable`:

            a price-list plan that cannot be bought online on this installation yet. `already_on_plan`: the account is already on it. `downgrade_not_supported`:

            only moves to a higher-priced plan are self-serve. `plan_change_managed`: the account''s plan

            is managed by the HellouOne team. `upgrade_conflict` (POST only): a concurrent request raced this one;

            retry. `porta_unconfigured` (POST only, `503`): billing is not set up on this installation.

            '
      required:
      - error
    error_message:
      type: object
      description: An error with a human-readable message.
      properties:
        error:
          type: string
          description: What went wrong.
        reason:
          type: string
          description: Machine-readable cause, when there is one (for example `feature_disabled`).
      required:
      - error
  responses:
    unauthorized:
      description: Missing or invalid `api_access_token`, or a bot token on an endpoint bots cannot use.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
    forbidden:
      description: 'Not allowed: the user''s role does not permit it, the feature is not enabled

        for the account (`reason: feature_disabled`), or the account is read-only.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_message'
  parameters:
    account_id:
      in: path
      name: account_id
      required: true
      description: The numeric ID of the account
      schema:
        type: integer
    plan_upgrade_id:
      in: path
      name: plan_upgrade_id
      required: true
      description: The numeric ID of the plan upgrade
      schema:
        type: integer
  securitySchemes:
    userApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A user''s access token, from **Profile settings → Access token** in the dashboard.

        Requests act with that user''s role: administrators reach everything in their

        account, agents only what their role and visibility settings allow.

        '
    agentBotApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'An agent bot''s access token, shown to administrators on the bot''s settings page.

        Bot tokens reach a limited set of conversation and message endpoints.

        '
    platformAppApiKey:
      type: apiKey
      in: header
      name: api_access_token
      description: 'A platform app token, issued by the installation operator. Used to provision

        accounts, users, account memberships and agent bots.

        '
    connectorInvokeToken:
      type: http
      scheme: bearer
      description: 'A connector''s invoke token (`hci_…`), sent as `Authorization: Bearer <token>`.

        Each connector install has its own; it is rotated whenever the connector is

        reconnected or disconnected, so a stale copy stops working.

        '
x-tagGroups:
- name: Guides
  tags:
  - Introduction
  - Authentication
  - Errors
  - Pagination
  - Rate limits
  - Webhook events
- name: Webhook payloads
  tags:
  - Event payloads
- name: Platform
  tags:
  - Accounts
  - Account Users
  - AgentBots
  - Users
- name: Application
  tags:
  - Account AgentBots
  - Agents
  - Automation Rule
  - Campaigns
  - Canned Responses
  - Contacts
  - Contact Labels
  - Conversation Assignment
  - Conversation Labels
  - Conversations
  - Custom Attributes
  - Custom Filters
  - Help Center
  - Inboxes
  - Integrations
  - Macros
  - Messages
  - Profile
  - Reports
  - Security Settings
  - Teams
  - Webhooks
- name: Business tools
  tags:
  - AI Classifications
  - Assignment Settings
  - Calls
  - AI Phone Lines
  - Connectors
  - ElevenLabs Integration
  - Facebook Marketing
  - HellouAI Integration
  - Knowledge Base
  - Marketing Consent
  - Plan Upgrades
  - Voice Campaigns
  - WhatsApp Campaigns
  - WhatsApp Flows
  - WhatsApp Templates
- name: Client
  tags:
  - Inbox API
  - Contacts API
  - Conversations API
  - Messages API
- name: Others
  tags:
  - CSAT Survey Page