Skip to main content
PUT
Update Delivery Tracking
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:
FieldTypeRequiredConstraints
tracking_codestringYesTrimmed, 1–255 chars, no ASCII control characters.
delivery_statusenumNoOne of waiting, in_transit, delivered. Defaults to in_transit on first set.
tracking_urlstring | nullNoTrimmed, max 255 chars, must start with http:// or https://.
tracking_companystring | nullNoTrimmed, 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

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

Example

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

id
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