Skip to main content
PUT
Update an invoice
Send only what changes: every field is optional, and an omitted one keeps its value. creditParties and debitParties replace the whole side they describe, and each side’s shares must add up to 100. When you send allowedPaymentMethods, the payer — the one sent with it, or else the current one — must have what those methods need. Only an OPEN invoice can be changed: once it closes, its boleto or PIX charge is already issued. The invoice amount and its entries don’t change here — add or delete entries for that. Any member of the organization, or an admin of the realm, can change it; updatedBy is set to the ID of the authenticated caller. Answers the invoice as stored.

Path Parameters

​
realmId
string<uuid>
required

ID of your realm.

Format: UUID

​
organizationId
string<uuid>
required

ID of your organization: the one that issued the invoice.

Format: UUID

​
invoiceId
string<uuid>
required

ID of the invoice.

Format: UUID

Body

application/json
​
allowedPaymentMethods
enum<string>[]

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 main method. Omit it to keep the current ones.

Example: ["BANK_SLIP","PIX"]

Minimum array length: 1
Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
closingAt

When the invoice closes (ISO 8601 date or date-time). Omit it to keep the current one.

Minimum string length: 1
Example:

"2026-10-01T00:00:00.000Z"

​
dueAt

When the invoice is due (ISO 8601 date or date-time). Omit it to keep the current one.

Minimum string length: 1
Example:

"2026-10-10T00:00:00.000Z"

​
expiresAt

The last day the invoice's charge can be paid (ISO 8601 date or date-time). Omit it to keep the current one.

Minimum string length: 1
Example:

"2026-11-10T00:00:00.000Z"

​
creditParties
object[]

Who receives the money — replaces every receiver. Omit it to keep the current ones.

Minimum array length: 1
​
debitParties
object[]

Who pays: exactly one payer — replaces the current one. Omit it to keep it.

Required array length: 1 element

Response

Successful response

An invoice.

​
id
string<uuid>
required

ID of the invoice.

Example:

"0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a"

​
realm
string<uuid>
required

ID of the realm of the organization that issued the invoice.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

​
organization
string<uuid>
required

ID of the organization that issued the invoice.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

​
deal
string<uuid>
required

ID of the deal that generated the invoice. Read the deal with GET .../deals/{dealId}.

Example:

"3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

​
previousInvoiceId
string
required

Always empty. The previous invoice sent on creation only decides which products are charged, and is not kept.

Example:

""

​
dealName
string
required

The deal's description. Empty when the invoice has none.

Example:

"Mensalidade Plano Pro"

​
description
string
required

The invoice's name. Empty when it has none (show dealName instead).

Example:

"Mensalidade Plano Pro - 1/12"

​
allowedPaymentMethods
enum<string>[]
required

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"]

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
invoiceNumber
integer
required

The installment number, from 1.

Example:

1

​
closingAt
string<date-time>
required

When the invoice closes: it stops gathering charges and its payment is issued.

Example:

"2026-10-01T00:00:00.000Z"

​
dueAt
string<date-time>
required

When the invoice is due.

Example:

"2026-10-10T00:00:00.000Z"

​
expiresAt
string<date-time>
required

The last day the invoice's charge can be paid.

Example:

"2026-11-10T00:00:00.000Z"

​
amount
integer
required

Amount of the invoice, in centavos (15000 is R$ 150,00): the sum of its charges.

Example:

15000

​
status
enum<string>
required

The stored status. OPEN: still gathering charges. CLOSED: issued and waiting for payment. PAID. CANCELED.

Available options:
OPEN,
CLOSED,
PAID,
CANCELED
Example:

"OPEN"

​
displayStatus
enum<string>
required

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).

Available options:
OPEN,
READY_TO_PAYMENT,
OVERDUE,
PAID,
CANCELED,
READY_TO_SCHEDULE,
SCHEDULED,
PAYMENT_FAILED,
REVOKED,
EXPIRED
Example:

"OPEN"

​
paymentStatus
enum<string>
required

Progress of the automatic charge from the payer's Portão 3 account (P2P). NONE for every other invoice.

Available options:
NONE,
PENDING,
PROCESSING,
PROCESSED,
FAILED
Example:

"NONE"

​
paymentsAttempts
integer
required

How many times the automatic P2P charge was attempted.

Example:

0

​
external
object
required

IDs of the invoice's boleto and PIX charge, once created.

​
debitParties
object[]
required

Who pays: one payer.

​
createdBy
string
required

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
string
required

Who last changed the invoice.

Example:

"BILLING:DEAL:3b9f6d2e-1a4c-4e8b-9f7a-6c5d4e3b2a1f"

​
createdAt
string<date-time>
required

When the invoice was created.

Example:

"2026-09-01T00:00:00.000Z"

​
updatedAt
string<date-time>
required

When the invoice was created. It does not move when the invoice changes.

Example:

"2026-09-01T00:00:00.000Z"

​
contract
string<uuid>

ID of the invoice's contract. Absent on an invoice of a deal created without a contract.

Example:

"7e4c2a1b-6d5f-4b3a-9e8d-2f1c0b9a8e7d"

​
paidAt
string<date-time>

When the invoice was paid. Absent until it is.

Example:

"2026-10-08T14:32:11.000Z"

​
fine
object

Late fee charged after the due date, when the deal has one.

​
interest
object

Interest charged after the due date, when the deal has it.

​
discount
object

Discount for paying early, when the deal has one.

​
creditParties
object[]

Who receives the money. Absent when you read the invoice as its payer (role=BUYER).