> ## Documentation Index > Fetch the complete documentation index at: https://developer.finogates.com/llms.txt > Use this file to discover all available pages before exploring further. # Refresh a Mailed Document's Tracking > Ask the carrier where a mailed document is right now, then return the updated tracking payload. Rate-limited per mailing rather than per caller, so ten people watching the same document cost one carrier call between them. A call made inside that window is **not** an error: you get the tracking we already hold, with `synced_at` unchanged so you can see how fresh it is. The same applies when the carrier cannot be reached — the stored history is still returned rather than an error, because stale tracking with an honest timestamp beats none. Response shape is identical to the tracking endpoint. Poll that one instead if you only need to read; this endpoint spends a carrier call. ## OpenAPI ````yaml POST /v1/platform/payments/document-mailing/{payment_id}/tracking/refresh openapi: 3.1.0 info: title: Finogate Platform API v1 version: 0.1.0 servers: - url: https://api-sandbox.finogates.com description: Sandbox - url: https://api.finogates.com description: Production security: [] tags: - name: auth - name: users - name: payees - name: verification - name: bank accounts - name: card processing - name: digital-assets - name: international - name: fees - name: onboarding - name: pending-applications - name: wallets - name: payments - name: document mailing - name: merchant onboarding - name: catalog - name: webhooks - name: screening - name: Platform - File Scanning - name: phone-numbers - name: sms - name: calls - name: listings - name: Card Transfers - name: embed-tokens paths: /v1/platform/payments/document-mailing/{payment_id}/tracking/refresh: post: tags: - document mailing summary: Refresh a Mailed Document's Tracking description: >- Ask the carrier where a mailed document is right now, then return the updated tracking payload. Rate-limited per mailing rather than per caller, so ten people watching the same document cost one carrier call between them. A call made inside that window is **not** an error: you get the tracking we already hold, with `synced_at` unchanged so you can see how fresh it is. The same applies when the carrier cannot be reached — the stored history is still returned rather than an error, because stale tracking with an honest timestamp beats none. Response shape is identical to the tracking endpoint. Poll that one instead if you only need to read; this endpoint spends a carrier call. operationId: >- refresh_document_shipping_tracking_v1_platform_payments_document_mailing__payment_id__tracking_refresh_post parameters: - name: payment_id in: path required: true schema: type: string format: uuid description: The document-mailing payment id. title: Payment Id description: The document-mailing payment id. responses: '200': description: The mailed document's tracking after a live carrier read. content: application/json: schema: $ref: >- #/components/schemas/CommonResponse_DocumentShippingTrackingRead_ example: status_code: 200 data: trackable: true tracking_number: '9400100000000000000000' carrier: usps carrier_label: USPS service: USPS Ground Advantage status: delivered status_label: Delivered shipped_at: '2026-08-24T15:02:00Z' estimated_delivery_at: '2026-08-27T00:00:00Z' delivered_at: '2026-08-26T17:45:00Z' delivered_to: J.SMITH synced_at: '2026-08-26T18:02:00Z' carrier_tracking_url: >- https://tools.usps.com/go/TrackConfirmAction?tLabels=9400100000000000000000 events: - status: label_created status_label: Label created description: Shipping label created, item awaiting pickup occurred_at: '2026-08-24T15:02:00Z' occurred_at_local: '2026-08-24T10:02:00' utc_offset_minutes: -300 city: Austin state: TX postal_code: '78701' country: US - status: in_transit status_label: In transit description: Departed shipping facility occurred_at: '2026-08-25T02:40:00Z' occurred_at_local: '2026-08-24T21:40:00' utc_offset_minutes: -300 city: Dallas state: TX postal_code: '75201' country: US - status: delivered status_label: Delivered description: Delivered, in/at mailbox occurred_at: '2026-08-26T17:45:00Z' occurred_at_local: '2026-08-26T11:45:00' utc_offset_minutes: -360 city: Denver state: CO postal_code: '80202' country: US query_generated_time: 1712847600000 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - _AuthenticatedBearer: [] components: schemas: CommonResponse_DocumentShippingTrackingRead_: properties: status_code: type: integer title: Status Code description: HTTP status code for the response. data: $ref: '#/components/schemas/DocumentShippingTrackingRead' description: Payload or error details. query_generated_time: type: integer title: Query Generated Time description: >- UTC timestamp (milliseconds since epoch) when response was generated. type: object required: - status_code - data - query_generated_time title: CommonResponse[DocumentShippingTrackingRead] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DocumentShippingTrackingRead: properties: trackable: type: boolean title: Trackable description: >- Whether this shipping service produces a tracking barcode at all. False for letter services, which carry a postage indicia instead — there is no number to follow and there never will be, so absent tracking on one of those is not a fault. tracking_number: anyOf: - type: string - type: 'null' title: Tracking Number carrier: anyOf: - type: string - type: 'null' title: Carrier description: Carrier key. examples: - fedex carrier_label: anyOf: - type: string - type: 'null' title: Carrier Label description: Carrier name, for display. examples: - FedEx service: anyOf: - type: string - type: 'null' title: Service description: The shipping service bought. examples: - FedEx Standard Overnight status: anyOf: - type: string - type: 'null' title: Status description: >- Current delivery stage, taken from the most recent scan — not the furthest stage reached. A parcel that hit an exception after going out for delivery reads `exception`, because that is what is true now. Null when no scans have been recorded yet. examples: - out_for_delivery status_label: anyOf: - type: string - type: 'null' title: Status Label description: Display form of `status`. examples: - Out for delivery shipped_at: anyOf: - type: string format: date-time - type: 'null' title: Shipped At description: When the shipping label was purchased. estimated_delivery_at: anyOf: - type: string format: date-time - type: 'null' title: Estimated Delivery At description: >- The carrier's own delivery estimate, not a commitment from us. Present it as the carrier's estimate wherever it is shown. delivered_at: anyOf: - type: string format: date-time - type: 'null' title: Delivered At description: >- When the carrier confirmed delivery. Delivery means the envelope reached the address — not that its contents were acted on. delivered_to: anyOf: - type: string - type: 'null' title: Delivered To description: >- Who the carrier recorded as accepting the parcel. Null until delivered, and on services that capture no signature — most of them — so its absence is never evidence of a problem. examples: - J.SMITH synced_at: anyOf: - type: string format: date-time - type: 'null' title: Synced At description: >- When we last successfully read this shipment's status from the carrier. Show it, so how fresh the page is stays visible rather than assumed. carrier_tracking_url: anyOf: - type: string - type: 'null' title: Carrier Tracking Url description: The carrier's own tracking page for this shipment. events: items: $ref: '#/components/schemas/DocumentMailingTrackingEventRead' type: array title: Events description: >- Every scan we hold, oldest first. Empty while a label exists but the carrier has not scanned the parcel yet — which is normal for the first several hours and is not the same as tracking being unavailable. type: object required: - trackable title: DocumentShippingTrackingRead description: 'A shipment''s full journey: where it is now, and everywhere it has been.' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError DocumentMailingTrackingEventRead: properties: status: type: string title: Status description: >- Normalised delivery stage for this scan: label_created, picked_up, in_transit, out_for_delivery, delivered, exception, returning, or unknown. Carrier event codes vary by carrier and change without notice; this field does not. examples: - out_for_delivery status_label: type: string title: Status Label description: Display form of `status`, ready to render. examples: - Out for delivery description: anyOf: - type: string - type: 'null' title: Description description: The carrier's own wording for this scan, passed through unchanged. examples: - On FedEx vehicle for delivery occurred_at: type: string format: date-time title: Occurred At description: When the scan happened, in UTC. Use this to sort. occurred_at_local: anyOf: - type: string format: date-time - type: 'null' title: Occurred At Local description: >- The same moment as a wall-clock reading at the place it was scanned, with no timezone attached. This is what to display: a parcel scanned at 21:14 in Memphis should read 21:14, not the UTC equivalent. Pair it with `utc_offset_minutes` to label the zone. utc_offset_minutes: anyOf: - type: integer - type: 'null' title: Utc Offset Minutes description: >- Minutes east of UTC at the scan location (-300 for US Central Daylight Time). Null when the carrier did not state an offset, in which case show `occurred_at_local` without a timezone label rather than assuming one. examples: - -300 city: anyOf: - type: string - type: 'null' title: City state: anyOf: - type: string - type: 'null' title: State postal_code: anyOf: - type: string - type: 'null' title: Postal Code country: anyOf: - type: string - type: 'null' title: Country exception_code: anyOf: - type: string - type: 'null' title: Exception Code description: The carrier's code for a failed delivery attempt. examples: - A1 exception_description: anyOf: - type: string - type: 'null' title: Exception Description description: >- The carrier's own reason for a failed attempt. Show it verbatim — it is what the recipient will be told if they contact the carrier. examples: - Customer not available or business closed carrier_code: anyOf: - type: string - type: 'null' title: Carrier Code description: >- The carrier's raw event code. Operator surfaces only; null elsewhere. examples: - OD source: anyOf: - type: string - type: 'null' title: Source description: >- Which signal recorded this scan — `webhook` or `poll`. Operator surfaces only; null elsewhere. examples: - webhook type: object required: - status - status_label - occurred_at title: DocumentMailingTrackingEventRead description: One carrier scan — a single line on the timeline. securitySchemes: _AuthenticatedBearer: type: oauth2 flows: password: scopes: {} tokenUrl: /v1/platform/auth/token ````