Mengelola sinyal pelacakan pesanan

Sinyal pelacakan pesanan memungkinkan Anda memberikan data pelacakan pesanan historis kepada Google untuk pesanan yang diselesaikan melalui situs penjual. Hal ini memberikan estimasi pengiriman yang lebih tepat dan akurat kepada pembeli. Sinyal pelacakan pesanan juga memungkinkan Anda meningkatkan kualitas listingan dengan anotasi pengiriman gratis dan cepat.

Anda dapat mengirimkan data untuk pesanan yang diselesaikan melalui situs penjual. Data yang Anda kirimkan melengkapi informasi konfigurasi pengiriman yang Anda berikan sebagai bagian dari penyiapan akun Merchant Center. Misalnya, jika Anda memberikan estimasi pengiriman 3-7 hari kepada pembeli, tetapi pelacakan pesanan historis terbaru Anda menunjukkan bahwa pesanan Anda biasanya tiba dalam 3 hari di beberapa wilayah, Google dapat memperbarui listingan Anda untuk memberikan estimasi yang lebih akurat kepada pelanggan.

Panduan ini menjelaskan cara menggunakan resource ordertrackingsignals untuk mengirimkan data pelacakan pesanan historis Anda.

Prasyarat

Akun Anda harus disetujui sebelumnya untuk mengirim sinyal pelacakan pesanan untuk akun lain. Hal ini mengharuskan akun lain tersebut menautkan pemegang akun.

Untuk mengetahui informasi selengkapnya, lihat Menautkan partner dengan akun Merchant Center Anda.

Menggunakan resource ordertrackingsignals

Resource ordertrackingsignals mencakup satu endpoint create, yang memungkinkan Anda mengirimkan data pelacakan pesanan historis.

Anda dapat mengirimkan satu pesanan per permintaan. Informasi berikut menjelaskan alasan informasi tersebut diperlukan dan dapat ditambahkan ke isi permintaan.

  • Detail pesanan (waktu pembuatan pesanan, kode pos pengiriman, dan kode wilayah), shippingInfo, dan nomor pelacakan: Memungkinkan penghitungan waktu penanganan dan pengiriman yang sebenarnya.

  • merchant_id dan lineItems : Atribut ini digunakan untuk mencocokkan pesanan dengan produk yang Anda miliki di akun Merchant Center.

  • customerShippingFee: Biaya pengiriman yang dikenakan kepada pembeli.

Mengirimkan data sinyal pelacakan pesanan baru

Berikut adalah contoh permintaan untuk mengirimkan sinyal pelacakan pesanan untuk pesanan '123456789' retailer dengan total 8 item.

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"
}

Berikut adalah contoh respons dari panggilan yang berhasil:

{
  "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"
}

Contoh kode berikut menunjukkan cara mengirimkan data sinyal pelacakan pesanan:

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);
  }
}
CreateOrderTrackingSignalSample.java

Mengirimkan data sinyal pelacakan pesanan baru atas nama retailer

Untuk mengirimkan data sinyal pelacakan pesanan baru atas nama retailer, ikuti langkah-langkah yang diberikan:

  1. Pastikan Anda diaktifkan sebelum dapat mengirimkan data atas nama bisnis lain. Untuk meminta akses, hubungi kami di OrderTrackingSignals@google.com.
  2. Siapkan kolom merchant_id dan kirim data atas nama bisnis.

Memperbarui data sinyal pelacakan pesanan yang ada

Untuk mengubah data pelacakan pesanan yang sudah dikirimkan, kirimkan permintaan yang berisi data baru dengan orderId yang sama. Untuk estimasi pengiriman dan badge cepat dan gratis, hanya data yang baru saja dikirimkan untuk setiap orderId yang digunakan.