curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh', 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-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}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.
curl --request POST \
--url https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh', 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-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-sandbox.finogates.com/v1/platform/payments/document-mailing/{payment_id}/tracking/refresh")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"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
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Authorizations
The access token received from the authorization server in the OAuth 2.0 flow.
Path Parameters
The document-mailing payment id.
Response
The mailed document's tracking after a live carrier read.

