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](https://support.google.com/merchants/answer/9780562).

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 pre-approved 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](https://support.google.com/merchants/answer/14172216).

> [!NOTE]
> **Note:** Sending order tracking signals for your own account does not require pre-approval.

## Use the `ordertrackingsignals` resource

The `ordertrackingsignals` resource includes a single `create` endpoint, which
lets you submit your historical order tracking data.

> [!NOTE]
> **Note:** You can only submit data for orders that have been delivered, so that the shipping times can be verified.

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_id` and `lineItems` : 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"
    }

> [!NOTE]
> **Note:** `amountMicros` is 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).

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 = "en~us~sku123";
        String productId2 = "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:

1. 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](mailto:OrderTrackingSignals@google.com).
2. Set up `merchant_id` field 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.