Update Delivery Tracking
Set or update shipping tracking on a paid transaction.
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
nullfortracking_urlortracking_companyto clear a previously set value. - When
delivery_statusis omitted, the existing status is preserved on update, or defaults toin_transitthe first time delivery is set. - A shipment already marked
deliveredcannot be moved back towaitingorin_transit(returns409).
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
GET /v2/transactions/{id}.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
^([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
Carrier tracking code for the shipment. Required.
1 - 255"BR123456789BR"
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.
waiting, in_transit, delivered "in_transit"
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.
255"https://tracking.carrier.com/BR123456789BR"
Name of the carrier handling the shipment. Send null to clear a previously set value; omit to leave it unchanged.
1 - 64"Correios"

