> ## Documentation Index > Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Delivery Tracking > Set or update shipping tracking on a paid transaction. 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](/api-reference/transactions/get) 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 ```bash theme={null} curl -X PUT "https://api.pagou.ai/v2/transactions/{id}/delivery" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "tracking_code": "BR123456789BR", "delivery_status": "in_transit", "tracking_url": "https://tracking.carrier.com/BR123456789BR", "tracking_company": "Correios" }' ``` ```json theme={null} { "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}`. ## OpenAPI ````yaml api-reference/openapi-v2.json PUT /v2/transactions/{id}/delivery openapi: 3.1.0 info: title: Pagou API - v2 description: API for Pagou.ai Gateway version: 2.0.0 contact: name: Support url: https://pagou.ai email: support@pagou.ai servers: - url: https://api.pagou.ai description: Production server - url: https://api.sandbox.pagou.ai description: Sandbox server for testing security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] paths: /v2/transactions/{id}/delivery: put: tags: - Transactions summary: Update Delivery Tracking description: >- Set or update delivery tracking information on a paid transaction. Identify the transaction by the UUID returned as its public `id`. `tracking_code` is required; `delivery_status`, `tracking_url`, and `tracking_company` are optional. Omitting an optional field leaves its current value unchanged, while sending `null` for `tracking_url` or `tracking_company` clears it. When `delivery_status` is omitted, the existing status is preserved (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). Supports optimistic concurrency through `If-Match` with the transaction ETag (returns 412 on mismatch). operationId: putTransactionsByIdDelivery parameters: - schema: type: string format: uuid 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)$ in: path name: id required: true requestBody: required: true content: application/json: schema: type: object properties: tracking_code: type: string minLength: 1 maxLength: 255 description: Carrier tracking code for the shipment. Required. example: BR123456789BR delivery_status: description: >- 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. example: in_transit type: string enum: - waiting - in_transit - delivered tracking_url: description: >- 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. example: https://tracking.carrier.com/BR123456789BR nullable: true type: string maxLength: 255 tracking_company: description: >- Name of the carrier handling the shipment. Send `null` to clear a previously set value; omit to leave it unchanged. example: Correios nullable: true type: string minLength: 1 maxLength: 64 required: - tracking_code responses: '200': description: Success content: application/json: schema: type: object properties: success: type: boolean requestId: type: string data: type: object properties: status: nullable: true type: string enum: - waiting - in_transit - delivered code: nullable: true type: string url: nullable: true type: string company: nullable: true type: string last_update: nullable: true type: string format: date-time required: - status - code - url - company - last_update additionalProperties: false required: - success - requestId - data additionalProperties: false example: 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' '400': description: HTTP 400 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '401': description: HTTP 401 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '404': description: HTTP 404 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '409': description: HTTP 409 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '412': description: HTTP 412 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} '422': description: HTTP 422 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} application/problem+json: schema: $ref: '#/components/schemas/ValidationProblemDetails' '429': description: HTTP 429 response content: application/json: schema: type: object properties: type: description: URI reference identifying the problem type. type: string title: type: string description: Short, human-readable summary of the problem. status: type: number description: HTTP status code. detail: description: Human-readable explanation specific to this occurrence. type: string instance: description: URI reference identifying the specific occurrence. type: string required: - title - status additionalProperties: {} default: description: RFC 7807 Problem Details error response content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' security: - BearerAuth: [] - ApiKeyAuth: [] - BasicAuth: [] components: schemas: ValidationProblemDetails: allOf: - $ref: '#/components/schemas/ProblemDetails' - type: object properties: errors: type: array items: type: object properties: field: type: string message: type: string code: type: string additionalProperties: true additionalProperties: true ProblemDetails: type: object description: RFC 7807 Problem Details object. properties: type: type: string format: uri-reference title: type: string status: type: number detail: type: string instance: type: string format: uri-reference required: - type - title - status - detail additionalProperties: true securitySchemes: BearerAuth: type: http scheme: bearer ApiKeyAuth: type: apiKey in: header name: apiKey BasicAuth: type: http scheme: basic description: Use Basic auth with username `token` and password `x`. ````