Update Delivery Tracking

PUT

transactions

{id}

delivery

curl --request PUT \
  --url https://api.pagou.ai/v2/transactions/{id}/delivery \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tracking_code": "BR123456789BR",
  "delivery_status": "in_transit",
  "tracking_url": "https://tracking.carrier.com/BR123456789BR",
  "tracking_company": "Correios"
}
'

import requests

url = "https://api.pagou.ai/v2/transactions/{id}/delivery"

payload = {
    "tracking_code": "BR123456789BR",
    "delivery_status": "in_transit",
    "tracking_url": "https://tracking.carrier.com/BR123456789BR",
    "tracking_company": "Correios"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tracking_code: 'BR123456789BR',
    delivery_status: 'in_transit',
    tracking_url: 'https://tracking.carrier.com/BR123456789BR',
    tracking_company: 'Correios'
  })
};

fetch('https://api.pagou.ai/v2/transactions/{id}/delivery', 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.pagou.ai/v2/transactions/{id}/delivery",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'tracking_code' => 'BR123456789BR',
    'delivery_status' => 'in_transit',
    'tracking_url' => 'https://tracking.carrier.com/BR123456789BR',
    'tracking_company' => 'Correios'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.pagou.ai/v2/transactions/{id}/delivery"

	payload := strings.NewReader("{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.put("https://api.pagou.ai/v2/transactions/{id}/delivery")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/transactions/{id}/delivery")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "status": "waiting",
    "code": "string",
    "url": "string",
    "company": "string",
    "last_update": "2026-07-14T12:00:00.000Z"
  }
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Set or update delivery tracking information on a paid transaction. Use the transaction UUID returned as id in the path. Authenticate with your company API key (Bearer, API key, or Basic auth). Once set, the tracking data appears on Get a Transaction under the transaction’s delivery fields.

Request fields

The body is JSON with snake_case fields:

Field	Type	Required	Constraints
`tracking_code`	string	Yes	Trimmed, 1–255 chars, no ASCII control characters.
`delivery_status`	enum	No	One of `waiting`, `in_transit`, `delivered`. Defaults to `in_transit` on first set.
`tracking_url`	string \| null	No	Trimmed, max 255 chars, must start with `http://` or `https://`.
`tracking_company`	string \| null	No	Trimmed, 1–64 chars.

Omit vs. null semantics

Omit an optional field to leave its current value unchanged.
Send null for tracking_url or tracking_company to clear a previously set value.
When delivery_status is omitted, the existing status is preserved on update, or defaults to in_transit the first time delivery is set.
A shipment already marked delivered cannot be moved back to waiting or in_transit (returns 409).

Idempotency and concurrency

PUT is idempotent — repeating the same request produces the same delivery state. For optimistic concurrency, send the transaction ETag in an If-Match header; a stale ETag returns 412 Precondition Failed.

Errors

Status	Meaning
`400`	Malformed request.
`401`	Missing or invalid credentials.
`404`	Transaction not found for this company.
`409`	Invalid status transition (e.g. moving a `delivered` shipment back).
`412`	`If-Match` ETag mismatch.
`422`	Validation failed (field constraints not met).
`429`	Rate limit exceeded.

Example

curl -X PUT "https://api.pagou.ai/v2/transactions/{id}/delivery" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_code": "BR123456789BR",
    "delivery_status": "in_transit",
    "tracking_url": "https://tracking.carrier.com/BR123456789BR",
    "tracking_company": "Correios"
  }'

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "status": "in_transit",
    "code": "BR123456789BR",
    "url": "https://tracking.carrier.com/BR123456789BR",
    "company": "Correios",
    "last_update": "2026-07-14T12:00:00.000Z"
  }
}

The updated tracking then appears on GET /v2/transactions/{id}.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

Pattern:

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Body

application/json

tracking_code

string

required

Carrier tracking code for the shipment. Required.

Required string length: 1 - 255

Example:

"BR123456789BR"

delivery_status

enum<string>

Delivery status of the shipment. One of waiting, in_transit, or delivered. When omitted, the existing status is preserved on update, or defaults to in_transit on the first update.

Available options:

waiting,

in_transit,

delivered

Example:

"in_transit"

tracking_url

string | null

Public URL where the buyer can track the shipment. Must start with http:// or https://. Send null to clear a previously set value; omit to leave it unchanged.

Maximum string length: 255

Example:

"https://tracking.carrier.com/BR123456789BR"

tracking_company

string | null

Name of the carrier handling the shipment. Send null to clear a previously set value; omit to leave it unchanged.

Required string length: 1 - 64

Example:

"Correios"

Response

Success

success

boolean

required

requestId

string

required

data

object

required

Show child attributes

Update Delivery Tracking

curl --request PUT \
  --url https://api.pagou.ai/v2/transactions/{id}/delivery \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tracking_code": "BR123456789BR",
  "delivery_status": "in_transit",
  "tracking_url": "https://tracking.carrier.com/BR123456789BR",
  "tracking_company": "Correios"
}
'

import requests

url = "https://api.pagou.ai/v2/transactions/{id}/delivery"

payload = {
    "tracking_code": "BR123456789BR",
    "delivery_status": "in_transit",
    "tracking_url": "https://tracking.carrier.com/BR123456789BR",
    "tracking_company": "Correios"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tracking_code: 'BR123456789BR',
    delivery_status: 'in_transit',
    tracking_url: 'https://tracking.carrier.com/BR123456789BR',
    tracking_company: 'Correios'
  })
};

fetch('https://api.pagou.ai/v2/transactions/{id}/delivery', 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.pagou.ai/v2/transactions/{id}/delivery",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'tracking_code' => 'BR123456789BR',
    'delivery_status' => 'in_transit',
    'tracking_url' => 'https://tracking.carrier.com/BR123456789BR',
    'tracking_company' => 'Correios'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.pagou.ai/v2/transactions/{id}/delivery"

	payload := strings.NewReader("{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.put("https://api.pagou.ai/v2/transactions/{id}/delivery")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pagou.ai/v2/transactions/{id}/delivery")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tracking_code\": \"BR123456789BR\",\n  \"delivery_status\": \"in_transit\",\n  \"tracking_url\": \"https://tracking.carrier.com/BR123456789BR\",\n  \"tracking_company\": \"Correios\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "data": {
    "status": "waiting",
    "code": "string",
    "url": "string",
    "company": "string",
    "last_update": "2026-07-14T12:00:00.000Z"
  }
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "title": "<string>",
  "status": 123,
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Customers

Transactions

Checkout Links

Transfers

Subscriptions

Legacy v1

Request fields

Omit vs. null semantics

Idempotency and concurrency

Errors

Example

Authorizations

Path Parameters

Body

Response

​Request fields

​Omit vs. null semantics

​Idempotency and concurrency

​Errors

​Example

Authorizations

Path Parameters

Body

Response

Request fields

Omit vs. null semantics

Idempotency and concurrency

Errors

Example