出貨動作結構定義

本頁面說明使用 Ordering End-to-End 內建動作 API 時，執行要求網路服務 (Ordering End-to-End API) 的酬載。如要取得這項資訊的機器可讀版本，請下載 JSON 結構定義。

基本類型

購物車

包含訂單詳細資料，以及要求是取貨還是送貨。購物車也會包含運送詳細資料、小費和運送地址。Cart 物件是在 Checkout AppRequest 中定義。您可以在 Checkout AppResponse 中加入購物車的副本。

下表列出 Cart 類型的屬性：

屬性 類型 說明
@type Const

這個物件的類型。如果父項 Cart 物件是 ProposedOrder 的一部分，請省略這個欄位。

值：type.googleapis.com/google.actions.v2.orders.Cart
id String

購物車的選用 ID。
merchant Merchant

與此購物車相關的商家。
lineItems List<LineItem>

必填。

使用者訂購的商品或服務清單。

必須至少包含 1 個項目。
promotions List<Promotion>

這個購物車中適用的促銷活動。目前僅支援一項促銷活動。
notes String

訂單或運送指示的附註。
extension FoodCartExtension

定義使用者詳細資料，例如訂單履行偏好設定。

以下範例顯示 Cart 元素：

範例 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.Cart",
  "merchant": {
    "id": "https://www.exampleprovider.com/merchant/id1",
    "name": "Cucina Venti"
  },
  "lineItems": [
    {
      "name": "Sizzling Prawns Dinner",
      "type": "REGULAR",
      "id": "sample_item_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "16",
          "nanos": 750000000
        }
      },
      "subLines": [
        {
          "note": "Notes for this item."
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
        "options": [
          {
            "id": "sample_addon_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
            "name": "Honey Mustard",
            "price": {
              "currencyCode": "USD"
            },
            "quantity": 1
          },
          {
            "id": "sample_addon_offer_id_2",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
            "name": "BBQ Sauce",
            "price": {
              "currencyCode": "USD",
              "nanos": 500000000
            },
            "quantity": 1
          }
        ]
      }
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
    "fulfillmentPreference": {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P0M"
        }
      }
    },
    "location": {
      "coordinates": {
        "latitude": 37.788783,
        "longitude": -122.41384
      },
      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
      "zipCode": "94043",
      "city": "Mountain View",
      "postalAddress": {
        "regionCode": "US",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1350 Charleston Road"
        ]
      },
      "notes": "Gate code is #111"
    }
  }
}

範例 2

{
  "merchant": {
    "id": "https://www.exampleprovider.com/merchant/id1",
    "name": "Falafel Bite"
  },
  "lineItems": [
    {
      "name": "Pita Chips",
      "type": "REGULAR",
      "id": "sample_item_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "2",
          "nanos": 750000000
        }
      },
      "subLines": [
        {
          "note": "Notes for this item."
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
        "options": [
          {
            "id": "sample_addon_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
            "name": "Honey Mustard",
            "price": {
              "currencyCode": "USD"
            },
            "quantity": 1
          },
          {
            "id": "sample_addon_offer_id_2",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
            "name": "BBQ Sauce",
            "price": {
              "currencyCode": "USD",
              "nanos": 500000000
            },
            "quantity": 1
          }
        ]
      }
    },
    {
      "name": "Chicken Shwarma Wrap",
      "type": "REGULAR",
      "id": "sample_item_offer_id_2",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "8"
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    },
    {
      "name": "Greek Salad",
      "type": "REGULAR",
      "id": "sample_item_offer_id_3",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "9",
          "nanos": 990000000
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    },
    {
      "name": "Prawns Biryani",
      "type": "REGULAR",
      "id": "sample_item_offer_id_4",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "15",
          "nanos": 990000000
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
    "fulfillmentPreference": {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P90M"
        }
      }
    },
    "location": {
      "coordinates": {
        "latitude": 37.788783,
        "longitude": -122.41384
      },
      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
      "zipCode": "94043",
      "city": "Mountain View",
      "postalAddress": {
        "regionCode": "US",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1350 Charleston Road"
        ]
      },
      "notes": "Gate code is #111"
    }
  }
}

聯絡

指定訂單收件人的詳細資料。這項功能僅適用於 AppResponse。

下表列出 Contact 類型的屬性：

屬性 類型 說明
displayName String

收貨人的姓名，請依照你希望顯示的方式輸入。如果未指定 firstName 和 lastName，請使用這個欄位。

範例：Lovefood Ordering
email String

訂單收件者的電子郵件地址。

範例：ilovefood@example.com
firstName String

收取訂單的人員姓氏。

範例：Lovefood
lastName String

收到訂單的收件者姓氏。

範例：Ordering
phoneNumber String

訂單收件人的電話號碼，包括國家/地區代碼。

範例：+16501234567
emailVerified 布林值

指出接收訂單的使用者是否已登入 Google 帳戶。

以下範例顯示 Contact 元素：

範例

{
  "displayName": "Lovefood Ordering",
  "email": "ilovefood@example.com",
  "phoneNumber": "+16501234567"
}

CustomPushMessage

包含要求的 OrderUpdate。

下表列出 CustomPushMessage 類型的屬性：

屬性 類型 說明
orderUpdate OrderUpdate

必填。

訂單的最新資訊。

以下範例顯示 CustomPushMessage 元素：

範例

{
  "orderUpdate": {
    "actionOrderId": "sample_action_order_id",
    "orderState": {
      "state": "IN_TRANSIT",
      "label": "Order is on the way"
    },
    "inTransitInfo": {
      "updatedTime": "2017-07-17T12:00:00Z"
    },
    "updateTime": "2017-07-17T12:00:00Z",
    "orderManagementActions": [
      {
        "type": "CUSTOMER_SERVICE",
        "button": {
          "title": "Contact customer service",
          "openUrlAction": {
            "url": "mailto:support@example.com"
          }
        }
      },
      {
        "type": "EMAIL",
        "button": {
          "title": "Email restaurant",
          "openUrlAction": {
            "url": "mailto:person@example.com"
          }
        }
      },
      {
        "type": "CALL_RESTAURANT",
        "button": {
          "title": "Call restaurant",
          "openUrlAction": {
            "url": "tel:+16505554679"
          }
        }
      }
    ],
    "receipt": {
      "userVisibleOrderId": "userVisibleId1234"
    },
    "infoExtension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
      "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
    }
  }
}

DeliveryInfo

下表列出 DeliveryInfo 類型的屬性：

屬性 類型 說明
deliveryTimeIso8601 String

預估送達時間，採用 ISO 8601 時間戳記格式：「{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z」或持續時間格式：「P(n)Y(n)M(n)DT(n)H(n)M(n)S」。舉例來說，PT90M 代表 90 分鐘的時間長度。預設值「PT0M」表示偏好的提交時間是盡快提交。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. 在結帳回應期間，使用這項參數更新預估送達時間。

範例：PT90M

以下範例顯示 DeliveryInfo 元素：

範例

{
  "deliveryTimeIso8601": "PT90M"
}

免責事項

下表列出 Disclaimer 類型的屬性：

屬性 類型 說明
predefinedMessage PredefinedMessage

必填。

在結帳時顯示預先定義的免責事項訊息。
feeAmount Money

合作夥伴會向商家收取這筆訂單的 N 元費用。
feeAmountRange FeeAmountRange

合作夥伴會向餐廳收取每筆訂單 N 到 M 的費用。
feePercent Number

合作夥伴會向商家收取這筆訂單的 N% 費用。
feePercentRange FeePercentRange

合作夥伴會向商家收取每筆訂單 N% 到 M% 的費用。

以下範例顯示 Disclaimer 元素：

範例 1

{
  "predefinedMessage": "NEW_YORK_DELIVERY_FEE_TIP_DISCLAIMER"
}

範例 2

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE"
}

範例 3

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feePercent": 25
}

示例 4

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feePercentRange": {
    "minFeePercent": 20,
    "maxFeePercent": 30
  }
}

範例 5

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feeAmount": {
    "currencyCode": "AUD",
    "units": 2,
    "nanos": 500000000
  }
}

範例 6

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feeAmountRange": {
    "minFeeAmount": {
      "currencyCode": "AUD",
      "units": 2,
      "nanos": 500000000
    },
    "maxFeeAmount": {
      "currencyCode": "AUD",
      "units": 10,
      "nanos": 0
    }
  }
}

錯誤

Error 類型可用的值如下：

  • CLOSED：餐廳在下單時間營業時間結束。
  • NO_CAPACITY：沒有可用的服務容量 (例如，因尖峰時段而暫時停機)。
  • NO_COURIER_AVAILABLE：由於送貨人員人數有限，無法處理訂單。
  • REQUIREMENTS_NOT_MET：未符合接受訂單的限制條件 (例如，購物車的最低金額)。
  • UNAVAILABLE_SLOT：訂單無法在 DeliveryInfo 或 PickupInfo 指定的預訂時間內完成。
  • OUT_OF_SERVICE_AREA：訂單無法送達使用者的地址。
  • PROMO_EXPIRED：促銷活動已過期，無法套用。
  • PROMO_NOT_APPLICABLE：通用錯誤代碼，用於偵測所有無法套用促銷代碼的情況 (如果其他促銷代碼錯誤代碼都不符合)。
  • PROMO_NOT_RECOGNIZED：系統無法辨識優待券代碼。
  • PROMO_ORDER_INELIGIBLE：目前的訂單不符合這張優待券的使用資格。
  • PROMO_USER_INELIGIBLE：目前使用者不符合這張優待券的使用資格。
  • AVAILABILITY_CHANGED：商品已售完，或商品數量不足以滿足要求。
  • INCORRECT_PRICE：費用或總價有價格錯誤。
  • INVALID：LineItem、FulfillmentOption 或 Promotion 含有無效資料。
  • NOT_FOUND：找不到明細項目、執行選項或促銷活動。
  • PRICE_CHANGED：商品價格已變更。

FeeAmountRange

下表列出 FeeAmountRange 類型的屬性：

屬性 類型 說明
minFeeAmount Money

收取的費用金額下限。
maxFeeAmount Money

收取的費用金額上限。

FeePercentRange

下表列出 FeePercentRange 類型的屬性：

屬性 類型 說明
minFeePercent Number

收取的費用百分比下限。
maxFeePercent Number

收取的費用百分比上限。

FoodCartExtension

包含使用者詳細資料，例如訂單履行偏好設定。

下表列出 FoodCartExtension 類型的屬性：

屬性 類型 說明
@type Const

這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodCartExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodCartExtension
contact Contact

訂單收件者的聯絡資訊。詳細資料包括使用者名稱、電話號碼和電子郵件地址。
fulfillmentPreference FulfillmentOption

必填。

使用者的出貨偏好設定。
location Location

在 CheckoutRequestMessage 中，這個欄位會指定運送地址，如果訂單需要運送，則必須提供這個欄位。如果是外帶或自取訂單，訊息中不會包含這個欄位。

以下範例顯示 FoodCartExtension 元素：

範例 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
  "fulfillmentPreference": {
    "fulfillmentInfo": {
      "delivery": {
        "deliveryTimeIso8601": "P0M"
      }
    }
  },
  "location": {
    "coordinates": {
      "latitude": 37.788783,
      "longitude": -122.41384
    },
    "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
    "zipCode": "94043",
    "city": "Mountain View",
    "postalAddress": {
      "regionCode": "US",
      "postalCode": "94043",
      "administrativeArea": "CA",
      "locality": "Mountain View",
      "addressLines": [
        "1350 Charleston Road"
      ]
    },
    "notes": "Gate code is #111"
  }
}

範例 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
  "fulfillmentPreference": {
    "fulfillmentInfo": {
      "pickup": {
        "pickupTimeIso8601": "P0M"
      }
    }
  },
  "contact": {
    "displayName": "Lovefood Ordering",
    "email": "ilovefood@example.com",
    "phoneNumber": "+16501234567"
  }
}

FoodErrorExtension

指出處理要求時發生一或多個錯誤。下表說明 FoodErrorExtension 類型的欄位。您可以透過 CheckoutResponse 傳送錯誤。

下表列出 FoodErrorExtension 類型的屬性：

屬性 類型 說明
@type Const

必填。

這個擴充功能的類型。

值：type.googleapis.com/google.actions.v2.orders.FoodErrorExtension
foodOrderErrors List<FoodOrderError>

必填。

描述發生錯誤的 FoodOrderError 物件陣列。建議每個購物車或每項商品只出現一個錯誤。

必須至少包含 1 個項目。
correctedProposedOrder ProposedOrder

foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED" 為必要屬性。

修正後的新 ProposedOrder。如果原始 ProposedOrder 中有可復原的錯誤，就會傳回這個物件。舉例來說，購物車中一或多個委刊項的價格變更，就是可復原的錯誤。針對有效的 ProposedOrder，可復原的錯誤會提前至確認階段，而不會要求使用者查看購物車。
paymentOptions PaymentOptions

foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED" 為必要屬性。

為使用者選取的預設付款方式。
additionalPaymentOptions List<PaymentOptions>

使用者可使用的其他付款方式。

以下範例顯示 FoodErrorExtension 元素：

範例

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
  "foodOrderErrors": [
    {
      "error": "PRICE_CHANGED",
      "id": "sample_item_offer_id_1",
      "description": "The price has changed.",
      "updatedPrice": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 750000000
      }
    },
    {
      "error": "PRICE_CHANGED",
      "id": "sample_item_offer_id_2",
      "description": "The price has changed.",
      "updatedPrice": {
        "currencyCode": "USD",
        "units": "8"
      }
    }
  ],
  "correctedProposedOrder": {
    "id": "sample_corrected_proposed_order_id_1",
    "otherItems": [
      {
        "name": "New customer discount",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "-5",
            "nanos": -500000000
          }
        },
        "type": "DISCOUNT"
      },
      {
        "name": "Delivery fee",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "3",
            "nanos": 500000000
          }
        },
        "type": "DELIVERY"
      },
      {
        "name": "Tax",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "1",
            "nanos": 500000000
          }
        },
        "type": "TAX"
      }
    ],
    "cart": {
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Falafel Bite"
      },
      "lineItems": [
        {
          "name": "Pita Chips",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        },
        {
          "name": "Chicken Shwarma Wrap",
          "type": "REGULAR",
          "id": "sample_item_offer_id_2",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "8"
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Greek Salad",
          "type": "REGULAR",
          "id": "sample_item_offer_id_3",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "9",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Prawns Biryani",
          "type": "REGULAR",
          "id": "sample_item_offer_id_4",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "15",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          }
        },
        "location": {
          "coordinates": {
            "latitude": 37.788783,
            "longitude": -122.41384
          },
          "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
          "zipCode": "94043",
          "city": "Mountain View",
          "postalAddress": {
            "regionCode": "US",
            "postalCode": "94043",
            "administrativeArea": "CA",
            "locality": "Mountain View",
            "addressLines": [
              "1350 Charleston Road"
            ]
          },
          "notes": "Gate code is #111"
        }
      }
    },
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "36",
        "nanos": 730000000
      }
    },
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ]
    }
  },
  "paymentOptions": {
    "googleProvidedOptions": {
      "tokenizationParameters": {
        "tokenizationType": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "stripe",
          "stripe:publishableKey": "pk_live_stripe_client_key",
          "stripe:version": "2017-04-06"
        }
      },
      "supportedCardNetworks": [
        "AMEX",
        "DISCOVER",
        "MASTERCARD",
        "JCB",
        "VISA"
      ],
      "prepaidCardDisallowed": true
    }
  }
}

FoodItemExtension

定義食品項目的加料。

下表列出 FoodItemExtension 類型的屬性：

屬性 類型 說明
@type Const

必填。

這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodItemExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodItemExtension
options List<FoodItemOption>

選項可以是附加商品項目，也可以是包含一組附加商品的附加商品群組。

以下範例顯示 FoodItemExtension 元素：

範例

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
  "options": [
    {
      "id": "sample_addon_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
      "name": "Honey Mustard",
      "price": {
        "currencyCode": "USD"
      },
      "quantity": 1
    },
    {
      "id": "sample_addon_offer_id_2",
      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
      "name": "BBQ Sauce",
      "price": {
        "currencyCode": "USD",
        "nanos": 500000000
      },
      "quantity": 1,
      "subOptions": [
        {
          "id": "10239138",
          "offerId": "912391723",
          "name": "Fries",
          "price": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 230000000
          },
          "quantity": 1
        }
      ]
    }
  ]
}

FoodItemOption

下表列出 FoodItemOption 類型的屬性：

屬性 類型 說明
id String

Google 指派的專屬 ID。傳送 FoodOrderError 或 AsyncOrderUpdateRequest 時，如果購物車中有多個 offerId 相同的項目，請使用這個欄位進行區分。

範例：39231093
offerId String

商品的優惠 ID。

範例：912835081
name String

選項名稱。

範例：Honey Mustard
price Money
note String

與選項相關的註解。
quantity Number

如果選項是項目，則為項目數。

範例：3
subOptions List<FoodItemOption>

選項的子選項 (如果有)。

範例：[ { "id": "71283712", "offerId": "51209121", "name": "BBQ Sauce", "price": { "currencyCode": "USD", "units": "3", "nanos": 780000000 }, "quantity": 2 }, { "id": "102941024", "offerId": "12084102", "name": "Ketchup", "price": { "currencyCode": "USD", "units": "2", "nanos": 980000000 }, "quantity": 6 } ]

以下範例顯示 FoodItemOption 元素：

範例 1

{
  "id": "10293231",
  "offerId": "1918491",
  "name": "Honey Mustard",
  "price": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  },
  "quantity": 5
}

範例 2

{
  "id": "123166552",
  "offerId": "912849184",
  "name": "Make It A Meal",
  "price": {
    "currencyCode": "USD",
    "units": "3",
    "nanos": 730000000
  },
  "quantity": 1,
  "subOptions": [
    {
      "id": "10239138",
      "offerId": "912391723",
      "name": "Fries",
      "price": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 230000000
      },
      "quantity": 1
    },
    {
      "id": "57159183",
      "offerId": "81837123",
      "name": "Drink",
      "price": {
        "currencyCode": "USD",
        "units": "3",
        "nanos": 130000000
      },
      "quantity": 1
    }
  ]
}

FoodOrderError

包含 CheckoutResponse 中的錯誤詳細資料。

下表列出 FoodOrderError 類型的屬性：

屬性 類型 說明
error Error

必填。
id String

error = "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "PRICE_CHANGED", "INVALID", or "NOT_FOUND" 為必要屬性。

這是商品層級錯誤的必填欄位。對於菜單項目，這是 Google 指派的 LineItem.id；對於加購商品，則是 FoodItemOption.id。
description String

錯誤說明。這項說明是供內部記錄使用，不會向使用者顯示。
updatedPrice Money

error = "PRICE_CHANGED" 為必要屬性。

導致錯誤的商品新價格。只有在錯誤為「PRICE_CHANGED」時，才需要這個值。
availableQuantity 整數

error = "INVALID", or "NOT_FOUND" 為必要屬性。

導致錯誤的商品新可用數量。只有在錯誤為「INVALID」或「NOT_FOUND」時，才需要提供這個屬性。如果是「INVALID」和「NOT_FOUND」，則值應為零。

以下範例顯示 FoodOrderError 元素：

範例 1

{
  "error": "CLOSED",
  "description": "This store is currently reachable. Please try again later."
}

範例 2

{
  "error": "PRICE_CHANGED",
  "id": "french_fries",
  "description": "The price has changed.",
  "updatedPrice": {
    "currencyCode": "USD",
    "units": "2",
    "nanos": 750000000
  }
}

FoodOrderExtension

包含訂單的執行資訊。

下表列出 FoodOrderExtension 類型的屬性：

屬性 類型 說明
@type Const

這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodOrderExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodOrderExtension
availableFulfillmentOptions List<FulfillmentOption>

代表訂單的可用出貨選項。
optinForRemarketing 布林值

使用者要求加入行銷管道。根據預設，您必須取得使用者同意，才能傳送行銷內容。如果 optinForRemarketing 為 true，您可以訂閱使用者。如果 optinForRemarketing 為 false 或不存在，您必須在系統中維持訂閱狀態。使用者無法透過 Google 選擇退出，只能透過行銷管道提供的取消訂閱功能。這個旗標僅會出現在 SubmitOrderRequestMessage 中。

以下範例顯示 FoodOrderExtension 元素：

範例 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
  "availableFulfillmentOptions": [
    {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P0M"
        }
      },
      "expiresAt": "2017-07-17T12:30:00Z"
    }
  ]
}

範例 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
  "availableFulfillmentOptions": [
    {
      "fulfillmentInfo": {
        "pickup": {
          "pickupTimeIso8601": "P0M"
        }
      },
      "expiresAt": "2020-08-20T11:41:00Z"
    }
  ],
  "optinForRemarketing": true
}

FulfillmentOption

您可以透過以下方式使用 FulfillmentOption 物件：
  • 在 Checkout AppRequest 和 Submit AppRequest 中，Cart.extension.fulfillmentPreference：儲存使用者的偏好設定 (外送或自取)。傳送結帳要求時，價格一律為 0。
  • 在 Checkout AppResponse 中，ProposedOrder.extension.availableFulfillmentOptions 會定義一或多個提交選項 (目前僅支援一個選項)。您可以在 ProposedOrder.otherItems 中將預設選項指定為 LineItem。FulfillmentOption 的 offerId 應與 ProposedOrder.otherItems 中指定的 LineItem ID 相符。

下表列出 FulfillmentOption 類型的屬性：

屬性 類型 說明
offerId String

這個履行選項的專屬 ID (如果有的話)。
fulfillmentInfo FulfillmentOptionInfo

必填。
expiresAt ISO 時間戳記

這個執行要求選項的到期時間。
price Money

這個選項的費用。

以下範例顯示 FulfillmentOption 元素：

範例

{
  "offerId": "offer5",
  "fulfillmentInfo": {
    "pickup": {
      "pickupTimeIso8601": "P0M"
    }
  },
  "expiresAt": "2019-05-02T00:00:00-07:00",
  "price": {
    "currencyCode": "USD",
    "units": "5",
    "nanos": 230000000
  }
}

FulfillmentOptionInfo

定義與 FulfillmentInfo 相關的資訊。

下表列出 FulfillmentOptionInfo 類型的屬性：

屬性 類型 說明
必須提供下列其中一個屬性組合。
delivery 群組 1 DeliveryInfo

如果有的話，表示運送順序。
pickup 群組 2 PickupInfo

如果存在，則表示取貨訂單。

圖片

下表列出 Image 類型的屬性：

屬性 類型 說明
sourceUrl String

必填。

圖片的網址。圖片大小至少須為 72x72 像素。為達最佳效果，請使用至少 216 x 216 像素的圖片。圖片大小必須小於 6 MB 且小於 6,400 萬像素。

LineItem

定義購物車內容 (Cart.lineItems) 或訂單的額外費用 (ProposedOrder.otherItems)。

下表列出 LineItem 類型的屬性：

屬性 類型 說明
id String

type = "REGULAR" 為必要屬性。

就購物車中的商品而言 (ProposedOrder.cart.lineItems[0].id)，這是 Google 在建立訂單時建立的專屬 ID。針對 ProposedOrder 中的 LineItem (ProposedOrder.otherItems[0].id)，也就是用於新增運費和稅金等項目，ID 值是由供應商定義。舉例來說，購物車中含有兩項相同商品，但兩者有不同的製作說明 (例如兩個中型比薩，配料不同)。在這種情況下，兩項商品都具有相同的基本 offerId。當您傳送訂單更新要求，表示某項商品遭到拒絕時，請使用這個 ID 做為歧義解除器。換句話說，如果其中一個披薩因缺少特定配料而遭拒，ID 可協助 Google 判斷你所指的是訂單中的哪項商品。除了 otherItems 以外，這是必填欄位。
name String

必填。

委刊項的名稱。這是向使用者顯示的字串，因此應盡可能使用句子大小寫 (例如「運費」、「服務費」、「稅金」)。這個欄位會截斷至使用者輸入的 100 個半形字元。
type LineItemType

必填。
quantity 整數

type = "REGULAR" 為必要屬性。

包含的項目數量。不適用於 ProposedOrder.otherItems。
description String

項目說明。
price Price

必填。

商品的價格。這個值代表此委刊項所有商品或服務的總價 (也就是將所有加購商品的費用加總，再乘以數量)。舉例來說，如果商品價格為 $10 美元，數量為 3，則價格為 $30 美元。一個披薩的基本價格為 $5 美元，加購 $1 美元的配料，總價為 $6 美元。假設有兩個披薩 (數量 = 2)，基本價格為 $5 美元，每個加購項目的價格為 $1 美元，則總價為 $12 美元。每個 LineItem 都應有價格，即使價格為「0」也一樣。如果類型為 DISCOUNT，請將值指定為負值 (例如「-2」)。
subLines List<SublineNote>

選用，僅在類型為「REGULAR」時有效。使用者可能會在結帳要求和提交訂單要求的這個欄位中，傳送商品相關的備註。請務必在提供備註時，確保商家收到備註。在要求中，這個值會以 subLines[0].note 的形式出現，這是在要求中出現時，這個欄位中唯一提供的值。

項目數量不得超過 1 個。
offerId String

type = "REGULAR" 為必要屬性。

商品的 MenuItem 優惠 ID。不適用於 ProposedOrder.otherItems。
extension FoodItemExtension

定義食品項目的加料。

以下範例顯示 LineItem 元素：

範例 1

{
  "name": "New customer discount",
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "-5",
      "nanos": -500000000
    }
  },
  "type": "DISCOUNT"
}

範例 2

{
  "name": "Pita Chips",
  "type": "REGULAR",
  "id": "sample_item_offer_id_1",
  "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
  "quantity": 1,
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "2",
      "nanos": 750000000
    }
  },
  "subLines": [
    {
      "note": "Notes for this item."
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
    "options": [
      {
        "id": "sample_addon_offer_id_1",
        "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
        "name": "Honey Mustard",
        "price": {
          "currencyCode": "USD"
        },
        "quantity": 1
      },
      {
        "id": "sample_addon_offer_id_2",
        "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
        "name": "BBQ Sauce",
        "price": {
          "currencyCode": "USD",
          "nanos": 500000000
        },
        "quantity": 1
      }
    ]
  }
}

LineItemType

LineItemType 類型可用的值如下：

  • REGULAR：商品明細。適用於 Cart.lineItems。
  • TAX：稅金明細項目。適用於 ProposedOrder.otherItems。
  • DISCOUNT：折扣明細。請注意，價格應為負數。適用於 ProposedOrder.otherItems。
  • GRATUITY：小費委刊項。通常是為使用者選取的小費保留的 SubmitOrderRequestMessage。適用於 ProposedOrder.otherItems。
  • DELIVERY：放送委刊項。適用於 ProposedOrder.otherItems。
  • SUBTOTAL：小計明細。適用於 ProposedOrder.otherItems。
  • FEE：其他類型未涵蓋的其他委刊項。適用於 ProposedOrder.otherItems。

位置

指定訂餐地址。Location 類型用於 Cart，僅用於表示運送訂單的目的地的資訊。如果使用者下單，系統也會在 TransactionDecisionValue 中顯示最終位置。如果訂單指定自取，則完全不包含位置 (甚至不包含空白位置)。

下表列出 Location 類型的屬性：

屬性 類型 說明
coordinates Coordinates
formattedAddress String

顯示位置的地址。

範例：1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States
postalAddress PostalAddress
zipCode String

範例：90210
city String

城市名稱。

範例：Los Angeles
notes String

關於地點的附註，例如門禁密碼。長度不得超過 500 個字元。

範例：Gate code is #111

以下範例顯示 Location 元素：

範例

{
  "coordinates": {
    "latitude": 37.788783,
    "longitude": -122.41384
  },
  "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
  "zipCode": "94043",
  "city": "Mountain View",
  "postalAddress": {
    "regionCode": "US",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1350 Charleston Road"
    ]
  },
  "notes": "Gate code is #111"
}

商家

下表列出 Merchant 類型的屬性：

屬性 類型 說明
id String

商家 ID。如果指定，則會與餐廳動態饋給中的 Restaurant.@id 相符。

範例：https://www.exampleprovider.com/merchant/id1
name String

必填。

使用者可查看的商家名稱。

範例：Falafel Bite

以下範例顯示 Merchant 元素：

範例

{
  "id": "https://www.exampleprovider.com/merchant/id1",
  "name": "Falafel Bite"
}

金額

下表列出 Money 類型的屬性：

屬性 類型 說明
currencyCode String

必填。

以 ISO 4217 格式表示的 3 個英文字母貨幣代碼。

範例：USD
units String

金額的整數單位。舉例來說，如果 currencyCode 為「USD」，則「1」單位為 1 美元。

範例：36
nanos 整數

金額的十億分之一 (10^-9) 單位數量。這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。請遵守下列規則：如果 units 為正值，nanos 必須為正值或零；如果 units 為零，則 nanos 可為正值、零或負值；如果 units 為負值，nanos 就必須為負值或零。例如，$-1.75 美元的表記方式為 units = -1 和 nanos = -750,000,000。

範例：730000000

以下範例顯示 Money 元素：

範例 1

{
  "currencyCode": "USD",
  "units": "36",
  "nanos": 730000000
}

範例 2

{
  "currencyCode": "EUR",
  "units": "10"
}

訂單

包含最終訂單，包括稅金、費用和運費，以及付款資訊。您的 Submit AppRequest 會接收這個物件。

下表列出 Order 類型的屬性：

屬性 類型 說明
finalOrder ProposedOrder

必填。

導致訂單產生的提案。
googleOrderId String

必填。

Google 指派的訂單 ID。這個 ID 應在訂單的整個生命週期中保持穩定。使用者不會看到這個 ID。
orderDate ISO 時間戳記

必填。

訂單建立的日期和時間。
paymentInfo PaymentInfo

必填。

與這筆訂單付款相關的付款資訊。

以下範例顯示 Order 元素：

範例

{
  "finalOrder": {
    "cart": {
      "notes": "Guest prefers their food to be hot when it is delivered.",
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Cucina Venti"
      },
      "lineItems": [
        {
          "name": "Sizzling Prawns Dinner",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "16",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "pickup": {
              "pickupTimeIso8601": "P0M"
            }
          }
        },
        "contact": {
          "displayName": "Lovefood Ordering",
          "email": "ilovefood@example.com",
          "phoneNumber": "+16501234567"
        }
      }
    },
    "otherItems": [
      {
        "name": "Service fee",
        "type": "FEE",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "3",
            "nanos": 500000000
          }
        }
      },
      {
        "name": "Tax",
        "type": "TAX",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "1",
            "nanos": 370000000
          }
        }
      },
      {
        "name": "Tip",
        "type": "GRATUITY",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 590000000
          }
        }
      }
    ],
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "23",
        "nanos": 710000000
      }
    },
    "id": "sample_final_order_id",
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "pickup": {
              "pickupTimeIso8601": "P0M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ],
      "optinForRemarketing": true
    }
  },
  "googleOrderId": "sample_google_order_id",
  "orderDate": "2017-07-17T12:00:00Z",
  "paymentInfo": {
    "displayName": "Visa\u2006****\u20061111",
    "googleProvidedPaymentInstrument": {
      "instrumentToken": "abcd"
    },
    "paymentType": "PAYMENT_CARD"
  }
}

OrderUpdate

下表說明 AppResponse 中包含的 OrderUpdate 類型欄位。

下表列出 OrderUpdate 類型的屬性：

屬性 類型 說明
actionOrderId String

必填。

整合服務供應商系統中訂單的專屬 ID，用於識別要傳送更新的訂單。如果在「CREATED」訂單的 OrderUpdate 中，至少未提供一次 receipt.user_visible_order_id，則這個 ID 會是 Google 訂單資訊卡中顯示的輸入使用者可見 ID。
orderState OrderState

必填。

訂單的新狀態。
lineItemUpdates Map<String, LineItemUpdate>
updateTime ISO 時間戳記

必填。

更新訂單的時間。
orderManagementActions List<OrderManagementAction>

訂單後續動作，例如聯絡支援團隊和查看訂單詳細資料。

必須包含至少 1 個項目，且最多 6 個項目。
rejectionInfo RejectionInfo

orderState.state = "REJECTED" 為必要屬性。
cancellationInfo CancellationInfo

orderState.state = "CANCELLED" 為必要屬性。
inTransitInfo InTransitInfo

這個欄位已淘汰。
fulfillmentInfo FulfillmentInfo

這個欄位已淘汰。
receipt Receipt

orderState.state = "CONFIRMED", "IN_PREPARATION", or "READY_FOR_PICKUP" 為必要屬性。

在收據中提供可供使用者查看的訂單 ID。
totalPrice Price

訂單總價。
infoExtension FoodOrderUpdateExtension

定義訂單更新的更多詳細資料，例如預估送達或取貨的間隔。

以下範例顯示 OrderUpdate 元素：

範例

{
  "actionOrderId": "sample_action_order_id",
  "orderState": {
    "state": "CONFIRMED",
    "label": "Provider confirmed"
  },
  "totalPrice": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "41",
      "nanos": 600000000
    }
  },
  "lineItemUpdates": {
    "sample_item_id_1": {
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "3",
          "nanos": 500000000
        }
      },
      "reason": "This item has an updated price."
    }
  },
  "receipt": {
    "userVisibleOrderId": "userVisibleId1234"
  },
  "updateTime": "2017-07-17T12:00:00Z",
  "orderManagementActions": [
    {
      "type": "CUSTOMER_SERVICE",
      "button": {
        "title": "Contact customer service",
        "openUrlAction": {
          "url": "mailto:support@example.com"
        }
      }
    },
    {
      "type": "EMAIL",
      "button": {
        "title": "Email restaurant",
        "openUrlAction": {
          "url": "mailto:person@example.com"
        }
      }
    },
    {
      "type": "CALL_RESTAURANT",
      "button": {
        "title": "Call restaurant",
        "openUrlAction": {
          "url": "tel:+16505554679"
        }
      }
    }
  ],
  "infoExtension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
    "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
  }
}

PickupInfo

下表列出 PickupInfo 類型的屬性：

屬性 類型 說明
pickupTimeIso8601 String

預估上車時間，格式為 ISO 8601 時間戳記格式：「{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z」或時間長度格式：「P(n)Y(n)M(n)DT(n)H(n)M(n)S」。舉例來說，PT90M 代表 90 分鐘的時間長度。預設值「PT0M」表示偏好的上車時間是盡快。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. 在結帳回應中使用此參數，更新預估取車時間。

範例：PT90M

以下範例顯示 PickupInfo 元素：

範例

{
  "pickupTimeIso8601": "PT90M"
}

PostalAddress

下表列出 PostalAddress 類型的屬性：

屬性 類型 說明
regionCode String

必填。

包含兩個英文字母的國家/地區代碼。

範例：US
postalCode String

郵遞區號。

範例：94043
administrativeArea String

最高行政區，用於國家/地區的郵遞地址。例如州、省或縣。

範例：CA
locality String

這個地點的城市或城鎮。如為未明確定義縣市或其縣市不適用此結構的地區，請不要指定縣市，改用 addressLines 欄位。

範例：Mountain View
addressLines List<String>

一或多行可用來指定街道地址。這個欄位可能包含不清楚的地區，因此不應修改。

範例：[ "1350 Charleston Road" ]
recipients List<String>

訂單的收件者清單。這個欄位僅適用於 billingAddress。

以下範例顯示 PostalAddress 元素：

範例

{
  "regionCode": "US",
  "postalCode": "94043",
  "administrativeArea": "CA",
  "locality": "Mountain View",
  "addressLines": [
    "1350 Charleston Road"
  ]
}

價格

下表列出 Price 類型的屬性：

屬性 類型 說明
type Enum [ "ESTIMATE", "ACTUAL" ]

必填。

促銷優待券代碼。
amount Money

必填。

宣傳

下表列出 Promotion 類型的屬性：

屬性 類型 說明
coupon String

必填。

促銷優待券代碼。

ProposedOrder

下表列出 ProposedOrder 類型的屬性：

屬性 類型 說明
id String

建議訂單的選用 ID。
cart Cart

必填。

使用者的商品。
otherItems List<LineItem>

供應商新增的項目，例如運費、其他費用和稅金。otherItems 也可能包含使用者新增的小費和/或折扣。

最多只能包含 10 個項目。
image Image

與提案訂單相關聯的圖片。
totalPrice Price

必填。

提案訂單的總價。
extension FoodOrderExtension

必填。

定義餐點訂單的履行資訊。
disclaimers List<Disclaimer>

對應至在下單前，會在 UI 中顯示的免責事項訊息。

以下範例顯示 ProposedOrder 元素：

範例

{
  "id": "sample_proposed_order_id_1",
  "otherItems": [
    {
      "name": "New customer discount",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "-5",
          "nanos": -500000000
        }
      },
      "type": "DISCOUNT"
    },
    {
      "name": "Delivery fee",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "3",
          "nanos": 500000000
        }
      },
      "type": "DELIVERY"
    },
    {
      "name": "Tax",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "1",
          "nanos": 500000000
        }
      },
      "type": "TAX"
    }
  ],
  "cart": {
    "merchant": {
      "id": "https://www.exampleprovider.com/merchant/id1",
      "name": "Falafel Bite"
    },
    "lineItems": [
      {
        "name": "Pita Chips",
        "type": "REGULAR",
        "id": "sample_item_offer_id_1",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 750000000
          }
        },
        "subLines": [
          {
            "note": "Notes for this item."
          }
        ],
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
          "options": [
            {
              "id": "sample_addon_offer_id_1",
              "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
              "name": "Honey Mustard",
              "price": {
                "currencyCode": "USD"
              },
              "quantity": 1
            },
            {
              "id": "sample_addon_offer_id_2",
              "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
              "name": "BBQ Sauce",
              "price": {
                "currencyCode": "USD",
                "nanos": 500000000
              },
              "quantity": 1
            }
          ]
        }
      },
      {
        "name": "Chicken Shwarma Wrap",
        "type": "REGULAR",
        "id": "sample_item_offer_id_2",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "8"
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      },
      {
        "name": "Greek Salad",
        "type": "REGULAR",
        "id": "sample_item_offer_id_3",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "9",
            "nanos": 990000000
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      },
      {
        "name": "Prawns Biryani",
        "type": "REGULAR",
        "id": "sample_item_offer_id_4",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "15",
            "nanos": 990000000
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      }
    ],
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
      "fulfillmentPreference": {
        "fulfillmentInfo": {
          "delivery": {
            "deliveryTimeIso8601": "P90M"
          }
        }
      },
      "location": {
        "coordinates": {
          "latitude": 37.788783,
          "longitude": -122.41384
        },
        "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
        "zipCode": "94043",
        "city": "Mountain View",
        "postalAddress": {
          "regionCode": "US",
          "postalCode": "94043",
          "administrativeArea": "CA",
          "locality": "Mountain View",
          "addressLines": [
            "1350 Charleston Road"
          ]
        },
        "notes": "Gate code is #111"
      }
    }
  },
  "totalPrice": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "36",
      "nanos": 730000000
    }
  },
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
    "availableFulfillmentOptions": [
      {
        "fulfillmentInfo": {
          "delivery": {
            "deliveryTimeIso8601": "P0M"
          }
        },
        "expiresAt": "2017-07-17T12:30:00Z"
      }
    ]
  }
}

SublineNote

下表列出 SublineNote 類型的屬性：

屬性 類型 說明
note String

必填。

時間戳記

日期和時間，格式如下： "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"

TransactionDecisionValue

包含 Order。

下表列出 TransactionDecisionValue 類型的屬性：

屬性 類型 說明
order Order

必填。

要下單的訂單，並附上付款詳細資料。

以下範例顯示 TransactionDecisionValue 元素：

範例

{
  "order": {
    "finalOrder": {
      "cart": {
        "notes": "Guest prefers their food to be hot when it is delivered.",
        "merchant": {
          "id": "https://www.exampleprovider.com/merchant/id1",
          "name": "Cucina Venti"
        },
        "lineItems": [
          {
            "name": "Sizzling Prawns Dinner",
            "type": "REGULAR",
            "id": "sample_item_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
            "quantity": 1,
            "price": {
              "type": "ESTIMATE",
              "amount": {
                "currencyCode": "USD",
                "units": "16",
                "nanos": 750000000
              }
            },
            "subLines": [
              {
                "note": "Notes for this item."
              }
            ],
            "extension": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
              "options": [
                {
                  "id": "sample_addon_offer_id_1",
                  "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                  "name": "Honey Mustard",
                  "price": {
                    "currencyCode": "USD"
                  },
                  "quantity": 1
                },
                {
                  "id": "sample_addon_offer_id_2",
                  "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                  "name": "BBQ Sauce",
                  "price": {
                    "currencyCode": "USD",
                    "nanos": 500000000
                  },
                  "quantity": 1
                }
              ]
            }
          }
        ],
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
          "fulfillmentPreference": {
            "fulfillmentInfo": {
              "pickup": {
                "pickupTimeIso8601": "P0M"
              }
            }
          },
          "contact": {
            "displayName": "Lovefood Ordering",
            "email": "ilovefood@example.com",
            "phoneNumber": "+16501234567"
          }
        }
      },
      "otherItems": [
        {
          "name": "Service fee",
          "type": "FEE",
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "3",
              "nanos": 500000000
            }
          }
        },
        {
          "name": "Tax",
          "type": "TAX",
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "1",
              "nanos": 370000000
            }
          }
        },
        {
          "name": "Tip",
          "type": "GRATUITY",
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 590000000
            }
          }
        }
      ],
      "totalPrice": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "23",
          "nanos": 710000000
        }
      },
      "id": "sample_final_order_id",
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
        "availableFulfillmentOptions": [
          {
            "fulfillmentInfo": {
              "pickup": {
                "pickupTimeIso8601": "P0M"
              }
            },
            "expiresAt": "2017-07-17T12:30:00Z"
          }
        ],
        "optinForRemarketing": true
      }
    },
    "googleOrderId": "sample_google_order_id",
    "orderDate": "2017-07-17T12:00:00Z",
    "paymentInfo": {
      "displayName": "Visa\u2006****\u20061111",
      "googleProvidedPaymentInstrument": {
        "instrumentToken": "abcd"
      },
      "paymentType": "PAYMENT_CARD"
    }
  }
}

履行要求

AppRequest

下表列出 AppRequest 類型的屬性：

屬性 類型 說明
isInSandbox 布林值

指出後續交易是否在沙箱環境中完成。
conversation Conversation
inputs List<Input>

必填。

包含結帳購物車的預期引數。

必須有 1 個項目。

以下範例顯示 AppRequest 元素：

範例 1

{
  "isInSandbox": true,
  "inputs": [
    {
      "intent": "actions.foodordering.intent.CHECKOUT",
      "arguments": [
        {
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.Cart",
            "merchant": {
              "id": "https://www.exampleprovider.com/merchant/id1",
              "name": "Cucina Venti"
            },
            "lineItems": [
              {
                "name": "Sizzling Prawns Dinner",
                "type": "REGULAR",
                "id": "sample_item_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                "quantity": 1,
                "price": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "16",
                    "nanos": 750000000
                  }
                },
                "subLines": [
                  {
                    "note": "Notes for this item."
                  }
                ],
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                  "options": [
                    {
                      "id": "sample_addon_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                      "name": "Honey Mustard",
                      "price": {
                        "currencyCode": "USD"
                      },
                      "quantity": 1
                    },
                    {
                      "id": "sample_addon_offer_id_2",
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                      "name": "BBQ Sauce",
                      "price": {
                        "currencyCode": "USD",
                        "nanos": 500000000
                      },
                      "quantity": 1
                    }
                  ]
                }
              }
            ],
            "extension": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
              "fulfillmentPreference": {
                "fulfillmentInfo": {
                  "delivery": {
                    "deliveryTimeIso8601": "P0M"
                  }
                }
              },
              "location": {
                "coordinates": {
                  "latitude": 37.788783,
                  "longitude": -122.41384
                },
                "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
                "zipCode": "94043",
                "city": "Mountain View",
                "postalAddress": {
                  "regionCode": "US",
                  "postalCode": "94043",
                  "administrativeArea": "CA",
                  "locality": "Mountain View",
                  "addressLines": [
                    "1350 Charleston Road"
                  ]
                },
                "notes": "Gate code is #111"
              }
            }
          }
        }
      ]
    }
  ]
}

範例 2

{
  "isInSandbox": true,
  "inputs": [
    {
      "intent": "actions.intent.TRANSACTION_DECISION",
      "arguments": [
        {
          "transactionDecisionValue": {
            "order": {
              "finalOrder": {
                "cart": {
                  "notes": "Guest prefers their food to be hot when it is delivered.",
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Cucina Venti"
                  },
                  "lineItems": [
                    {
                      "name": "Sizzling Prawns Dinner",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "16",
                          "nanos": 750000000
                        }
                      },
                      "subLines": [
                        {
                          "note": "Notes for this item."
                        }
                      ],
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                        "options": [
                          {
                            "id": "sample_addon_offer_id_1",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                            "name": "Honey Mustard",
                            "price": {
                              "currencyCode": "USD"
                            },
                            "quantity": 1
                          },
                          {
                            "id": "sample_addon_offer_id_2",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                            "name": "BBQ Sauce",
                            "price": {
                              "currencyCode": "USD",
                              "nanos": 500000000
                            },
                            "quantity": 1
                          }
                        ]
                      }
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    },
                    "contact": {
                      "displayName": "Lovefood Ordering",
                      "email": "ilovefood@example.com",
                      "phoneNumber": "+16501234567"
                    }
                  }
                },
                "otherItems": [
                  {
                    "name": "Service fee",
                    "type": "FEE",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    }
                  },
                  {
                    "name": "Tax",
                    "type": "TAX",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 370000000
                      }
                    }
                  },
                  {
                    "name": "Tip",
                    "type": "GRATUITY",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "2",
                        "nanos": 590000000
                      }
                    }
                  }
                ],
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "23",
                    "nanos": 710000000
                  }
                },
                "id": "sample_final_order_id",
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2017-07-17T12:30:00Z"
                    }
                  ],
                  "optinForRemarketing": true
                }
              },
              "googleOrderId": "sample_google_order_id",
              "orderDate": "2017-07-17T12:00:00Z",
              "paymentInfo": {
                "displayName": "Visa\u2006****\u20061111",
                "googleProvidedPaymentInstrument": {
                  "instrumentToken": "abcd"
                },
                "paymentType": "PAYMENT_CARD"
              }
            }
          }
        }
      ]
    }
  ]
}

CheckoutRequestMessage

CheckoutRequestMessage 是具有 actions.foodordering.intent.CHECKOUT 意圖的 AppRequest。

SubmitOrderRequestMessage

SubmitOrderRequestMessage 是具有 actions.foodordering.intent.TRANSACTION_DECISION 意圖的 AppRequest。

對話

Conversation 只會出現在一個工作階段。您可以視需要使用此方法連結多個 Checkout 和 SubmitOrder 動作。

下表列出 Conversation 類型的屬性：

屬性 類型 說明
conversationId String

必填。

對話的專屬 ID。

以下範例顯示 Conversation 元素：

範例

{
  "conversationId": "CQnJ7Z4i7UmvEZ9ph3AxyZRJ"
}

輸入

結帳時的預期引數。

下表列出 Input 類型的屬性：

屬性 類型 說明
intent Enum [ "actions.foodordering.intent.CHECKOUT", "actions.intent.TRANSACTION_DECISION" ]

必填。

如要傳送結帳要求訊息，請將其設為「actions.foodordering.intent.CHECKOUT」；如要傳送提交訂單要求訊息，請設為「actions.intent.TRANSACTION_DECISION」。
arguments List<Argument>

必填。

包含要結帳的購物車或要下單的訂單

必須有 1 個項目。

引數

包含使用者想結帳的餐點詳細資料。結帳時，只能使用額外資訊。如要提交訂單，請使用 transactionDecisionValue

下表列出 Argument 類型的屬性：

屬性 類型 說明
必須提供下列其中一個屬性組合。
extension 群組 1 Cart

詳細說明使用者要結帳的餐點。
transactionDecisionValue 群組 2 TransactionDecisionValue

包含要下單的訂單和付款詳細資料。

執行要求回應

AppResponse

下表列出 AppResponse 類型的屬性：

屬性 類型 說明
expectUserResponse Const

設為 false。

值：False
finalResponse FinalResponse

必填。

包含你對購物車結帳的回應。

以下範例顯示 AppResponse 元素：

範例 1

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "checkoutResponse": {
              "proposedOrder": {
                "id": "sample_proposed_order_id_1",
                "otherItems": [
                  {
                    "name": "New customer discount",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5",
                        "nanos": -500000000
                      }
                    },
                    "type": "DISCOUNT"
                  },
                  {
                    "name": "Delivery fee",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    },
                    "type": "DELIVERY"
                  },
                  {
                    "name": "Tax",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 500000000
                      }
                    },
                    "type": "TAX"
                  }
                ],
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Pita Chips",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "2",
                          "nanos": 750000000
                        }
                      },
                      "subLines": [
                        {
                          "note": "Notes for this item."
                        }
                      ],
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                        "options": [
                          {
                            "id": "sample_addon_offer_id_1",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                            "name": "Honey Mustard",
                            "price": {
                              "currencyCode": "USD"
                            },
                            "quantity": 1
                          },
                          {
                            "id": "sample_addon_offer_id_2",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                            "name": "BBQ Sauce",
                            "price": {
                              "currencyCode": "USD",
                              "nanos": 500000000
                            },
                            "quantity": 1
                          }
                        ]
                      }
                    },
                    {
                      "name": "Chicken Shwarma Wrap",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_2",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "8"
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    },
                    {
                      "name": "Greek Salad",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_3",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "9",
                          "nanos": 990000000
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    },
                    {
                      "name": "Prawns Biryani",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_4",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "15",
                          "nanos": 990000000
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "delivery": {
                          "deliveryTimeIso8601": "P90M"
                        }
                      }
                    },
                    "location": {
                      "coordinates": {
                        "latitude": 37.788783,
                        "longitude": -122.41384
                      },
                      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
                      "zipCode": "94043",
                      "city": "Mountain View",
                      "postalAddress": {
                        "regionCode": "US",
                        "postalCode": "94043",
                        "administrativeArea": "CA",
                        "locality": "Mountain View",
                        "addressLines": [
                          "1350 Charleston Road"
                        ]
                      },
                      "notes": "Gate code is #111"
                    }
                  }
                },
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "36",
                    "nanos": 730000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "delivery": {
                          "deliveryTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2017-07-17T12:30:00Z"
                    }
                  ]
                }
              },
              "paymentOptions": {
                "googleProvidedOptions": {
                  "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
                }
              },
              "additionalPaymentOptions": [
                {
                  "actionProvidedOptions": {
                    "paymentType": "ON_FULFILLMENT",
                    "displayName": "Cash on delivery."
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

範例 2

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "orderUpdate": {
              "actionOrderId": "sample_action_order_id",
              "orderState": {
                "state": "CONFIRMED",
                "label": "Provider confirmed"
              },
              "receipt": {
                "userVisibleOrderId": "userVisibleId1234"
              },
              "updateTime": "2017-07-17T12:00:00Z",
              "orderManagementActions": [
                {
                  "type": "CUSTOMER_SERVICE",
                  "button": {
                    "title": "Contact customer service",
                    "openUrlAction": {
                      "url": "mailto:support@example.com"
                    }
                  }
                },
                {
                  "type": "CUSTOMER_SERVICE",
                  "button": {
                    "title": "Call customer service",
                    "openUrlAction": {
                      "url": "tel:+18005554679"
                    }
                  }
                },
                {
                  "type": "EMAIL",
                  "button": {
                    "title": "Email restaurant",
                    "openUrlAction": {
                      "url": "mailto:person@example.com"
                    }
                  }
                },
                {
                  "type": "CALL_RESTAURANT",
                  "button": {
                    "title": "Call restaurant",
                    "openUrlAction": {
                      "url": "tel:+16505554679"
                    }
                  }
                }
              ],
              "infoExtension": {
                "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
                "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
              }
            }
          }
        }
      ]
    }
  }
}

範例 3

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "error": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
              "foodOrderErrors": [
                {
                  "error": "CLOSED",
                  "description": "The restaurant is closed."
                }
              ]
            }
          }
        }
      ]
    }
  }
}

示例 4

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "checkoutResponse": {
              "proposedOrder": {
                "otherItems": [
                  {
                    "name": "Delivery Fees",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    },
                    "type": "DELIVERY"
                  },
                  {
                    "name": "Tax",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 370000000
                      }
                    },
                    "type": "TAX"
                  },
                  {
                    "name": "Promotion",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5",
                        "nanos": 0
                      }
                    },
                    "id": "OWG_ACTIVE_CODE",
                    "type": "DISCOUNT"
                  }
                ],
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Pita Chips",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "2",
                          "nanos": 750000000
                        }
                      },
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "promotions": [
                    {
                      "coupon": "OWG_ACTIVE_CODE"
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    }
                  }
                },
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "14",
                    "nanos": 860000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2018-04-10T01:20:08.471Z"
                    }
                  ]
                }
              },
              "paymentOptions": {
                "googleProvidedOptions": {
                  "tokenizationParameters": {
                    "tokenizationType": "PAYMENT_GATEWAY",
                    "parameters": {
                      "gateway": "stripe",
                      "stripe:publishableKey": "pk_live_stripe_client_key",
                      "stripe:version": "2017-04-06"
                    }
                  },
                  "supportedCardNetworks": [
                    "AMEX",
                    "DISCOVER",
                    "MASTERCARD",
                    "VISA",
                    "JCB"
                  ],
                  "prepaidCardDisallowed": true,
                  "billingAddressRequired": true
                }
              }
            }
          }
        }
      ]
    }
  }
}

CheckoutResponseMessage

CheckoutResponseMessage 是 AppResponse，在 StructuredResponse 中包含 checkoutResponse 或 error。

SubmitOrderResponseMessage

SubmitOrderResponseMessage 是 AppResponse，在 StructuredResponse 中具有 orderUpdate。

FinalResponse

您對購物車結帳或 SubmitOrderRequestMessage 的回應。

下表列出 FinalResponse 類型的屬性：

屬性 類型 說明
richResponse RichResponse

必填。

包含您對 CheckoutRequestMessage 或 SubmitOrderRequestMessage 的回應。

CheckoutResponse

下表列出 CheckoutResponse 類型的屬性：

屬性 類型 說明
proposedOrder ProposedOrder

必填。

建議用於交易的訂單。
paymentOptions PaymentOptions

必填。

使用者選取的預設付款方式。
additionalPaymentOptions List<PaymentOptions>

使用者可使用的其他付款方式。

以下範例顯示 CheckoutResponse 元素：

範例

{
  "proposedOrder": {
    "id": "sample_proposed_order_id_1",
    "otherItems": [
      {
        "name": "New customer discount",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "-5",
            "nanos": -500000000
          }
        },
        "type": "DISCOUNT"
      },
      {
        "name": "Delivery fee",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "3",
            "nanos": 500000000
          }
        },
        "type": "DELIVERY"
      },
      {
        "name": "Tax",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "1",
            "nanos": 500000000
          }
        },
        "type": "TAX"
      }
    ],
    "cart": {
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Falafel Bite"
      },
      "lineItems": [
        {
          "name": "Pita Chips",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        },
        {
          "name": "Chicken Shwarma Wrap",
          "type": "REGULAR",
          "id": "sample_item_offer_id_2",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "8"
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Greek Salad",
          "type": "REGULAR",
          "id": "sample_item_offer_id_3",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "9",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Prawns Biryani",
          "type": "REGULAR",
          "id": "sample_item_offer_id_4",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "15",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          }
        },
        "location": {
          "coordinates": {
            "latitude": 37.788783,
            "longitude": -122.41384
          },
          "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
          "zipCode": "94043",
          "city": "Mountain View",
          "postalAddress": {
            "regionCode": "US",
            "postalCode": "94043",
            "administrativeArea": "CA",
            "locality": "Mountain View",
            "addressLines": [
              "1350 Charleston Road"
            ]
          },
          "notes": "Gate code is #111"
        }
      }
    },
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "36",
        "nanos": 730000000
      }
    },
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P0M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ]
    }
  },
  "paymentOptions": {
    "googleProvidedOptions": {
      "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
    }
  },
  "additionalPaymentOptions": [
    {
      "actionProvidedOptions": {
        "paymentType": "ON_FULFILLMENT",
        "displayName": "Cash on delivery."
      }
    }
  ]
}

項目

包含你對購物車結帳或 SubmitOrderRequestMessage 的回應。

下表列出 Item 類型的屬性：

屬性 類型 說明
structuredResponse StructuredResponse

必填。

RichResponse

包含你對購物車結帳的回應。

下表列出 RichResponse 類型的屬性：

屬性 類型 說明
items List<Item>

必填。

必須有 1 個項目。

StructuredResponse

對於 CheckoutResponseMessage，這可以是下列任一項：CheckoutResponse 表示結帳成功。OR FoodErrorExtension：表示結帳期間發生錯誤。回應可能包含已修正的 ProposedOrder 和 PaymentOptions，或是沒有 PaymentOptions 的錯誤訊息。針對 SubmitOrderResponseMessage，僅適用 orderUpdate。

下表列出 StructuredResponse 類型的屬性：

屬性 類型 說明
必須提供下列其中一個屬性組合。
checkoutResponse 群組 1 CheckoutResponse

已結帳的商品，加上稅金和折扣。
error 群組 2 FoodErrorExtension

購物車商品發生錯誤。視錯誤性質而定，這項屬性可能會包含已修正的 ProposedOrder 和 PaymentOptions，或是只有錯誤訊息，而沒有 PaymentOptions。
orderUpdate 群組 3 OrderUpdate

非同步訂單更新

本節將說明組成一般餐點訂購內建動作互動動作的一般類型。

AsyncOrderUpdateRequestMessage

在提交及確認訂單後，通知使用者變更。舉例來說，您可以通知使用者訂單正在運送中，或是價格有變動。詳情請參閱

下表列出 AsyncOrderUpdateRequestMessage 類型的屬性：

屬性 類型 說明
isInSandbox 布林值

表示這項更新是針對沙箱付款訂單傳送。
customPushMessage CustomPushMessage

必填。

包含要求的 OrderUpdate。

以下範例顯示 AsyncOrderUpdateRequestMessage 元素：

範例

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "IN_TRANSIT",
        "label": "Order is on the way"
      },
      "inTransitInfo": {
        "updatedTime": "2017-07-17T12:00:00Z"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
      }
    }
  }
}

AsyncOrderUpdateResponseMessage

成功傳送 AsyncOrderUpdateRequestMessage 後，Google 會傳回 HTTP 200 狀態和空白內文。如果更新失敗，Google 會回覆訂單更新失敗的原因。

訂單更新類型

按鈕

定義可新增的使用者介面元素，以提供使用者互動。

下表列出 Button 類型的屬性：

屬性 類型 說明
title String

必填。

顯示標籤。請使用句首字母大寫的 30 個半形字元，確保正確顯示。

範例：Contact us
openUrlAction OpenUrlAction

必填。

以下範例顯示 Button 元素：

範例

{
  "title": "Send us feedback",
  "openUrlAction": {
    "url": "mailto:person@example.com"
  }
}

CancellationInfo

下表列出 CancellationInfo 類型的屬性：

屬性 類型 說明
reason String

必填。

當 OrderState.state 為「CANCELLED」時，顯示拒絕原因的文字。

範例：Restaurant closed

以下範例顯示 CancellationInfo 元素：

範例

{
  "reason": "Insufficient inventory"
}

FoodOrderUpdateExtension

這類型會向使用者提供訂單送達或可供取貨的預估時間間隔。只要資訊可用，或自上次傳送後有所變更，就應在 OrderUpdate 中傳送這項擴充資料。

請提供較保守的執行間隔預估值，確保能持續滿足使用者期望。舉例來說，如果系統預估訂單會在今天 13:00 送達，您應傳送的預估間隔應與交通狀況變化一致，例如今天 12:45 到 13:15。

ISO 8601 時間長度或時間戳記的解讀方式是指從 OrderUpdate 的 updateTime (本質上是「現在」) 到 updateTime 加上 duration 的間隔。除非「現在」確實是合理的預期時間，否則請勿使用這個格式。

ISO 8601 間隔的解讀方式是指從間隔開始到結束的間隔。

下表列出 FoodOrderUpdateExtension 類型的屬性：

屬性 類型 說明
@type Const

這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension
estimatedFulfillmentTimeIso8601 String

訂單送達或可供取貨的預估時間。字串必須採用 ISO 8601 格式，且必須對應至一段時間，而非單一固定時間。可接受的慣用規則包括：間隔、時間長度和日期/時間。當資訊可用或發生變更 (例如提早或延遲抵達) 時，您可以透過 SubmitOrderResponseMessage 或 AsyncOrderUpdateRequestMessage 傳送這個欄位。

範例：2017-07-17T13:00:00Z/2017-07-17T13:30:00Z
foodOrderErrors List<FoodOrderError>

說明後續訂單發生的錯誤。建議每個購物車或每項商品只出現一個錯誤。如有 RejectionInfo 未涵蓋的任何錯誤，請使用 FoodOrderUpdateExtension.FoodOrderErrors。

必須至少包含 1 個項目。

以下範例顯示 FoodOrderUpdateExtension 元素：

範例 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
  "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}

範例 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
  "foodOrderErrors": [
    {
      "error": "NO_CAPACITY",
      "description": "Sorry, the restaurant cannot take your order right now."
    }
  ]
}

FulfillmentInfo

下表列出 FulfillmentInfo 類型的屬性：

屬性 類型 說明
必須提供下列其中一個屬性組合。
deliveryTime 群組 1 ISO 時間戳記

在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601
pickupTime 群組 2 ISO 時間戳記

在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601

以下範例顯示 FulfillmentInfo 元素：

範例 1

{
  "deliveryTime": "2017-05-10T02:36:38.803Z"
}

範例 2

{
  "pickupTime": "2019-12-26T07:24:27.803Z"
}

InTransitInfo

下表列出 InTransitInfo 類型的屬性：

屬性 類型 說明
updatedTime ISO 時間戳記

在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601

以下範例顯示 InTransitInfo 元素：

範例

{
  "updatedTime": "2017-05-10T02:36:38.803Z"
}

LineItemUpdate

下表列出 LineItemUpdate 類型的屬性：

屬性 類型 說明
orderState OrderState
price Price
reason String

變更原因。如要變更價格，請務必填寫。

以下範例顯示 LineItemUpdate 元素：

範例

{
  "orderState": {
    "state": "CONFIRMED",
    "label": "Provider confirmed"
  },
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "5",
      "nanos": 500000000
    }
  },
  "reason": "Menu updated prices."
}

OpenUrlAction

下表列出 OpenUrlAction 類型的屬性：

屬性 類型 說明
url String

必填。

點按或輕觸按鈕時觸發的動作。適用的前置字元清單取決於 orderManagementActionType。「EMAIL」：前置字元必須是「mailto」。「CALL」：前置字元必須是「tel」。「CUSTOMER_SERVICE」：前置字元必須是「mailto」、「tel」、「http」或「https」。

範例：https://www.google.com

OrderManagementAction

訂單管理功能可讓使用者取得訂單後支援服務，並應在提交訂單 AppResponse 和後續每個 AsyncOrderUpdateRequestMessage 中，透過每個 OrderUpdate 傳送。針對特定訂單傳送的訂單管理動作可能因狀態而異。

舉例來說，在「CREATED」狀態下，CUSTOMER_SERVICE 可能會參照客戶服務電話。接著，在「CONFIRMED」狀態下，如果餐廳電話是客戶聯絡的最佳管道，CUSTOMER_SERVICE 可以變更為餐廳的電話號碼。同樣地，當訂單處於「已完成」狀態時，CUSTOMER_SERVICE 可以參照支援電子郵件地址。

下表列出 OrderManagementAction 類型的屬性：

屬性 類型 說明
type OrderManagementActionType

必填。
button Button

必填。

以下範例顯示 OrderManagementAction 元素：

範例 1

{
  "type": "CUSTOMER_SERVICE",
  "button": {
    "title": "Contact customer service",
    "openUrlAction": {
      "url": "mailto:support@example.com"
    }
  }
}

範例 2

{
  "type": "EMAIL",
  "button": {
    "title": "Email restaurant",
    "openUrlAction": {
      "url": "mailto:person@example.com"
    }
  }
}

OrderManagementActionType

定義與 OrderManagementAction 相關的類型。

OrderManagementActionType 類型可用的值如下：

  • CUSTOMER_SERVICE：在訂單確認頁面上顯示的客戶服務電子郵件和/或聯絡電話號碼。這是必要項目。openUrlAction.url 前置字元必須是「mailto」、「tel」、「http」或「https」。
  • EMAIL：僅適用於訂單詳細資料頁面的電子郵件動作。openUrlAction.url 前置字串必須為「mailto」。
  • CALL_DRIVER：僅適用於訂單詳細資料頁面的呼叫動作。openUrlAction.url 前置字串必須為「tel」。
  • CALL_RESTAURANT：僅適用於訂單詳細資料頁面的呼叫動作。openUrlAction.url 前置字串必須為「tel」。

OrderState

訂單目前的狀態。OrderState 的每個 state 值也對應至 myaccount.google.com 上的購買狀態。

下表列出 OrderState 類型的屬性：

屬性 類型 說明
state OrderStateEnum

必填。
label String

必填。

狀態的使用者可見顯示字串。英文標題應採用句首字母大寫格式。

範例：Your order has been received

以下範例顯示 OrderState 元素：

範例

{
  "state": "CONFIRMED",
  "label": "Provider confirmed"
}

OrderStateEnum

定義與 OrderState 相關的類型。

OrderStateEnum 類型可用的值如下：

  • CREATED：由整合服務供應商建立的訂單，目前正在等待供應商確認。對應於「已下單」的購買狀態。
  • CONFIRMED：訂單已由供應商確認並生效。對應至「已接受」的購買狀態。
  • REJECTED：訂單遭到整合業者或供應商拒絕。對應於「Declined」(拒絕) 購買狀態。
  • CANCELLED：使用者取消訂單。對應於「已取消」的購買狀態。
  • IN_PREPARATION：餐點正在準備中。對應於「狀態不明」的購買狀態。
  • READY_FOR_PICKUP：餐點已備妥，可供取件。對應於「已準備取貨」的購買狀態。
  • IN_TRANSIT：訂單正在送達。對應於「進行中」的購買狀態。
  • FULFILLED：使用者收到訂購的商品。對應至「已取貨」的購買狀態。

收據

在提交訂單 AppResponse 中傳送此類型，其中 OrderState 為「CONFIRMED」、「FULFILLED」或「IN_TRANSIT」。在 userVisibleOrderId 可用時傳送收據。您不需要在後續更新中持續傳送收據。

下表列出 Receipt 類型的屬性：

屬性 類型 說明
userVisibleOrderId String

必填。

如果訂單狀態為「CONFIRMED」、「IN_TRANSIT」或「FULFILLED」，則為必填。這個欄位是這筆訂單的單一使用者 ID (通常是餐廳的訂單 ID)，會顯示在整合商的收據和 Google 訂單資訊卡中。使用者必須能夠使用這個 ID 向供應商和整合服務供應商提供訂單，以便取得客戶服務。您只需在任何 OrderUpdate 中提供一次這個 ID。在提供該值之前，actionOrderId 就是 userVisibleOrderId。舉例來說，您可能必須等到餐廳確認訂單後，才能取得 userVisibleOrderId。確認後，您必須傳送 AsyncOrderUpdateRequestMessage，其中包含 OrderUpdate 和 Receipt。

以下範例顯示 Receipt 元素：

範例

{
  "userVisibleOrderId": "userVisibleId1234"
}

RejectionInfo

下表列出 RejectionInfo 類型的屬性：

屬性 類型 說明
type RejectionType

必填。
reason String

拒絕原因，用於內部記錄。使用者不會看到這個欄位。

以下範例顯示 RejectionInfo 元素：

範例

{
  "type": "PAYMENT_DECLINED",
  "reason": "There is an issue with payment processing."
}

RejectionType

RejectionType 類型可用的值如下：

  • INELIGIBLE：使用者因政策或風險相關問題而無法使用服務。
  • PAYMENT_DECLINED：付款處理作業發生問題。
  • UNAVAILABLE_SLOT：訂單無法在 DeliveryInfo 或 PickupInfo 指定的預訂時間內完成。
  • PROMO_NOT_APPLICABLE：促銷活動發生問題。
  • UNKNOWN：任何其他原因。

付款相關類型

本節說明用於處理餐點訂購的付款相關類型。

ActionProvidedPaymentOptions

行動提供的付款方式相關規定。

下表列出 ActionProvidedPaymentOptions 類型的屬性：

屬性 類型 說明
paymentType PaymentType

必填。
displayName String

必填。

收據上顯示的付款工具名稱。

範例：Taco Points Total
onFulfillmentPaymentData OnFulfillmentPaymentData

付款類型為「ON_FULFILLMENT」的其他資料。舉例來說，您可以使用這個欄位指定是否支援現金或卡片付款。

以下範例顯示 ActionProvidedPaymentOptions 元素：

範例

{
  "paymentType": "ON_FULFILLMENT",
  "displayName": "Pay when you get your food.",
  "onFulfillmentPaymentData": {
    "supportedPaymentOptions": [
      "Cash",
      "Card"
    ]
  }
}

AllowedAuthMethods

AllowedAuthMethods 類型可用的值如下：

  • PAN_ONLY：這種驗證方式與使用者 Google 帳戶中儲存的付款卡相關聯。傳回的付款資料包括個人帳號 (PAN) 和到期月份及年份。

AllowedCardNetworks

AllowedCardNetworks 類型可用的值如下：

  • AMEX
  • DISCOVER
  • INTERAC
  • JCB
  • MASTERCARD
  • VISA

BillingAddressParameters

這個物件可讓您為要求的帳單地址設定要傳回的額外欄位。

下表列出 BillingAddressParameters 類型的屬性：

屬性 類型 說明
format String

完成交易所需的帳單地址格式。MIN：姓名、國家/地區代碼和郵遞區號。FULL：姓名、街道地址、縣市、地區、國家/地區代碼與郵遞區號。

以下範例顯示 BillingAddressParameters 元素：

範例 1

{
  "format": "MIN"
}

範例 2

{
  "format": "FULL"
}

CardParameters

使用這個物件設定網站對 Google Pay API 的支援。

下表列出 CardParameters 類型的屬性：

屬性 類型 說明
allowedAuthMethods List<Const>

必填。

驗證卡片交易時支援的欄位。

必須至少包含 1 個項目。
allowedCardNetworks List<AllowedCardNetworks>

必填。

Google Pay API 也支援您所支援的一或多個發卡機構。

必須至少包含 1 個項目。
billingAddressRequired 布林值

如果您需要帳單地址，請設為 true。只有在需要帳單地址來處理交易時，才要求提供。要求額外的資料可能會增加結帳程序的不便，並且導致轉換率下降。
billingAddressParameters BillingAddressParameters

將 billingAddressRequired 設為 true 時傳回的預期欄位。
cvcRequired 布林值

如果使用 TimesofMoney，請將這個值設為 true；如果使用其他付款處理服務，請設為 false。

以下範例顯示 CardParameters 元素：

範例 1

{
  "allowedAuthMethods": [
    "PAN_ONLY"
  ],
  "allowedCardNetworks": [
    "AMEX",
    "DISCOVER"
  ],
  "billingAddressRequired": false,
  "cvcRequired": false
}

範例 2

{
  "allowedAuthMethods": [
    "PAN_ONLY"
  ],
  "allowedCardNetworks": [
    "AMEX",
    "DISCOVER"
  ],
  "billingAddressRequired": true,
  "billingAddressParameters": {
    "format": "MIN"
  },
  "cvcRequired": false
}

GoogleProvidedPaymentInstrument

下表列出 GoogleProvidedPaymentInstrument 類型的屬性：

屬性 類型 說明
instrumentToken String

必填。

採用 Base 64 編碼的字串，其中包含付款權杖，可根據先前指定的 GoogleProvidedPaymentOptions，透過合作的 Google Pay 處理工具向使用者收費。
billingAddress PostalAddress

付款的帳單地址。

以下範例顯示 GoogleProvidedPaymentInstrument 元素：

範例

{
  "instrumentToken": "abcd",
  "billingAddress": {
    "regionCode": "US",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1350 Charleston Road"
    ]
  }
}

GoogleProvidedPaymentOptions

Google 提供的付款方式相關規定。

下表列出 GoogleProvidedPaymentOptions 類型的屬性：

屬性 類型 說明
facilitationSpecification String

PaymentDataRequest JSON 做為字串。使用這個物件設定網站對 Google Pay API 的支援。
supportedCardNetworks List<SupportedCardNetworks>

請改用 facilitationSpecification。代理人支援的發卡機構類型。

這個欄位已淘汰。
prepaidCardDisallowed 布林值

請改用 facilitationSpecification。是否允許使用預付卡付款。

這個欄位已淘汰。
billingAddressRequired 布林值

請改用 facilitationSpecification。是否需要帳單地址。

這個欄位已淘汰。
tokenizationParameters TokenizationParameters

這個欄位已淘汰。

以下範例顯示 GoogleProvidedPaymentOptions 元素：

範例 1

{
  "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
}

範例 2

{
  "tokenizationParameters": {
    "tokenizationType": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "braintree",
      "braintree:apiVersion": "v1",
      "braintree:sdkVersion": "1.4.0",
      "braintree:merchantId": "a1b2c3d4e5",
      "braintree:clientKey": "production_braintree_client_key",
      "braintree:authorizationFingerprint": "same_as_client_key"
    }
  },
  "supportedCardNetworks": [
    "AMEX",
    "DISCOVER",
    "MASTERCARD",
    "JCB",
    "VISA"
  ],
  "prepaidCardDisallowed": true
}

範例 3

{
  "tokenizationParameters": {
    "tokenizationType": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "stripe",
      "stripe:publishableKey": "pk_live_stripe_client_key",
      "stripe:version": "2017-04-06"
    }
  },
  "supportedCardNetworks": [
    "AMEX",
    "DISCOVER",
    "MASTERCARD",
    "VISA",
    "JCB"
  ],
  "prepaidCardDisallowed": true,
  "billingAddressRequired": true
}

MerchantInfo

使用這個物件設定網站對 Google Pay API 的支援。

下表列出 MerchantInfo 類型的屬性：

屬性 類型 說明
merchantId String

Google Pay 核發給你的 Google 商家識別碼。
merchantName String

必填。

採用 UTF-8 編碼的商家名稱，商家名稱會顯示在付款畫面中。

OnFulfillmentPaymentData

使用這個物件，針對 PaymentType 傳送「ON_FULFILLMENT」的其他資料。

下表列出 OnFulfillmentPaymentData 類型的屬性：

屬性 類型 說明
supportedPaymentOptions List<PaymentOptionsEnums>

使用者在訂單履行時可用的付款方式清單。

以下範例顯示 OnFulfillmentPaymentData 元素：

範例

{
  "supportedPaymentOptions": [
    "Cash",
    "Card"
  ]
}

參數

定義與 TokenizationParameters 相關的類型。

下表列出 Parameters 類型的屬性：

屬性 類型 說明
gateway String

必填。

範例：braintree
gatewayMerchantId String
[additionalKey: string] String 其他鍵/值組合

以下範例顯示 Parameters 元素：

範例 1

{
  "gatewayMerchantId": "90412491",
  "gateway": "olo"
}

範例 2

{
  "gateway": "braintree",
  "braintree:apiVersion": "v1",
  "braintree:sdkVersion": "1.4.0",
  "braintree:merchantId": "YOUR_MERCHANT_ID",
  "braintree:clientKey": "YOUR_BRAINTREE_SANDVOX_OR_PRODUCTION_KEY"
}

PaymentDataRequest

使用這個物件設定網站對 Google Pay API 的支援。

下表列出 PaymentDataRequest 類型的屬性：

屬性 類型 說明
apiVersion Const

必填。

API 主要版本。

值：2
apiVersionMinor Const

必填。

API 次要版本。

值：0
merchantInfo MerchantInfo

必填。

(Google Pay 商家 ID) 要求付款資料的商家相關資訊。
allowedPaymentMethods List<PaymentMethod>

必填。

指定支援 Google Pay API 所支援的一或多種付款方式。
transactionInfo TransactionInfo

必填。

根據使用者是否同意交易，提供有關交易授權的詳細資料，這個欄位包含總價和價格狀態。

以下範例顯示 PaymentDataRequest 元素：

範例

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "merchantInfo": {
    "merchantId": "10391231",
    "merchantName": "Burrito Town"
  },
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": [
          "PAN_ONLY"
        ],
        "allowedCardNetworks": [
          "VISA",
          "AMEX",
          "MASTERCARD"
        ],
        "billingAddressRequired": true,
        "billingAddressParameters": {
          "format": "FULL"
        },
        "cvcRequired": false
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "stripe",
          "stripe:version": "2019-05-16",
          "stripe:publishableKey": "pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA"
        }
      }
    }
  ],
  "transactionInfo": {
    "currencyCode": "INR",
    "totalPriceStatus": "ESTIMATED",
    "totalPrice": "185.00"
  }
}

PaymentInfo

訂單的付款相關資訊。

下表列出 PaymentInfo 類型的屬性：

屬性 類型 說明
displayName String

必填。

收據上顯示的付款工具名稱，供使用者查看。
paymentType PaymentType

必填。
googleProvidedPaymentInstrument GoogleProvidedPaymentInstrument

動作可使用的符記。只有在 CheckoutResponseMessage 中將 GoogleProvidedPaymentOptions 指定為付款選項時，才需要指定這項屬性。

以下範例顯示 PaymentInfo 元素：

範例 1

{
  "displayName": "Visa\u2006****\u20061111",
  "googleProvidedPaymentInstrument": {
    "instrumentToken": "abcd"
  },
  "paymentType": "PAYMENT_CARD"
}

範例 2

{
  "displayName": "Visa\u2006****\u20061111",
  "googleProvidedPaymentInstrument": {
    "instrumentToken": "abcd",
    "billingAddress": {
      "regionCode": "US",
      "postalCode": "94043",
      "administrativeArea": "CA",
      "locality": "Mountain View",
      "addressLines": [
        "123 Random Street",
        "Unit ABC"
      ],
      "recipients": [
        "sample_receipient"
      ]
    }
  },
  "paymentType": "PAYMENT_CARD"
}

PaymentMethod

使用這個物件設定網站對 Google Pay API 的支援。

下表列出 PaymentMethod 類型的屬性：

屬性 類型 說明
type Const

必填。

支援的付款方式簡短 ID。目前僅支援 CARD。

值：CARD
parameters CardParameters

必填。

設定所提供的付款方式類型時所需的參數。
tokenizationSpecification TokenizationSpecification

必填。

設定要接收付款資訊的帳戶或解密供應商。如為 CARD 付款方式，則此為必要屬性。

以下範例顯示 PaymentMethod 元素：

範例

{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": [
      "PAN_ONLY"
    ],
    "allowedCardNetworks": [
      "VISA",
      "AMEX",
      "MASTERCARD"
    ],
    "billingAddressRequired": false
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gatewayMerchantId": "90412491",
      "gateway": "olo"
    }
  }
}

PaymentOptions

下表列出 PaymentOptions 類型的屬性：

屬性 類型 說明
必須提供下列其中一個屬性組合。
googleProvidedOptions 群組 1 GoogleProvidedPaymentOptions

與 actionProvidedOptions 互斥。使用 Google Pay 進行線上付款時，請使用這組資訊。
actionProvidedOptions 群組 2 ActionProvidedPaymentOptions

與 googleProvidedOptions 互斥。適用於「貨到付款」或「出貨付款」。

以下範例顯示 PaymentOptions 元素：

範例 1

{
  "googleProvidedOptions": {
    "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
  }
}

範例 2

{
  "googleProvidedOptions": {
    "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\":true,   \"billingAddressParameters\": {  \"format\":\"MIN\"  }    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
  }
}

範例 3

{
  "actionProvidedOptions": {
    "paymentType": "ON_FULFILLMENT",
    "displayName": "Pay when you get your food.",
    "onFulfillmentPaymentData": {
      "supportedPaymentOptions": [
        "Cash",
        "Card"
      ]
    }
  }
}

PaymentOptionsEnums

PaymentOptionsEnums 類型可用的值如下：

  • Cash
  • Card
  • UPI
  • Paytm

PaymentType

PaymentType 類型可用的值如下：

  • PAYMENT_CARD：適用於 GoogleProvidedPaymentOptions。
  • ON_FULFILLMENT：適用於 ActionProvidedPaymentOptions。

SupportedCardNetworks

定義與 GoogleProvidedPaymentOptions 相關的類型。

SupportedCardNetworks 類型可用的值如下：

  • UNSPECIFIED_CARD_NETWORK
  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA

TokenizationParameters

定義與 GoogleProvidedPaymentOptions 相關的類型。

下表列出 TokenizationParameters 類型的屬性：

屬性 類型 說明
tokenizationType Enum [ "UNSPECIFIED_TOKENIZATION_TYPE", "PAYMENT_GATEWAY" ]

必填。

請改用 facilitationSpecification。可接受的符記類型。
parameters Parameters

請改用 facilitationSpecification。

TokenizationSpecification

這個物件可讓您設定要接收可扣款付款資訊的帳戶。

下表列出 TokenizationSpecification 類型的屬性：

屬性 類型 說明
type Const

必填。
parameters Parameters

必填。

以下範例顯示 TokenizationSpecification 元素：

範例 1

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gatewayMerchantId": "1247192",
    "gateway": "cybersource"
  }
}

範例 2

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "stripe",
    "stripe:version": "2018-10-31",
    "stripe:publishableKey": "12378127"
  }
}

TransactionInfo

這個物件說明交易內容，藉此判斷付款人能否付款。這個物件可用來顯示付款授權對話方塊。

下表列出 TransactionInfo 類型的屬性：

屬性 類型 說明
currencyCode String

必填。

ISO 4217 以英文字母構成的貨幣代碼。
transactionId String

用於識別交易嘗試的專屬 ID。商家可以使用現有 ID，或為 Google Pay 交易嘗試產生特定 ID。將回呼傳送至 Google Transaction Events API 時，這是必填欄位。
totalPriceStatus Const

必填。

預設值為「ESTIMATED」。總價可能會根據回應詳情調整，例如根據帳單地址收取的銷售稅。

值：ESTIMATED
totalPrice String

必填。

交易總金額，可選用位數至小數點後兩位。這個欄位的值應與 cart.totalPrice 相同。

以下範例顯示 TransactionInfo 元素：

範例

{
  "totalPriceStatus": "ESTIMATED",
  "totalPrice": "12.34",
  "currencyCode": "USD"
}