Companies

Invoice a company for a plan

Changed on

Sells a membership plan to a company by invoice, the same as Generate invoice in the company plan dialog. Issues a Stripe invoice on the board's connected account, due in 30 days, and returns its hostedInvoiceUrl. Cavuno does not send the invoice itself; share the link with the employer. The plan is assigned to the company when the invoice is paid. The plan's own price and, for a subscription plan, its interval set the terms; for a plan without a price, send amountCents and currency. Send billingInterval to make the invoice recur. A company holds one membership at a time, so a company with an active membership or another membership invoice awaiting payment gets 409 company_plan_membership_taken. Requires an Idempotency-Key header: a retry with the same key returns the first response and never issues a second invoice. Requires plans.manage.

post/companies/{id}/plan-invoices

Request

  • Base URL: https://api.cavuno.com/v1
  • URL: https://api.cavuno.com/v1/companies/{id}/plan-invoices
  • Auth: HTTP bearer

Path parameters

idstring required

The company's opaque object id: the id field returned by the company endpoints (e.g. p17xq4c2b9r5gz3e8j0r6t4k7m2n9d5w). This is NOT the slug or display name; passing a slug like antler returns 404. To look up a company by name or slug, use GET /v1/companies, POST /v1/companies/search, or POST /v1/companies/find-or-create and read the returned id.

Request body

planIdstring required

An active (not archived) plan with purpose: membership on this board.

contactEmailstring email required

Billing email of the employer who will pay.

amountCentsinteger

Amount per invoice in currency minor units. Required when the plan has no price; rejected when it has one.

currencystring

ISO 4217 currency code. Send it together with amountCents.

billingInterval'month' | 'year'

Make the invoice recur. Omit for a one-off invoice. Rejected when the plan is a subscription with its own interval, which then sets the terms.

billingIntervalCountinteger

Intervals between invoices (default 1; month with 3 is quarterly). Needs billingInterval.

Response

The issued plan invoice.

idstring required

The plan invoice ID.

object'company_plan_invoice' required
companyIdstring required
planIdstring required
planNamestring nullable required
status'issued' | 'paid' | 'canceled' | 'uncollectible' required

issued: awaiting payment. paid: paid, and the plan was assigned to the company. canceled: canceled before payment. uncollectible: marked uncollectible in Stripe.

amountCentsinteger required

Amount per invoice, in currency minor units.

currencystring required

Lowercase ISO 4217 currency code.

billingInterval'month' | 'year' nullable required

Null for a one-off invoice; otherwise how often it recurs.

billingIntervalCountinteger nullable required

Number of intervals between invoices (3 months = quarterly).

contactEmailstring required

The billing email the invoice is for.

hostedInvoiceUrlstring nullable required

The payment page for the employer. Cavuno does not send the invoice itself; share this link with them.

dueAtstring nullable required

ISO-8601 due date (30 days after issue).

assignmentIdstring nullable required

The plan assignment created when the invoice was paid; null until then.

createdAtstring required

ISO-8601 creation time.

updatedAtstring required

ISO-8601 time of the last change.

Changes