Skip to main content
POST
Create an invoice
The deal must be open. Its RECURRENT products become the invoice’s entries — and its ONE_TIME products too when there is no previousInvoiceId — and the invoice amount is their sum. Without invoiceNumber, the invoice is the deal’s next installment. When the deal closes its invoices on creation (settings.disableOpenStatus), or it is a SUBSCRIPTION deal whose closingAt is today or earlier, the invoice is closed at once and its boleto or PIX charge is issued. The BILLING_INVOICE_CREATED webhook event is sent (BILLING_INVOICE_CLOSED when it closes at once). A request sent twice creates two invoices. Only the fields below are read; any other one is ignored — the status, the amount and the payment state always start fresh. Any member of the organization, or an admin of the realm, can create one; createdBy and updatedBy are 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 issues the invoice.

Format: UUID

Body

application/json
​
deal
string<uuid>
required

ID of the deal the invoice belongs to. The deal must be OPEN; its products become the invoice's entries.

Format: UUID

Example:

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

​
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 main method.

Example: ["BANK_SLIP","PIX"]

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

When the invoice closes — stops gathering charges and issues its payment (ISO 8601 date or date-time).

Minimum string length: 1
Example:

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

​
dueAt
required

When the invoice is due (ISO 8601 date or date-time).

Minimum string length: 1
Example:

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

​
expiresAt
required

The last day the invoice's charge can be paid (ISO 8601 date or date-time).

Minimum string length: 1
Example:

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

​
creditParties
object[]
required

Who receives the money: one or more receivers.

Minimum array length: 1
​
debitParties
object[]
required

Who pays: exactly one payer.

Required array length: 1 element
​
description
string

The invoice's name. Up to 100 characters.

Maximum string length: 100
Example:

"Mensalidade Plano Pro - 1/12"

​
invoiceNumber
integer

The installment number. Omit it for the next number of the deal.

Required range: x >= 1
Example:

1

​
previousInvoiceId
string<uuid>

ID of the deal's previous invoice, for an installment after the first. Without it, the deal's one-time products are charged too. It is not kept: the invoice answers it empty.

Format: UUID

Example:

"1c8d3b55-7a2f-4e4c-8b9f-6d3a2e1f0c8b"

​
fine
object | null

Late fee charged after the due date.

​
interest
object | null

Interest charged after the due date.

​
discount
object | null

Discount for paying before the due date.

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