Skip to main content
PUT
Deprecated — Update a deal
Changes an open deal: its description, dates, payment method, closing and due days, or parties. Send only what changes. A new description renames every invoice of the deal. startAt can change only while the deal has no invoice; when it is today, the first invoice is created at once. endAt can’t be after the contract’s end nor before the deal’s start; null removes it when the contract has no end date, and today or earlier terminates the deal at once — its open invoice is closed and issued, and the BILLING_DEAL_TERMINATED webhook event is sent. Parties are replaced as a whole and checked like on create: against the contract, the wallets, the shares adding up to 100, and what the (new or current) payment method needs from the payer. A PIX Automático or recurring PIX deal can’t change its payment method. The products, charge type, settings, fees and installments can’t be changed. 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 deal as changed.

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

Format: UUID

Body

application/json
​
description
string

New description, up to 90 characters. It also renames every invoice of the deal. Omitted or empty: unchanged.

Maximum string length: 90
Example:

"Mensalidade Plano Pro"

​
startAt

New start date (ISO 8601 date or date-time). Only while the deal has no invoice, and not before the contract starts nor before today. When it is today, the deal's first invoice is created at once.

Example:

"2026-11-01"

​
endAt

New end date (ISO 8601 date or date-time), or null to remove it — unless the contract has an end date, which the deal's can't exceed. It can't be before the deal's start date. Today or earlier terminates the deal at once. Omitted: unchanged.

Example:

"2027-11-10"

​
paymentMethods
enum<string>[]

New payment method, exactly one: BANK_SLIP, PIX or P2P. A PIX Automático or recurring PIX deal can't change it. With P2P the payer needs its Portão 3 wallet, with BANK_SLIP or PIX its billing address (see debitParties). Omitted: unchanged.

Example: ["BANK_SLIP"]

Required array length: 1 element
Available options:
BANK_SLIP,
PIX,
P2P
​
closingAt
string

New closing day of the invoices, as a cron expression 0 0 <day> * * with a day from 1 to 28. Omitted or empty: unchanged.

Example:

"0 0 5 * *"

​
dueAt
string

New due day of the invoices, as a cron expression 0 0 <day> * * with a day from 1 to 28. Omitted or empty: unchanged.

Example:

"0 0 10 * *"

​
creditParties
object[]

New receivers. Replaces the whole list; their shares must add up to 100. Omitted: unchanged.

Minimum array length: 1
​
debitParties
object[]

New payer: exactly one. Replaces the stored one — send its wallet again when the deal needs it, and its address when the deal is paid by BANK_SLIP or PIX. When the payer's document is the stored payer's, the contact fields you leave out (phone, name, email, and the address unless you send a new one with its postalCode and street) keep their stored values; a field you send replaces the stored one, and none can be cleared. Omitted: unchanged.

Required array length: 1 element

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:

"OPEN"

​
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-26T13:00: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"