> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Cancel an invoice > Cancels a closed invoice your organization issued. Only a `CLOSED` invoice — issued and not paid yet — can be canceled. A scheduled PIX payment of the invoice is canceled with it; for PIX Automático, once no invoice of the deal is left to pay, the payer's authorization is released too. The first payment of a PIX Automático can only be canceled together with its authorization: cancel the deal instead. A boleto or PIX charge already issued for it is not canceled, and no webhook event is sent. Any member of the organization, or an admin of the realm, can cancel it. Answers the invoice as stored, now `CANCELED`. ## OpenAPI ````yaml /api-reference/billing.openapi.json post /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel openapi: 3.0.3 info: title: Billing version: 1.0.0 description: >- Portão 3 billing API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Full billing surface — contracts, deals, invoices, statements, payment links, checkout and NFSe orchestration. (The product/supplier catalog moved to registry.) Confidence tiers: generated:typed=74 copied:manual=0 unknown=5. servers: - url: https://api.billing.v2.portao3.com.br/ description: production - url: https://api.billing.dev.3pers.com.br/ description: development security: [] tags: - name: Contracts - name: Deals - name: Invoices - name: Invoice Entries - name: Invoice Statements - name: NFSe Configuration - name: Payment Links paths: /realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/cancel: post: tags: - Invoices summary: Cancel an invoice description: Cancels a closed invoice your organization issued. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdInvoicesByInvoiceIdCancel parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: organizationId in: path required: true description: |- ID of your organization: the one that issued the invoice. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: invoiceId in: path required: true description: |- ID of the invoice to cancel. Format: `UUID` schema: type: string format: uuid example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a responses: '200': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the invoice. example: 0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a format: uuid realm: type: string description: >- ID of the realm of the organization that issued the invoice. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the organization that issued the invoice. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid contract: type: string description: >- ID of the invoice's contract. Absent on an invoice of a deal created without a contract. example: 7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d format: uuid deal: type: string description: >- ID of the deal that generated the invoice. Read the deal with `GET .../deals/{dealId}`. example: 3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f format: uuid previousInvoiceId: type: string description: >- Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept. example: '' dealName: type: string description: The deal's description. Empty when the invoice has none. example: Mensalidade Plano Pro description: type: string description: >- The invoice's name. Empty when it has none (show `dealName` instead). example: Mensalidade Plano Pro - 1/12 allowedPaymentMethods: type: array items: type: string enum: - BANK_SLIP - PIX_INITIATION - PIX_AUTOMATIC - PIX - P2P example: PIX_AUTOMATIC description: >- How the invoice can be paid: `BANK_SLIP` (boleto), `PIX` (PIX charge), `PIX_AUTOMATIC` (PIX Automático), `PIX_INITIATION` (recurring scheduled PIX) or `P2P` (a debit from the payer's Portão 3 account). The first one is the deal's main method. --- Example: `["PIX_AUTOMATIC","PIX"]` invoiceNumber: type: integer description: The installment number, from 1. example: 1 closingAt: type: string description: >- When the invoice closes: it stops gathering charges and its payment is issued. example: '2026-10-01T00:00:00.000Z' format: date-time dueAt: type: string description: When the invoice is due. example: '2026-10-10T00:00:00.000Z' format: date-time expiresAt: type: string description: The last day the invoice's charge can be paid. example: '2026-11-10T00:00:00.000Z' format: date-time paidAt: type: string description: When the invoice was paid. Absent until it is. example: '2026-10-08T14:32:11.000Z' format: date-time amount: type: integer description: >- Amount of the invoice, in centavos (`15000` is R$ 150,00): the sum of its charges. example: 15000 status: type: string enum: - OPEN - CLOSED - PAID - CANCELED description: >- The stored status. `OPEN`: still gathering charges. `CLOSED`: issued and waiting for payment. `PAID`. `CANCELED`. example: CANCELED displayStatus: type: string enum: - OPEN - READY_TO_PAYMENT - OVERDUE - PAID - CANCELED - READY_TO_SCHEDULE - SCHEDULED - PAYMENT_FAILED - REVOKED - EXPIRED description: >- The invoice's status as the Portão 3 app shows it, computed when you read it — the same rule on every invoice route. `OPEN`: still gathering charges. `READY_TO_PAYMENT`: issued, and less than a day past its due date. `OVERDUE`: issued, and more than a day past its due date (for PIX Automático, after the 5-day retry window). `PAID`. `CANCELED`. Only for PIX Automático: `READY_TO_SCHEDULE` (the payment is not scheduled with the payer's bank yet), `SCHEDULED` (it will be charged on the due date), `PAYMENT_FAILED` (the due-date charge did not go through and is being retried, until 5 days after the due date), `REVOKED` (canceled because the payer revoked the authorization) and `EXPIRED` (canceled because the payer never authorized it). example: CANCELED paymentStatus: type: string enum: - NONE - PENDING - PROCESSING - PROCESSED - FAILED description: >- Progress of the automatic charge from the payer's Portão 3 account (P2P). `NONE` for every other invoice. example: NONE paymentsAttempts: type: integer description: How many times the automatic P2P charge was attempted. example: 0 fine: type: object properties: amountType: type: string description: >- How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount). example: PERCENT amount: type: number description: >- The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others. example: 2 required: - amountType - amount description: >- Late fee charged after the due date, when the deal has one. interest: type: object properties: amountType: type: string description: >- How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount). example: PERCENT amount: type: number description: >- The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others. example: 2 required: - amountType - amount description: Interest charged after the due date, when the deal has it. discount: type: object properties: amountType: type: string description: >- How `amount` is read. A fine: `FIXED_VALUE` (centavos) or `PERCENT` (of the invoice amount). Interest: `AMOUNT_CALENDAR_DAYS` / `AMOUNT_WORKING_DAYS` (centavos per day late) or `PERCENT_POINT_PER_DAY_CALENDAR_DAYS` / `PERCENT_POINT_PER_DAY_WORKING_DAYS` (percent per day late), counting calendar or working days. A discount: `AMOUNT_PER_ANTECIPATION` (centavos) or `PERCENT_PER_ANTECIPATION` (of the invoice amount). example: PERCENT amount: type: number description: >- The value, in the unit `amountType` gives: centavos for the `FIXED_VALUE` and `AMOUNT_*` types, a percentage for the others. example: 2 required: - amountType - amount description: Discount for paying early, when the deal has one. external: type: object properties: b3BankSlip: type: string description: ID of the boleto created for the invoice. example: 4c9e2f1a-7b3d-4e5f-8a6b-0c1d2e3f4a5b b3Pix: type: string description: ID of the PIX charge created for the invoice. example: 6d1a3b5c-8e2f-4a7b-9c0d-1e2f3a4b5c6d description: IDs of the invoice's boleto and PIX charge, once created. creditParties: type: array items: type: object properties: partyAccount: type: object properties: document: type: string description: CPF or CNPJ, digits only. example: '12345678000195' name: type: string example: Empresa Exemplo Ltda email: type: string example: financeiro@empresaexemplo.com.br bank: type: string enum: - P3 description: >- Where the party's account is held. `P3`: a Portão 3 account. example: P3 type: type: string enum: - WALLET description: 'Kind of account. `WALLET`: a Portão 3 wallet.' example: WALLET identifier: type: object properties: realm: type: string description: ID of the party's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the party's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the party's account. example: 2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d format: uuid wallet: type: string description: ID of the party's wallet. example: 8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b format: uuid required: - realm - organization - account - wallet description: The account and wallet the money is paid into. required: - name - bank - type - identifier description: Who receives the invoice's money. unit: type: string enum: - PERCENTAGE description: >- `PERCENTAGE`: `amount` is a share of the invoice amount, in percent. example: PERCENTAGE amount: type: number description: >- The receiver's share. The shares of all receivers add up to 100. example: 100 required: - partyAccount - unit - amount description: A share of the invoice that goes to one receiver. description: >- Who receives the money. Absent when you read the invoice as its payer (`role=BUYER`). debitParties: type: array items: type: object properties: partyAccount: type: object properties: document: type: string description: CPF or CNPJ, digits only. example: '11144477735' name: type: string example: Maria Silva email: type: string example: maria.silva@exemplo.com.br address: type: object properties: street: type: string example: Rua das Flores number: type: string example: '123' complement: type: string example: Sala 4 neighborhood: type: string example: Centro city: type: string example: São Paulo state: type: string description: Two-letter state code. example: SP postalCode: type: string description: Postal code (CEP), as `NNNNN-NNN`. example: 01310-100 required: - street - number - neighborhood - city - state - postalCode description: >- The payer's address. Present when the invoice is paid by boleto or PIX charge. bank: type: string enum: - P3 description: >- Where the payer's account is held, when the payer pays from a Portão 3 account (`P3`). example: P3 type: type: string enum: - WALLET description: >- Kind of the payer's account, when it is a Portão 3 wallet (`WALLET`). example: WALLET identifier: type: object properties: realm: type: string description: ID of the party's realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the party's organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the party's account. example: 2a7d9c4e-5b1f-4e3a-8c6d-9f0e1a2b3c4d format: uuid wallet: type: string description: ID of the party's wallet. example: 8e1f2a3b-4c5d-4e6f-9a0b-1c2d3e4f5a6b format: uuid required: - realm - organization - account - wallet description: >- The payer's Portão 3 account and wallet, when the invoice is paid from one (P2P). required: - name description: Who pays the invoice. unit: type: string enum: - PERCENTAGE description: >- `PERCENTAGE`: `amount` is a share of the invoice amount, in percent. example: PERCENTAGE amount: type: number description: >- The payer's share: always 100 (an invoice has one payer). example: 100 required: - partyAccount - unit - amount description: The invoice's payer and its share. description: 'Who pays: one payer.' createdBy: type: string description: >- Who created the invoice: the caller of the API, or the Portão 3 service that generated it from its deal. example: BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f updatedBy: type: string description: Who last changed the invoice. example: BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f createdAt: type: string description: When the invoice was created. example: '2026-09-01T00:00:00.000Z' format: date-time updatedAt: type: string description: >- When the invoice was created. It does not move when the invoice changes. example: '2026-09-01T00:00:00.000Z' format: date-time required: - id - realm - organization - deal - previousInvoiceId - dealName - description - allowedPaymentMethods - invoiceNumber - closingAt - dueAt - expiresAt - amount - status - displayStatus - paymentStatus - paymentsAttempts - external - debitParties - createdBy - updatedBy - createdAt - updatedAt description: An invoice. '400': description: >- `INVOICE_NOT_CLOSED` — The invoice is open, paid or already canceled. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INVOICE_NOT_CLOSED description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INVOICE_NOT_CLOSED origin: BILLING message: Only closed invoices can be canceled '403': description: >- `INSUFFICIENT_PERMISSIONS` — You are not a member of the organization nor an admin of the realm. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INSUFFICIENT_PERMISSIONS description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INSUFFICIENT_PERMISSIONS origin: BILLING message: insufficient permissions '404': description: >- `INVOICE_NOT_FOUND` — The organization issued no invoice with this ID. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - INVOICE_NOT_FOUND description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: INVOICE_NOT_FOUND origin: BILLING message: invoice not found '422': description: >- `PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE` — The invoice is the first payment of a PIX Automático whose authorization is still pending. `BAD_REQUEST` — A path parameter is not a valid ID; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BILLING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: PIX_AUTOMATIC_FIRST_PAYMENT_NOT_CANCELABLE origin: BILLING message: >- The first payment of a PIX Automático can only be canceled together with its consent. Cancel the deal instead. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.