Add entries to an invoice
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries \
--header 'Content-Type: application/json' \
--data '
{
"entries": [
{
"identifier": "SETUP_FEE",
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"amount": 15000,
"description": "Taxa de instalação"
}
]
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries"
payload = { "entries": [
{
"identifier": "SETUP_FEE",
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"amount": 15000,
"description": "Taxa de instalação"
}
] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
entries: [
{
identifier: 'SETUP_FEE',
chargeMethod: 'LATER',
productType: 'ON_EVENT',
amount: 15000,
description: 'Taxa de instalação'
}
]
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entries' => [
[
'identifier' => 'SETUP_FEE',
'chargeMethod' => 'LATER',
'productType' => 'ON_EVENT',
'amount' => 15000,
'description' => 'Taxa de instalação'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries"
payload := strings.NewReader("{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries")
.header("Content-Type", "application/json")
.body("{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body[
{
"id": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90",
"identifier": "SETUP_FEE",
"invoice": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
"amount": 15000,
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"effectiveAt": "2026-10-01T09:00:00.000Z",
"external": {
"transaction": "6711b4c0d8e1a30012b7c9f2"
},
"description": "Taxa de instalação",
"status": "OPEN",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}
]{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_FOUND",
"origin": "BILLING",
"message": "invoice not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_OPEN",
"origin": "BILLING",
"message": "invoice is not open for changes"
}Add entries to an invoice
Adds charges (line items) to an open invoice your organization issued: an on-demand charge for the invoice’s period, on top of the entries generated from the deal’s products.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
invoices
/
{invoiceId}
/
entries
Add entries to an invoice
curl --request POST \
--url https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries \
--header 'Content-Type: application/json' \
--data '
{
"entries": [
{
"identifier": "SETUP_FEE",
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"amount": 15000,
"description": "Taxa de instalação"
}
]
}
'import requests
url = "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries"
payload = { "entries": [
{
"identifier": "SETUP_FEE",
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"amount": 15000,
"description": "Taxa de instalação"
}
] }
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
entries: [
{
identifier: 'SETUP_FEE',
chargeMethod: 'LATER',
productType: 'ON_EVENT',
amount: 15000,
description: 'Taxa de instalação'
}
]
})
};
fetch('https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'entries' => [
[
'identifier' => 'SETUP_FEE',
'chargeMethod' => 'LATER',
'productType' => 'ON_EVENT',
'amount' => 15000,
'description' => 'Taxa de instalação'
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries"
payload := strings.NewReader("{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries")
.header("Content-Type", "application/json")
.body("{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.billing.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/invoices/{invoiceId}/entries")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"entries\": [\n {\n \"identifier\": \"SETUP_FEE\",\n \"chargeMethod\": \"LATER\",\n \"productType\": \"ON_EVENT\",\n \"amount\": 15000,\n \"description\": \"Taxa de instalação\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body[
{
"id": "3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90",
"identifier": "SETUP_FEE",
"invoice": "0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a",
"amount": 15000,
"chargeMethod": "LATER",
"productType": "ON_EVENT",
"effectiveAt": "2026-10-01T09:00:00.000Z",
"external": {
"transaction": "6711b4c0d8e1a30012b7c9f2"
},
"description": "Taxa de instalação",
"status": "OPEN",
"createdBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"updatedBy": "5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b",
"createdAt": "2026-10-01T09:00:00.000Z",
"updatedAt": "2026-10-01T09:00:00.000Z"
}
]{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "BILLING",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_FOUND",
"origin": "BILLING",
"message": "invoice not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INVOICE_NOT_OPEN",
"origin": "BILLING",
"message": "invoice is not open for changes"
}Each entry’s
amount is added to the invoice amount, so the invoice must be OPEN: a closed, paid or canceled invoice refuses the request with INVOICE_NOT_OPEN. Send from 1 to 50 entries; they are created together, in the order sent. A field that is not documented is ignored and never stored. createdBy and updatedBy are set to the ID of the authenticated caller; they can’t be sent in the body.
An entry whose chargeMethod is INSTANT is also charged to the payer’s Portão 3 account right away, as a P2P payment of its amount, when P2P is enabled for your organization. That charge is attempted after the entries are saved and its outcome is not reported: a 201 does not mean the payer was charged. When the charge fails the entry stays on the invoice; check the invoice’s statements to see which payments were created.
Any member of the organization, or an admin of the realm, can add entries. Answers the entries it created.Path Parameters
ID of your realm.
Format: UUID
ID of the organization that issued the invoice.
Format: UUID
ID of the invoice the entries are added to.
Format: UUID
Body
application/json
The charges to add, from 1 to 50 per request.
Required array length:
1 - 50 elementsShow child attributes
Show child attributes
Response
Successful response
ID of the entry.
Example:
"3f9a1c2e-7b4d-4e8a-9c1f-2d5b6a7c8e90"
What the charge is for: the identifier of the deal product that generated the entry, or the label sent when it was added through the API. Free text.
Example:
"SETUP_FEE"
ID of the invoice the entry belongs to.
Example:
"0b7c2a44-6f1e-4d3b-9a8e-5c2f1d0e9b7a"
Amount of the charge in centavos (15000 is R$ 150,00). It counts toward the invoice amount while the entry is OPEN.
Example:
15000
When the charge is collected. LATER: it is added to the invoice and paid with it. INSTANT: it is also debited from the payer's Portão 3 account as soon as it is added.
Available options:
INSTANT, LATER Example:
"LATER"
When the charge's product is billed. RECURRENT: on every invoice of the deal. ONE_TIME: on the first invoice only. ON_EVENT: never automatically; such an entry is added through the API, when the event happens.
Available options:
RECURRENT, ONE_TIME, ON_EVENT Example:
"ON_EVENT"
When the entry took effect: the moment it was created.
Example:
"2026-10-01T09:00:00.000Z"
References of the entry outside the invoice.
Show child attributes
Show child attributes
Free text describing the charge. Empty when there is none.
Example:
"Taxa de instalação"
OPEN: the entry counts toward the invoice amount. DELETED: the entry was deleted and no longer counts.
Available options:
OPEN, DELETED Example:
"OPEN"
ID of who created the entry: the authenticated caller of the API that added it, or the Portão 3 service that generated it from the deal.
Example:
"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"
ID of who last changed the entry: who created it, until someone deletes it.
Example:
"5f0c2b1e-8a3d-4e6f-9b7c-2d1a0e9f8c7b"
When the entry was created. Entries added in the same request are one minute apart, in the order they were sent, so that a listing keeps that order.
Example:
"2026-10-01T09:00:00.000Z"
When the entry was last changed. Deleting an entry does not refresh it.
Example:
"2026-10-01T09:00:00.000Z"