---
title: "Cancel a company's plan invoice"
method: POST
path: "/companies/{id}/plan-invoices/{invoiceId}/cancel"
tags: ["Companies"]
---

# Cancel a company's plan invoice

`POST /companies/{id}/plan-invoices/{invoiceId}/cancel`

## Request

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

Cancels a plan invoice awaiting payment, the same as **Cancel invoice** in the company plan dialog: a recurring invoice stops recurring, the Stripe invoice is voided, and the company can be assigned or invoiced again. Canceling an invoice that is already canceled returns it unchanged. Requires an `Idempotency-Key` header and `plans.manage`.

## Path parameters

- `id` string, 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`.
- `invoiceId` string, required: The plan invoice ID returned by the list or create call.

## Response `200`

The plan invoice after the cancel.

- CompanyPlanInvoice
  - `id` string, required: The plan invoice ID.
  - `object` 'company_plan_invoice', required
  - `companyId` string, required
  - `planId` string, required
  - `planName` string, 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.
  - `amountCents` integer, required: Amount per invoice, in currency minor units.
  - `currency` string, required: Lowercase ISO 4217 currency code.
  - `billingInterval` 'month' | 'year', nullable, required: Null for a one-off invoice; otherwise how often it recurs.
  - `billingIntervalCount` integer, nullable, required: Number of intervals between invoices (3 months = quarterly).
  - `contactEmail` string, required: The billing email the invoice is for.
  - `hostedInvoiceUrl` string, nullable, required: The payment page for the employer. Cavuno does not send the invoice itself; share this link with them.
  - `dueAt` string, nullable, required: ISO-8601 due date (30 days after issue).
  - `assignmentId` string, nullable, required: The plan assignment created when the invoice was paid; null until then.
  - `createdAt` string, required: ISO-8601 creation time.
  - `updatedAt` string, required: ISO-8601 time of the last change.

## Other responses

- `404`: Company or plan invoice not found.
- `409`: The invoice is paid or uncollectible, or is still being issued and can be canceled in a few seconds (`company_plan_invoice_not_cancelable`), or Stripe is not connected (`company_plan_invoice_connect_required`).
- `502`: Stripe could not cancel the invoice (`company_plan_invoice_stripe_error`); try again.

## Changes

- **2026-10-20** `de39bd3242e2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/companies/:id/plan-invoices/:invoiceId/cancel/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)