Skip to main content
POST
Deprecated — Cancel a deal
Cancels an open deal: it stops creating invoices. For a PIX Automático or recurring PIX deal, the payer’s authorization is canceled at the bank first; if that fails, the bank’s error is returned (origin BANKING, with its own status and code) and nothing changes. The body is optional: send {}, or no body and no Content-Type. With cancelAllInvoices: true, every invoice of the deal that is not paid or canceled yet is canceled. Otherwise the open invoice is closed — its boleto or PIX charge is issued and it stays payable — and only the closed invoices due more than a month from now are canceled. Paid invoices are never touched. The BILLING_DEAL_CANCELED webhook event is sent (and BILLING_INVOICE_CLOSED for the invoice it closed, or BILLING_INVOICE_PAID when that invoice was already paid in full). Any member of the organization, or an admin of the realm, can cancel one; updatedBy is set to the ID of the authenticated caller. Answers the canceled deal.

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

Format: UUID

​
contractId
string<uuid>
required

ID of the contract the deal belongs to.

Format: UUID

​
dealId
string<uuid>
required

ID of the deal to cancel.

Format: UUID

Body

application/json
​
cancelAllInvoices
boolean

true: cancel every invoice of the deal that is not paid or canceled yet. false or omitted: close the open invoice — it is issued and stays payable — and cancel only the closed invoices due more than a month from now.

Example:

true

Response

Successful response

A deal: what an organization charges a payer for, how and when.

​
id
string<uuid>
required

ID of the deal.

Example:

"9b2f7c1e-4d3a-4f6b-8e2d-1c0b9a8f7e6d"

​
realm
string<uuid>
required

ID of the realm of the organization that issues the deal.

Example:

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

​
organization
string<uuid>
required

ID of the organization that issues the deal.

Example:

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

​
chargeType
enum<string>
required

SINGLE: one invoice. RECURRENT: monthly invoices up to numberOfInstallments months after firstChargeDate. SUBSCRIPTION: one invoice a month until the deal ends, is terminated or is canceled. After the first, each invoice is created when the previous one closes — unless the deal created them all at the start (settings.createAllInvoicesOnStart) — and only while the deal has a RECURRENT product.

Available options:
SINGLE,
RECURRENT,
SUBSCRIPTION
Example:

"RECURRENT"

​
status
enum<string>
required

OPEN: active — it creates invoices and can be changed or canceled. CANCELED: canceled through the API. TERMINATED: it reached its end date (checked daily), its end date was moved to today or earlier, or its contract was terminated. EXPIRED: a PIX Automático or recurring PIX deal whose payer never authorized the payment, a few days after the first due date. REVOKED: the payer revoked the PIX Automático authorization.

Available options:
OPEN,
CANCELED,
TERMINATED,
EXPIRED,
REVOKED
Example:

"CANCELED"

​
firstChargeDate
string<date-time>
required

Due date of the first invoice. The later invoices are due on the same day of each following month.

Example:

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

​
startAt
string<date-time>
required

When the deal starts: when it was created, unless it was changed with PUT.

Example:

"2026-10-26T13:00:00.000Z"

​
endAt
string<date-time> | null
required

When the deal ends. SINGLE: when it was created. RECURRENT: numberOfInstallments months after firstChargeDate. SUBSCRIPTION: the end date you set, or null for no end. Once the end date has passed, a daily routine terminates an OPEN deal.

Example:

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

​
products
object[]
required

What the deal charges for.

​
paymentMethods
enum<string>[]
required

How the invoices are paid: one of BANK_SLIP (boleto), PIX (a PIX charge), P2P (a debit from the payer's Portão 3 wallet), PIX_AUTOMATIC (PIX Automático) or PIX_INITIATION (recurring scheduled PIX).

Example: ["BANK_SLIP"]

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
​
secondaryPaymentMethods
enum<string>[]
required

Other ways the payer can pay the invoices: PIX and/or BANK_SLIP. Empty when there are none.

Example: []

Available options:
BANK_SLIP,
PIX_INITIATION,
PIX_AUTOMATIC,
PIX,
P2P
Example:
​
creditParties
object[]
required

Who receives the money and each one's share.

​
debitParties
object[]
required

Who pays.

​
closingAt
string
required

When each invoice created one at a time closes, as a cron expression 0 0 <day of month> * *: 5 days before firstChargeDate's day, or that same day when settings.disableOpenStatus is true. Invoices created at the start close on their own due date.

Example:

"0 0 5 * *"

​
dueAt
string
required

When each invoice is due, as a cron expression 0 0 <day of month> * *: firstChargeDate's day.

Example:

"0 0 10 * *"

​
createdBy
string
required

ID of who created the deal.

Example:

"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"

​
updatedBy
string
required

ID of who last changed the deal.

Example:

"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"

​
createdAt
string<date-time>
required

When the deal was created.

Example:

"2026-10-26T13:00:00.000Z"

​
updatedAt
string<date-time>
required

When the deal last changed.

Example:

"2026-10-28T09:15:00.000Z"

​
description
string

Description of the deal. It names the invoice of a SINGLE deal, and the invoices created at the start when settings.invoiceNameType is DEAL_DESCRIPTION.

Example:

"Mensalidade Plano Pro"

​
contract
string<uuid>

ID of the contract the deal belongs to. Absent on a deal created without a contract.

Example:

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

​
numberOfInstallments
number

With settings.createAllInvoicesOnStart, how many invoices were created at the start. Otherwise it sets when a RECURRENT deal ends: numberOfInstallments months after firstChargeDate. 1 unless it was sent.

Example:

12

​
settings
object

How the deal creates its invoices.

​
fine
object | null

Fine for late payment. null when the deal has none.

​
interest
object | null

Interest for late payment. null when the deal has none.

​
discount
object | null

Discount for early payment. null when the deal has none.

​
paymentUrl
string

Link where the payer authorizes the payments. Only on PIX_AUTOMATIC and PIX_INITIATION deals.

Example:

"https://pix.example.com/authorize/9b2f7c1e"

​
paymentLinkValidity
string<date-time> | null

Until when paymentUrl can be used. Only on PIX_AUTOMATIC deals; null on PIX_INITIATION deals.

Example:

"2026-11-09T23:59:59.000Z"