Order tracking signals let you provide Google with your historical order tracking data for orders completed through a merchant's site. This provides buyers more precise and accurate shipping estimates. Order tracking signals also let you enhance your listings with free and fast shipping annotations .
You can submit data for orders completed through a merchant's site. The data that you submit compliments the shipping configuration information that you provide as part of your Merchant Center account setup. For example, if you provide buyers with shipping estimates of 3-7 days, but your recent historical order tracking indicates that your orders typically arrive in 3 days in some regions, Google can update your listings to provide customers with a more precise estimate.
This guide explains how to use the ordertrackingsignals
resource to submit
your historical order tracking data.
Prerequisites
Your account must be preapproved to send order tracking signals for another account, this requires the other account to link the account holder.
For more information, see Link a partner with your Merchant Center account .
Use the ordertrackingsignals
resource
The ordertrackingsignals
resource includes a single create
endpoint, which
lets you submit your historical order tracking data.
You can submit one order per request. The following information explains why it's needed and can be added to the request body.
-
Order details (order creation time, delivery postal code, and region code),
shippingInfo, and tracking number: It enables the calculation of actual handling and delivery times. -
merchant_idandlineItems: It is used to match the order to products you have in your Merchant Center account. -
customerShippingFee: Shipping cost charged to the buyer.
Submit new order tracking signals data
Here's a sample request to submit an order tracking signal for the retailer's order '123456789' with a total of 8 items.
https://merchantapi.googleapis.com/products/ordertracking/v1/accounts/ {ACCOUNT_ID}
/ordertrackingsignals
{
"merchantId": {ACCOUNT_ID}
,
"orderCreatedTime": {
"year": 2025,
"month": 1,
"day": 2,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"orderId": "123456789",
"shippingInfo": [
{
"shipmentId": "1",
"trackingId": "100",
"carrier": "FEDEX",
"carrierService": "GROUND",
"shippedTime": {
"year": 2025,
"month": 1,
"day": 3,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"shippingStatus": "DELIVERED"
},
{
"shipmentId": "2",
"earliestDeliveryPromiseTime": {
"year": 2025,
"month": 1,
"day": 4,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"latestDeliveryPromiseTime": {
"year": 2025,
"month": 1,
"day": 5,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"actualDeliveryTime": {
"year": 2025,
"month": 1,
"day": 5,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"shippedTime": {
"year": 2025,
"month": 1,
"day": 3,
"hours": 0,
"minutes": 0,
"seconds": 0,
"timeZone": {
"id": "America/Los_Angeles"
}
},
"shippingStatus": "DELIVERED"
}
],
"lineItems": [
{
"lineItemId": "item1",
"productId": "en~US~trouser",
"quantity": "3"
},
{
"lineItemId": "item2",
"productId": "en~US~sneaker",
"quantity": "5"
}
],
"shipmentLineItemMapping": [
{
"shipmentId": "1",
"lineItemId": "item1",
"quantity": "1"
},
{
"shipmentId": "2",
"lineItemId": "item1",
"quantity": "2"
},
{
"shipmentId": "1",
"lineItemId": "item2",
"quantity": "4"
},
{
"shipmentId": "2",
"lineItemId": "item2",
"quantity": "1"
}
],
"customerShippingFee": {
"amount_micros": 4500000,
"currency_code": "USD"
},
"deliveryPostalCode": "94043",
"deliveryRegionCode": "US"
}
Here's a sample response from a successful call:
{
"orderCreatedTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
2
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"orderId"
:
"15e2b0d3c33891ebb0f1ef609ec419420c20e320ce94c65fbc8c3312448eb225"
,
"shippingInfo"
:
[
{
"shipmentId"
:
"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
,
"trackingId"
:
"100"
,
"carrier"
:
"FEDEX"
,
"carrierService"
:
"GROUND"
,
"shippedTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
3
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"shippingStatus"
:
"DELIVERED"
},
{
"shipmentId"
:
"d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35"
,
"shippedTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
3
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"earliestDeliveryPromiseTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
4
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"latestDeliveryPromiseTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
5
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"actualDeliveryTime"
:
{
"year"
:
2025
,
"month"
:
1
,
"day"
:
5
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
"shippingStatus"
:
"DELIVERED"
}
],
"lineItems"
:
[
{
"lineItemId"
:
"item1"
,
"productId"
:
"en~US~8465944842"
,
"quantity"
:
"3"
},
{
"lineItemId"
:
"item2"
,
"productId"
:
"en~US~8465944842"
,
"quantity"
:
"5"
}
],
"shipmentLineItemMapping"
:
[
{
"shipmentId"
:
"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
,
"lineItemId"
:
"item1"
,
"quantity"
:
"1"
},
{
"shipmentId"
:
"d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35"
,
"lineItemId"
:
"item1"
,
"quantity"
:
"2"
},
{
"shipmentId"
:
"6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b"
,
"lineItemId"
:
"item2"
,
"quantity"
:
"4"
},
{
"shipmentId"
:
"d4735e3a265e16eee03f59718b9b5d03019c07d8b6c51f90da3a666eec13ab35"
,
"lineItemId"
:
"item2"
,
"quantity"
:
"1"
}
],
"customerShippingFee"
:
{
"amountMicros"
:
"4500000"
,
"currencyCode"
:
"USD"
},
"deliveryPostalCode"
:
"94043"
,
"deliveryRegionCode"
:
"US"
,
"orderTrackingSignalId"
:
"2424724582881888160"
,
"merchantId"
:
"1234"
}
The following code sample shows how to submit order tracking signals data:
Java
import
com.google.api.gax.core.FixedCredentialsProvider
;
import
com.google.auth.oauth2.GoogleCredentials
;
import
com.google.shopping.merchant.ordertracking.v1.CreateOrderTrackingSignalRequest
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.LineItemDetails
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShipmentLineItemMapping
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShippingInfo
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignal.ShippingInfo.ShippingState
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignalsServiceClient
;
import
com.google.shopping.merchant.ordertracking.v1.OrderTrackingSignalsServiceSettings
;
import
com.google.shopping.type.Price
;
import
com.google.type.DateTime
;
import
com.google.type.TimeZone
;
import
java.util.Arrays
;
import
java.util.List
;
import
shopping.merchant.samples.utils.Authenticator
;
import
shopping.merchant.samples.utils.Config
;
/** This class demonstrates how to create an order tracking signal. */
public
class
CreateOrderTrackingSignalSample
{
private
static
String
getParent
(
String
accountId
)
{
return
String
.
format
(
"accounts/%s"
,
accountId
);
}
private
static
void
createOrderTrackingSignal
(
Config
config
,
List<String>
productIds
)
throws
Exception
{
GoogleCredentials
credentials
=
new
Authenticator
().
authenticate
();
OrderTrackingSignalsServiceSettings
orderTrackingSignalsServiceSettings
=
OrderTrackingSignalsServiceSettings
.
newBuilder
()
.
setCredentialsProvider
(
FixedCredentialsProvider
.
create
(
credentials
))
.
build
();
String
parent
=
getParent
(
config
.
getAccountId
().
toString
());
String
firstProductId
=
productIds
.
get
(
0
);
String
secondProductId
=
productIds
.
get
(
1
);
DateTime
orderCreatedTime
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
24
)
.
setHours
(
12
)
.
setMinutes
(
2
)
.
setSeconds
(
22
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
DateTime
shippedTime1
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
25
)
.
setHours
(
16
)
.
setMinutes
(
22
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
DateTime
shippedTime2
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
26
)
.
setHours
(
16
)
.
setMinutes
(
22
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
DateTime
earliestDeliveryPromiseTime
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
27
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
DateTime
latestDeliveryPromiseTime
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
30
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
DateTime
actualDeliveryTime
=
DateTime
.
newBuilder
()
.
setYear
(
2025
)
.
setMonth
(
3
)
.
setDay
(
29
)
.
setHours
(
16
)
.
setMinutes
(
22
)
.
setTimeZone
(
TimeZone
.
newBuilder
().
setId
(
"America/Los_Angeles"
))
.
build
();
ShippingInfo
shippingInfo1
=
ShippingInfo
.
newBuilder
()
.
setShipmentId
(
"shipment_id1"
)
.
setCarrier
(
"UPS"
)
.
setCarrierService
(
"Ground"
)
.
setTrackingId
(
"1Z23456789"
)
.
setShippedTime
(
shippedTime1
)
.
setEarliestDeliveryPromiseTime
(
earliestDeliveryPromiseTime
)
.
setLatestDeliveryPromiseTime
(
latestDeliveryPromiseTime
)
.
setActualDeliveryTime
(
actualDeliveryTime
)
.
setShippingStatus
(
ShippingState
.
DELIVERED
)
.
setOriginPostalCode
(
"94043"
)
.
setOriginRegionCode
(
"US"
)
.
build
();
ShippingInfo
shippingInfo2
=
ShippingInfo
.
newBuilder
()
.
setShipmentId
(
"shipment_id2"
)
.
setCarrier
(
"USPS"
)
.
setCarrierService
(
"Ground Advantage"
)
.
setTrackingId
(
"987654321"
)
.
setShippedTime
(
shippedTime2
)
.
setShippingStatus
(
ShippingState
.
SHIPPED
)
.
setOriginPostalCode
(
"94043"
)
.
setOriginRegionCode
(
"US"
)
.
build
();
try
(
OrderTrackingSignalsServiceClient
orderTrackingSignalsServiceClient
=
OrderTrackingSignalsServiceClient
.
create
(
orderTrackingSignalsServiceSettings
))
{
CreateOrderTrackingSignalRequest
request
=
CreateOrderTrackingSignalRequest
.
newBuilder
()
.
setParent
(
parent
)
.
setOrderTrackingSignal
(
OrderTrackingSignal
.
newBuilder
()
// Unique order ID across all merchants orders.
.
setOrderId
(
"unique_order_id443455"
)
// If sending signal on behalf of another merchant use setMerchantId to
// indicate the merchant.
// .setMerchantId(123L)
.
setOrderCreatedTime
(
orderCreatedTime
)
.
addShippingInfo
(
shippingInfo1
)
.
addShippingInfo
(
shippingInfo2
)
// Details of the line items in the order including quantity and fields
// identifying the product.
.
addLineItems
(
LineItemDetails
.
newBuilder
()
.
setQuantity
(
2
)
.
setProductId
(
firstProductId
)
.
setLineItemId
(
"item1"
))
.
addLineItems
(
LineItemDetails
.
newBuilder
()
.
setQuantity
(
1
)
.
setProductId
(
secondProductId
)
.
setLineItemId
(
"item2"
)
// Optional fields used to identify the product when product ID is not
// sufficient.
.
setMpn
(
"00638HAY"
)
.
setProductTitle
(
"Tshirt-small-blue"
)
.
setBrand
(
"Brand1"
)
// Any GTIN associated with the product.
.
addGtins
(
"001234567890"
))
// Mapping of line items to shipments.
.
addShipmentLineItemMapping
(
ShipmentLineItemMapping
.
newBuilder
()
.
setShipmentId
(
"shipment_id1"
)
.
setLineItemId
(
"item2"
)
.
setQuantity
(
1
))
.
addShipmentLineItemMapping
(
ShipmentLineItemMapping
.
newBuilder
()
.
setShipmentId
(
"shipment_id2"
)
.
setLineItemId
(
"item1"
)
.
setQuantity
(
1
))
.
addShipmentLineItemMapping
(
ShipmentLineItemMapping
.
newBuilder
()
.
setShipmentId
(
"shipment_id1"
)
.
setLineItemId
(
"item1"
)
.
setQuantity
(
1
))
// The price represented as a number in micros (1 million micros is an
// equivalent to one's currency standard unit, for example, 1 USD = 1000000
// micros).
.
setCustomerShippingFee
(
Price
.
newBuilder
()
// Equivalent to 5 USD.
.
setAmountMicros
(
5000000
)
.
setCurrencyCode
(
"USD"
))
.
setDeliveryPostalCode
(
"10011"
))
.
build
();
System
.
out
.
println
(
"Sending Create OrderTrackingSignal request."
);
OrderTrackingSignal
response
=
orderTrackingSignalsServiceClient
.
createOrderTrackingSignal
(
request
);
System
.
out
.
println
(
"Created OrderTrackingSignal below."
);
System
.
out
.
println
(
response
);
}
catch
(
Exception
e
)
{
System
.
out
.
println
(
e
);
}
}
public
static
void
main
(
String
[]
args
)
throws
Exception
{
Config
config
=
Config
.
load
();
// All products in the order. Replace with actual products in the order. Be sure to include all
// products in the order.
String
productId1
=
"online~en~us~sku123"
;
String
productId2
=
"online~en~us~skuabc"
;
List<String>
productIds
=
Arrays
.
asList
(
productId1
,
productId2
);
createOrderTrackingSignal
(
config
,
productIds
);
}
}
Submit new order tracking signals data on behalf of a retailer
To submit new order tracking signals data on behalf of a retailer, follow the given steps:
- Make sure that you're enabled before you can submit data on behalf of another business. To request access, contact us at OrderTrackingSignals@google.com .
- Set up
merchant_idfield and send data on behalf of the business.
Update existing order tracking signals data
To modify already submitted order tracking data, submit a request that contains
new data with the same orderId
. For shipping estimates and fast and free
badging, only the most recently submitted data for each orderId
is used.
