> ## Documentation Index
> Fetch the complete documentation index at: https://commet.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update invoice status

> Mark an outstanding invoice as "paid" or "void" and return the updated invoice. Cannot change the status of already paid or voided invoices.

Mark an outstanding invoice as "paid" or "void" and return the updated invoice. Cannot change the status of already paid or voided invoices.


## OpenAPI

````yaml /openapi/es/rest/2026-08-27.json patch /invoices/{id}/status
openapi: 3.1.0
info:
  title: Commet API
  version: '2026-08-27'
  description: Billing and payments API for SaaS and AI products.
servers:
  - url: https://commet.co/api/v1
security:
  - ApiKeyAuth: []
tags:
  - name: Test Clock
    description: >-
      Simulate the passage of time in sandbox to test billing flows. Mirrors
      Stripe test clocks: forward-only and sandbox-only.
  - name: Customers
  - name: Subscriptions
  - name: Plans
  - name: Markets
    description: >-
      Reusable country groups for market-specific prices and selectable price
      variants.
  - name: Offers
  - name: Promo Codes
  - name: Features
  - name: Usage
  - name: Seats
  - name: Quota
  - name: Add-ons
  - name: Portal
  - name: Credit Packs
  - name: Plan Groups
  - name: Invoices
  - name: Payments
    description: >-
      One-time payments with no subscription or plan. Charge a customer's saved
      payment method off-session, or create a payment link the customer opens to
      pay. Tax, invoice, and receipt are handled automatically.
  - name: Transactions
  - name: Webhooks
  - name: API Keys
  - name: Payouts
    description: >-
      Withdraw available balance to your bank and manage the payout account
      (verification + destination bank accounts).
  - name: Provisioning
    description: >-
      Take ownership of an organization an agent provisioned headlessly. The
      agent holds the API keys from the start; a human claims the account
      through a claim link.
paths:
  /invoices/{id}/status:
    patch:
      tags:
        - Invoices
      summary: Update invoice status
      description: >-
        Mark an outstanding invoice as "paid" or "void" and return the updated
        invoice. Cannot change the status of already paid or voided invoices.
      operationId: update-invoice-status
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Unique key used to safely retry this write for 24 hours without
            applying it twice.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: Commet-Version
          in: header
          required: false
          description: >-
            API version used by this reference. Send this header to select this
            contract explicitly.
          schema:
            type: string
            default: '2026-08-27'
          example: '2026-08-27'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - paid
                    - void
              required:
                - status
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Invoice'
              example:
                id: inv_1a2b3c4d
                customerId: cus_1a2b3c4d
                subscriptionId: sub_1a2b3c4d
                invoiceNumber: INV-2026-0001
                status: paid
                invoiceType: recurring
                currency: usd
                subtotal: 2000
                discountAmount: 0
                taxAmount: 0
                total: 2000
                periodStart: '2026-09-07T12:00:00.000Z'
                periodEnd: '2026-10-07T12:00:00.000Z'
                issueDate: '2026-09-07T12:00:00.000Z'
                dueDate: '2026-09-07T12:00:00.000Z'
                memo: null
                metadata: {}
                createdAt: '2026-09-07T12:00:00.000Z'
                updatedAt: '2026-09-07T12:00:00.000Z'
                creditApplied: 0
                planName: Pro
                poNumber: null
                reference: null
                lineItems:
                  - lineType: plan_base
                    featureName: null
                    description: Pro — monthly subscription
                    quantity: 1
                    unitAmount: 2000
                    amount: 2000
                    includedAmount: null
                    usedAmount: null
                    overageAmount: null
                    discountType: null
                    discountValue: null
                    discountName: null
                    chargeType: standard
                object: invoice
                livemode: false
        '400':
          description: Bad request
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: validation_error
                  code: validation_error
                  message: The request contains an invalid parameter.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md
        '401':
          description: Unauthorized
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: authentication_error
                  code: unauthorized
                  message: A valid API key is required.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md
        '403':
          description: Forbidden
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: authentication_error
                  code: forbidden
                  message: You do not have permission to perform this operation.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md
        '404':
          description: Not found
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: not_found_error
                  code: not_found
                  message: The requested resource was not found.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md
        '409':
          description: Conflict
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: conflict_error
                  code: idempotency_in_progress
                  message: >-
                    A request with this idempotency key is still being
                    processed.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md
        '429':
          description: Too many requests
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            RateLimit-Limit:
              description: Maximum number of requests allowed in the current window.
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: string
            RateLimit-Reset:
              description: Seconds until the rate limit window resets.
              schema:
                type: string
            Retry-After:
              description: Seconds to wait before retrying the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: rate_limit_error
                  code: rate_limited
                  message: >-
                    Too many requests. Retry after the interval specified in the
                    Retry-After header.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md
        '500':
          description: Internal server error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: internal_error
                  code: internal_error
                  message: An unexpected error occurred while processing the request.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md
        '503':
          description: Service unavailable
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  type: internal_error
                  code: idempotency_unavailable
                  message: >-
                    Idempotency storage is temporarily unavailable. Retry with
                    the same idempotency key.
                  doc_url: >-
                    https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md
      x-codeSamples:
        - lang: typescript
          label: TypeScript
          source: |-
            import { Commet } from "@commet/node";

            const commet = new Commet({ apiKey: "ck_xxx" });

            const invoice = await commet.invoices.updateStatus({
              id: "inv_xxx",
              status: "paid",
            });
        - lang: python
          label: Python
          source: |-
            from commet import Commet

            commet = Commet("ck_xxx")

            invoice = commet.invoices.update_status(
                "inv_xxx",
                status="paid",
            )
        - lang: go
          label: Go
          source: "client, err := commet.New(\"ck_xxx\")\nif err != nil {\n\tlog.Fatal(err)\n}\nctx := context.Background()\n\ninvoice, err := client.Invoices.UpdateStatus(ctx, \"inv_xxx\", &commet.UpdateInvoiceStatusParams{\n\tStatus: \"paid\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}"
        - lang: java
          label: Java
          source: |-
            import co.commet.Commet;
            import co.commet.params.UpdateInvoiceStatusParams;

            var commet = Commet.builder().apiKey("ck_xxx").build();

            var invoice = commet.invoices().updateStatus(
                "inv_xxx",
                UpdateInvoiceStatusParams.builder("paid").build()
            );
        - lang: php
          label: PHP
          source: |-
            use Commet\Commet;

            $commet = new Commet('ck_xxx');

            $invoice = $commet->invoices->updateStatus(
                id: 'inv_xxx',
                status: 'paid',
            );
components:
  headers:
    RequestId:
      description: >-
        Server-generated identifier that correlates this response with Platform
        logs.
      schema:
        type: string
        format: uuid
  schemas:
    Invoice:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        subscriptionId:
          anyOf:
            - type: string
            - type: 'null'
        invoiceNumber:
          type: string
        status:
          type: string
          enum:
            - draft
            - outstanding
            - paid
            - void
            - uncollectible
        invoiceType:
          $ref: '#/components/schemas/InvoiceType'
        currency:
          type: string
        subtotal:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        discountAmount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        taxAmount:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        total:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        periodStart:
          type: string
          format: date-time
        periodEnd:
          type: string
          format: date-time
        issueDate:
          type: string
          format: date-time
        dueDate:
          type: string
          format: date-time
        memo:
          anyOf:
            - type: string
            - type: 'null'
        metadata:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        creditApplied:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        planName:
          anyOf:
            - type: string
            - type: 'null'
        poNumber:
          anyOf:
            - type: string
            - type: 'null'
        reference:
          anyOf:
            - type: string
            - type: 'null'
        lineItems:
          type: array
          items:
            type: object
            properties:
              lineType:
                type: string
                enum:
                  - plan_base
                  - feature_overage
                  - feature_seats
                  - feature_quota
                  - discount
                  - promo_code_discount
                  - credit
                  - balance_overage
                  - addon_base
                  - one_time
              featureName:
                anyOf:
                  - type: string
                  - type: 'null'
              description:
                type: string
              quantity:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              unitAmount:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              amount:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              includedAmount:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              usedAmount:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              overageAmount:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              discountType:
                anyOf:
                  - type: string
                  - type: 'null'
              discountValue:
                anyOf:
                  - type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  - type: 'null'
              discountName:
                anyOf:
                  - type: string
                  - type: 'null'
              chargeType:
                type: string
                enum:
                  - standard
                  - advance
                  - true_up
            required:
              - lineType
              - featureName
              - description
              - quantity
              - unitAmount
              - amount
              - includedAmount
              - usedAmount
              - overageAmount
              - discountType
              - discountValue
              - discountName
              - chargeType
            additionalProperties: false
        object:
          type: string
          const: invoice
        livemode:
          type: boolean
      required:
        - id
        - customerId
        - subscriptionId
        - invoiceNumber
        - status
        - invoiceType
        - currency
        - subtotal
        - discountAmount
        - taxAmount
        - total
        - periodStart
        - periodEnd
        - issueDate
        - dueDate
        - memo
        - metadata
        - createdAt
        - updatedAt
        - creditApplied
        - planName
        - poNumber
        - reference
        - lineItems
        - object
        - livemode
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            code:
              type: string
            message:
              type: string
            param:
              type: string
            details: {}
            doc_url:
              type: string
          required:
            - type
            - code
            - message
            - doc_url
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    InvoiceType:
      type: string
      enum:
        - recurring
        - overage
        - plan_change
        - adjustment
        - credit_purchase
        - balance_topup
        - addon_activation
        - one_time_payment
        - reactivation
        - resume
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

## Related topics

- [invoice.overdue](/docs/es/webhooks/invoice-overdue.md)
- [List invoices](/docs/es/api-reference/invoices/list-invoices.md)
- [Update plan feature](/docs/es/api-reference/plans/update-plan-feature.md)
- [Update credit pack](/docs/es/api-reference/credit-packs/update-credit-pack.md)
- [Update promo code](/docs/es/api-reference/promo-codes/update-promo-code.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.