Accounts

An account is your organization’s Carom workspace. Every user, mailbox, and record belongs to exactly one account. Use this resource to read the account’s billing state: whether it is live, the status of its subscription, what it is being charged for, and its recent invoices.

An account starts pre-live: people can sign in and invite colleagues, and nothing is billed. It goes live when the first mailbox is connected, which starts the subscription. Only the account owner can read invoices and charges, so this endpoint works only when your key’s user is the account owner. Changing the payment card, closing the account, and the account’s switches for API access, outbound email, and Ask Carom are managed by admins in the Carom app; read the switches on Retrieve your key’s user.

#The account object

Returned by Retrieve an account.

Every amount and rate is an integer number of cents.

Attributes

idstring · uuid

Unique identifier for the account.
statusstring

Where the account is in its lifecycle. An account moves from pre-live to live once, when its first mailbox is connected.

pre-livelive
billing_accountobject · nullable

The account’s billing record. Null when the account has none, for example an account that isn’t billed.
Show 10 child attributesHide child attributes
- idstring · uuid
- account_idstring · uuid
- subscription_statusstring · nullable
  
  The subscription’s status. past_due and incomplete mean a payment failed and is being retried; the account keeps working but can’t add users or mailboxes. unpaid, canceled, and incomplete_expired lock the account until payment resumes. Null before the account goes live.
  
  activeincompletepast_dueunpaidcanceledincomplete_expired
- plan_codestring · nullable
  The price plan, such as basic.
- created_atstring · date-time · nullable
- canceled_atstring · date-time · nullable
  When cancellation was requested.
- cancellation_effective_atstring · date-time · nullable
  When a requested cancellation takes effect.
- first_period_ends_atstring · date-time · nullable
  End of the subscription’s first billing period. Launch credit that remains at this time expires.
- current_usageobject
  
  What the subscription charges for each month. An empty object until the account goes live.
  Show 3 child attributesHide child attributes
  - subscriptionobject
    The base monthly rate, in cents.
  - userobject
    The number of billed users as quantity, and the monthly rate for each, in cents.
  - mailboxobject
    The number of billed mailboxes as quantity, and the monthly rate for each, in cents.
- invoicesarray of objects
  
  The upcoming invoice, with the id upcoming, followed by recent invoices, newest first. There is no upcoming invoice before the account goes live or after the subscription is canceled.
  Show 15 child attributesHide child attributes
  - idstring · nullable
    The invoice’s id, or upcoming for the upcoming invoice.
  - numberstring · nullable
    The invoice number printed on the invoice.
  - statusstring · nullable
    The invoice’s status, such as draft, open, or paid.
  - billing_reasonstring · nullable
    Why the invoice was created, such as subscription_create or subscription_cycle. upcoming for the upcoming invoice.
  - currencystring · nullable
    Three-letter currency code in lowercase, such as usd.
  - paidboolean · nullable
  - amount_dueinteger
    In cents.
  - amount_paidinteger
    In cents.
  - subtotalinteger · nullable
    In cents, before credits and discounts.
  - totalinteger · nullable
    In cents.
  - period_startstring · date-time · nullable
  - period_endstring · date-time · nullable
  - hosted_invoice_urlstring · nullable
    A page where the invoice can be viewed and paid.
  - invoice_pdfstring · nullable
    A link to the invoice as a PDF.
  - itemsarray of objects
    
    The invoice’s line items, one per line on the invoice. A proration line and a regular line of the same type are separate items.
    
    Show 8 child attributesHide child attributes
    
    typestring
    What the line charges for.
    subscriptionusersmailboxes
    
    descriptionstring · nullable
    The line’s description as it appears on the invoice.
    
    quantityinteger · nullable
    
    unit_rateinteger · nullable
    Price per unit, in cents.
    
    amountinteger
    The line’s amount, in cents. Negative for a credit.
    
    prorationboolean · nullable
    True for a charge or credit for a change partway through a billing period, such as adding a user.
    
    period_startstring · date-time · nullable
    
    period_endstring · date-time · nullable

The account object

{
  "id": "06d4e1ca-b76f-4210-8165-c0f9199478ec",
  "status": "live",
  "billing_account": {
    "id": "1bd3926b-18f0-462f-8aba-1ab51aa99700",
    "account_id": "06d4e1ca-b76f-4210-8165-c0f9199478ec",
    "subscription_status": "active",
    "plan_code": "basic",
    "created_at": "2026-09-01T15:20:04.118Z",
    "canceled_at": null,
    "cancellation_effective_at": null,
    "first_period_ends_at": "2026-10-02T13:02:51.000Z",
    "current_usage": {
      "subscription": { "rate": 4900 },
      "user": { "quantity": 4, "rate": 1900 },
      "mailbox": { "quantity": 3, "rate": 2900 }
    },
    "invoices": [
      {
        "id": "upcoming",
        "number": null,
        "status": "draft",
        "billing_reason": "upcoming",
        "currency": "usd",
        "paid": false,
        "amount_due": 21200,
        "amount_paid": 0,
        "subtotal": 21200,
        "total": 21200,
        "period_start": "2026-10-02T13:02:51.000Z",
        "period_end": "2026-11-02T13:02:51.000Z",
        "hosted_invoice_url": null,
        "invoice_pdf": null,
        "items": [
          {
            "type": "subscription",
            "description": "Carom (at $49.00 / month)",
            "quantity": 1,
            "unit_rate": 4900,
            "amount": 4900,
            "proration": false,
            "period_start": "2026-10-02T13:02:51.000Z",
            "period_end": "2026-11-02T13:02:51.000Z"
          },
          …
        ]
      },
      …
    ]
  }
}

get/accounts/{id} Read key

#Retrieve an account

Returns your account with its billing record, current usage, and invoices. {id} must be your account’s id, and your key’s user must be the account owner. Get the id from account.id on Retrieve your key’s user.

Path parameters

idstring · uuidrequired

Your account’s id.

Returns

The account object, wrapped in account.

Errors

403permission_deniedYour key’s user isn’t the account owner.
404record_not_foundThe id isn’t your account’s.
502billing_unavailableInvoices couldn’t be loaded. Retry later.

get/accounts/{id}

curl https://api.carom.io/accounts/06d4e1ca-b76f-4210-8165-c0f9199478ec \
  -H "Authorization: Bearer $CAROM_API_KEY"

Response200

{
  "account": {
    "id": "06d4e1ca-b76f-4210-8165-c0f9199478ec",
    "status": "live",
    "billing_account": {
      "id": "1bd3926b-18f0-462f-8aba-1ab51aa99700",
      "subscription_status": "active",
      "plan_code": "basic",
      "current_usage": {
        "subscription": { "rate": 4900 },
        "user": { "quantity": 4, "rate": 1900 },
        "mailbox": { "quantity": 3, "rate": 2900 }
      },
      …
    }
  }
}