出貨動作結構定義

這個頁面說明使用「訂單透過 Google 內建動作 API」時，出貨網路服務 (透過 Google API 訂購) 的酬載。如需機器可解讀的資訊版本，您可以下載 JSON 結構定義。

基礎類型

購物車

包含訂單詳細資料，以及要求是取貨或外送。購物車也包含運送詳細資料、重力和交貨地址。 Checkout AppRequest 中定義了 Cart 物件。 Checkout AppResponse 包含購物車副本

下表列出 Cart 類型的屬性：

屬性 類型 說明
@type 缺點

這個物件的類型。如果父項「購物車」物件屬於 ProposedOrder ，則請省略這個欄位。

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

購物車的選用 ID。
merchant Merchant

與這個購物車相關聯的商家。
lineItems 清單<LineItem>

這是必填欄位。

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

不可超過 1 個項目。
promotions 清單<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"
}

自訂推送訊息

包含要求的 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 類型的屬性：

屬性 類型 說明
deliveryTimeIso8601 String

預計送達時間，採 ISO 8601 時間戳記格式："{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z)。舉例來說，PT90M 代表時間長度為 90 分鐘。預設值「PT0M」表示偏好的運送時間越快越好。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Merged_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：委刊項、FulfillmentOption 或 Promotion 含有無效的資料。
  • NOT_FOUND：找不到明細項目、FulfillmentOption 或 Promotion。
  • PRICE_CHANGED：商品價格已變更。

費用金額範圍

下表列出 FeeAmountRange 類型的屬性：

屬性 類型 說明
minFeeAmount Money

費用金額下限。
maxFeeAmount Money

收費金額上限。

費用百分比範圍

下表列出 FeePercentRange 類型的屬性：

屬性 類型 說明
minFeePercent Number

費用百分比下限。
maxFeePercent Number

費用上限上限。

食物購物車擴充功能

含有使用者的詳細資料，例如出貨偏好設定。

下表列出 FoodCartExtension 類型的屬性：

屬性 類型 說明
@type 缺點

這項額外資訊的類型。這個欄位一律會設為「quot;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 缺點

這是必填欄位。

這項額外資訊的類型。

值：type.googleapis.com/google.actions.v2.orders.FoodErrorExtension
foodOrderErrors 清單<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 清單<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 缺點

這是必填欄位。

這項額外資訊的類型。這個欄位一律會設為「quot;type.googleapis.com/google.actions.v2.orders.FoodItemExtension"」。

值：type.googleapis.com/google.actions.v2.orders.FoodItemExtension
options 清單<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 時，您可以使用這個欄位來區分購物車包含超過相同 itemId 的項目。

範例：39231093
offerId String

商品的優惠 ID。

範例：912835081
name String

選項名稱。

範例：Honey Mustard
price Money
note String

與選項相關的附註。
quantity Number

如果選項是項目，則代表項目數量。

範例：3
subOptions 清單<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 缺點

這項額外資訊的類型。這個欄位一律會設為「quot;type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"」。

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

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

使用者要求啟用您的行銷管道。根據預設，如未徵得使用者同意，您不得傳送行銷內容。如果 OptinForReach 的值為 true，您可以訂閱使用者。如果 OptinFor Remarketing 為否或不存在，您就必須保留系統中的訂閱狀態。使用者無法透過 Google 停用此功能，只能透過行銷管道提供的取消訂閱功能。此標記只出現在提交訂單要求訊息中。

以下範例為 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 物件：
  • 在 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 像素。為求最佳效果，請使用至少 216x216 像素的圖片。圖片大小必須小於 6 MB 或 6,400 萬像素。

LineItem

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

下表列出 LineItem 類型的屬性：

屬性 類型 說明
id String

當 type = "REGULAR" 時為必要欄位。

如果購物車中的明細項目 (ProposedOrder.cart.lineItems[0].id) 是 Google 在建立訂單時產生的專屬 ID。如果是 ProposedOrder (ProposedOrder.otherItems[0].id) 中的明細項目，用於新增運費和稅金等項目，則 ID 的值是由供應商定義。舉例來說，在購物車中有兩個相同商品，各自帶有不同的準備說明 (例如有兩排中不同的配料)。在這種情況下，兩個商品的基本產品 ID 相同。當您傳送訂單更新要求以表示某個商品遭拒時，請使用這個 ID 消歧。換句話說，如果其中一個披薩因缺少特定配料而遭到拒絕，ID 會協助 Google 在您參照的訂單中決定哪個商品。其他「商品」除外，此為必要欄位。
name String

這是必填欄位。

委刊項的名稱。這是使用者可查看的字串，請盡可能使用句首字母大寫 (例如「運費」、「服務費」和「稅金」)。這個欄位會縮短，最多 100 個半形字元。
type LineItemType

這是必填欄位。
quantity 整數

當 type = "REGULAR" 時為必要欄位。

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

商品的說明。
price Price

這是必填欄位。

商品價格。這個值反映了這個委刊項所有商品或服務的總價 (也就是加上所有外掛程式的費用乘以數量)。舉例來說，如果價值 $10 美元的商品數量為 3，則價格為 $30 美元。以基本價格為 $5 美元與 $1 美元的外掛程式為例，價格為 $6 美元。以兩張基本價格為 $5 美元的兩項披薩 (數量 = 2) 而言，每件披薩的附加價為 $1 美元，即 $12 美元。每個委刊項都應該有價格，即使價格是「0」也一樣。如果類型為 DISCOUNT，請將值指定為負值 (例如「-2」)。
subLines 清單<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 類型包含下列值：

  • REGULAR：商品委刊項。適用於 Cart.lineItems。
  • TAX：稅金項目。適用於 ProposedOrder.otherItems。
  • DISCOUNT：折扣委刊項。請注意，價格必須為負值。適用於 ProposedOrder.otherItems。
  • GRATUITY：完整性委刊項。通常會為使用者選取的提示保留 FillOrderRequestMessage。適用於 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。如果有指定，則會與「餐廳」動態饋給中的 Korea.@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

這是必填欄位。

採用 3 個英文字母組成的貨幣代碼，採 ISO 4217 格式。

範例：USD
units String

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

範例：36
nanos 整數

金額的奈米 (10^-9) 單位數量。這個值必須介於 -999,999,999 到 +999,999,999 (含) 之間。請使用下列規則：如果單位為正數，nanos 必須為正值或零。如果單位為零，nanos 可以是正值、零或負值。如果單位為負數，nanos 必須為負值或零。例如，$-1.75 美元代表單位 = -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"
  }
}

訂單更新

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

下表列出 OrderUpdate 類型的屬性：

屬性 類型 說明
actionOrderId String

這是必填欄位。

整合商系統中的訂單專屬 ID，用來識別傳送更新的順序。如果在 OrderUpdate 中並未為「CREATED」建立訂單，則如果收據.user_visible_order_id 未出現至少一次，此 ID 將會是 Google 訂單資訊卡中顯示的使用者可見 ID。
orderState OrderState

這是必填欄位。

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

這是必填欄位。

訂單更新的時間。
orderManagementActions 清單<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 類型的屬性：

屬性 類型 說明
pickupTimeIso8601 String

預計取貨時間，採 ISO 8601 時間戳記格式："{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z)。舉例來說，PT90M 代表時間長度為 90 分鐘。預設值「PT0M」表示偏好的取貨時間越快越好。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Merged_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 清單<String>

一或多條地址，可用來指定街道地址。請勿修改這個欄位，因為其中可能包含不明的區域。

範例：[ "1350 Charleston Road" ]
recipients 清單<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 類型的屬性：

屬性 類型 說明
id String

提案訂單的選用 ID。
cart Cart

這是必填欄位。

使用者的項目。
otherItems 清單<LineItem>

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

不得超過 10 個項目。
image Image

與建議訂單相關聯的圖片。
totalPrice Price

這是必填欄位。

提案訂單的總價。
extension FoodOrderExtension

這是必填欄位。

定義餐點訂單的出貨資訊。
disclaimers 清單<Disclaimer>

對應在下單前，使用者介面中顯示的免責事項訊息。

以下範例為 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 類型的屬性：

屬性 類型 說明
note String

這是必填欄位。

時間戳記

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

交易決策價值

包含 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 清單<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 是包含 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&quot；如果是提交訂單要求訊息，則設為「"actions.intent.TRANSACTION_DECISION"」。
arguments 清單<Argument>

這是必填欄位。

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

只能有 1 個項目。

引數

含有使用者想要查看的食品詳細資訊。結帳時只能使用擴充功能。針對提交訂單，則僅適用於 transactionDecisionValue

下表列出 Argument 類型的屬性：

屬性 類型 說明
必須選取下列其中一組屬性。
extension 群組 1 Cart

提供使用者要結帳的餐點詳細資料。
transactionDecisionValue 第 2 組 TransactionDecisionValue

包含要提交的訂單及付款詳情。

完成回覆

AppResponse

下表列出 AppResponse 類型的屬性：

屬性 類型 說明
expectUserResponse 缺點

設為 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
                }
              }
            }
          }
        }
      ]
    }
  }
}

CheckoutResponse 訊息

CheckoutResponseMessage 是 StructuredResponse 中具有 checkoutResponse 或 error 的 AppResponse。

提交訂單回覆訊息

SubmitOrderResponseMessage 是 AppResponse，其 StructuredResponse 中具有 orderUpdate。

FinalResponse

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

下表列出 FinalResponse 類型的屬性：

屬性 類型 說明
richResponse RichResponse

這是必填欄位。

包含您的 CheckoutRequestMessage 或 SubmitOrderRequestMessage 回應。

結帳回應

下表列出 CheckoutResponse 類型的屬性：

屬性 類型 說明
proposedOrder ProposedOrder

這是必填欄位。

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

這是必填欄位。

為使用者選取的預設付款方式。
additionalPaymentOptions 清單<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 類型的屬性：

屬性 類型 說明
items 清單<Item>

這是必填欄位。

只能有 1 個項目。

結構化回應

針對 CheckoutResponseMessage，可能為下列其中一種狀態： CheckoutResponse 表示成功結帳。或 FoodErrorExtension：表示結帳失敗。回應中可包括更正的 ProposedOrder 和 PaymentOptions，或是包含沒有 PaymentOptions 的錯誤訊息。如為 OrderOrderResponseMessage，則只有 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

定義可以加入以提供使用者互動的使用者介面元素。

下表列出 Button 類型的屬性：

屬性 類型 說明
title String

這是必填欄位。

顯示標籤。請務必使用 30 個字元的句子，確保目錄能正確顯示。

範例：Contact us
openUrlAction OpenUrlAction

這是必填欄位。

以下範例為 Button 元素：

範例

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

取消資訊

下表列出 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 缺點

這項額外資訊的類型。這個欄位一律會設為「quot;type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension"」。

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

訂單商品預計送達或可供取貨的時間。字串必須採用 ISO 8601 格式，且必須對應至間隔，而不是單一固定時間。可接受的慣例如下：間隔、時間長度和日期/時間。當資訊有異動或發生異動時 (例如提前抵達或延遲送達)，這個欄位可用於提交 OrderOrderResponseMessage 或 AsyncOrderUpdateRequestMessage。

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

說明排序後發生的錯誤。建議每個購物車或一項商品顯示一項錯誤。針對 RejectedionInfo 未提及的錯誤，使用 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 類型的屬性：

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

在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601

以下範例為 InTransitInfo 元素：

範例

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

委刊項更新

下表列出 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"：前置字元必須是「quot;mailto"」。"CALL"：前置字元必須是「tel」。"CUSTOMER_SERVICE"：前置字元必須是「quot;mailto"」、「quot;tel"」、「quot;http"」或「quot;https"」。

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

訂單管理動作

訂單管理可讓使用者獲得訂購後支援，而且必須在提交訂單 AppResponse 中的每個 OrderUpdate 和後續幾個 AsyncOrderUpdateRequestMessage 中傳送，視訂單狀態而定，特定訂單傳送的訂單管理動作可能會有所不同。

舉例來說，在「CREATED」狀態中，CUSTOMER_SERVICE 可能會參照您的客戶服務電話。接著，在「確認」狀態中，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"
    }
  }
}

訂單管理動作類型

定義與 OrderManagementAction 相關的類型。

OrderManagementActionType 類型包含下列值：

  • CUSTOMER_SERVICE：顯示在訂單確認頁面上的客戶服務電子郵件和/或聯絡電話。必填。openUrlAction.url 前置字元必須是「quot;mailto"」、「quot;tel"」、「quot;http"」或「quot;https"」。
  • EMAIL：僅限訂單詳細資料頁面上的電子郵件動作。openUrlAction.url 前置字元必須為 "mailto"
  • CALL_DRIVER：僅限訂單詳細資料頁面上的行動號召。openUrlAction.url 前置字元必須是「quot;tel"」。
  • CALL_RESTAURANT：僅限訂單詳細資料頁面上的行動號召。openUrlAction.url 前置字元必須是「quot;tel"」。

訂單狀態

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

下表列出 OrderState 類型的屬性：

屬性 類型 說明
state OrderStateEnum

這是必填欄位。
label String

這是必填欄位。

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

範例：Your order has been received

以下範例為 OrderState 元素：

範例

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

訂單狀態

定義與 OrderState 相關的類型。

OrderStateEnum 類型包含下列值：

  • CREATED：整合服務供應商建立的訂單，正在等待供應商確認。對應「已訂購」購買狀態。
  • CONFIRMED：供應商已確認並處於有效狀態的訂單。對應「已接受」的購買狀態。
  • REJECTED：整合服務供應商或供應商拒絕的訂單。對應「已拒絕」的購買狀態。
  • CANCELLED：使用者取消訂單。對應「已取消」的購買狀態。
  • IN_PREPARATION：正在準備食物。對應「狀態不明」購買狀態。
  • READY_FOR_PICKUP：餐點已可領取。對應「可取貨」購買狀態。
  • IN_TRANSIT：正在傳送訂單。對應「處理中」的購買狀態。
  • FULFILLED：使用者收到訂購的商品。對應「已取貨」購買狀態。

收據

按照提交順序 AppResponse 傳送這個類型，其中 OrderState 為「CONFIRMED」、「CONULRMILLED」或「IN_TRANSIT」。userVisibleOrderId 可供使用時傳送收據。您不需要在後續更新中持續傳送收據。

下表列出 Receipt 類型的屬性：

屬性 類型 說明
userVisibleOrderId String

這是必填欄位。

當前訂單為「CONFIRMED」、「IN_TRANSIT」或「FULFILLED」時為必填。這個欄位是這筆訂單的單一使用者 ID (通常是餐廳的訂單 ID，通常會顯示在整合商的收據和 Google 訂單資訊卡)。使用者必須能使用這個 ID，透過供應商和整合商參照他們訂購的客戶服務訂單。在任何任一 OrderUpdate 中，你只需要提供這組 ID 一次。在提供之前，actionOrderId 是 userVisibleOrderId。舉例來說，在餐廳確認訂單之前，您可能無法使用 userVisibleOrderId。確認後，您必須傳送含有 OrderUpdate 和收據的 AsyncOrderUpdateRequestMessage。

以下範例為 Receipt 元素：

範例

{
  "userVisibleOrderId": "userVisibleId1234"
}

拒絕資訊

下表列出 RejectionInfo 類型的屬性：

屬性 類型 說明
type RejectionType

這是必填欄位。
reason String

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

以下範例為 RejectionInfo 元素：

範例

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

拒絕類型

RejectionType 類型包含下列值：

  • INELIGIBLE：使用者違反政策或風險相關疑慮，因此不符合資格。
  • PAYMENT_DECLINED：處理付款時發生問題。
  • UNAVAILABLE_SLOT：訂單無法在 DeliveryInfo 或 PickupInfo 指定的訂單提前完成。
  • PROMO_NOT_APPLICABLE：促銷活動發生問題。
  • UNKNOWN：任何其他原因。

付款相關類型

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

動作提供付款方式

使用動作提供的付款方式的相關規定。

下表列出 ActionProvidedPaymentOptions 類型的屬性：

屬性 類型 說明
paymentType PaymentType

這是必填欄位。
displayName String

這是必填欄位。

收據上列出的付款方式名稱。

範例：Taco Points Total
onFulfillmentPaymentData OnFulfillmentPaymentData

payType 和「ON_FULFILLMENT」的額外資料。舉例來說，您可以使用這個欄位來指定在付款時是否支援現金或卡片。

以下範例為 ActionProvidedPaymentOptions 元素：

範例

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

允許的方法

AllowedAuthMethods 類型包含下列值：

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

允許的卡片網路

AllowedCardNetworks 類型包含下列值：

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

CardParameters

請使用這個物件，為網站設定 Google Pay API 支援。

下表列出 CardParameters 類型的屬性：

屬性 類型 說明
allowedAuthMethods 清單<缺點

這是必填欄位。

可用於驗證卡片交易的欄位。

不可超過 1 個項目。
allowedCardNetworks 清單<AllowedCardNetworks>

這是必填欄位。

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

不可超過 1 個項目。
billingAddressRequired 布林

如果您需要帳單地址，請設為 true。只有在帳單地址需要處理交易時，才申請帳單地址。其他資料要求可能會增加結帳程序的阻礙，進而降低轉換率。
cvcRequired 布林

如果使用 TimesofMoney，則設為 true，所有其他付款處理方設為 false。

以下範例為 CardParameters 元素：

範例

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

GoogleProvidedPaymentInstrument

下表列出 GoogleProvidedPaymentInstrument 類型的屬性：

屬性 類型 說明
instrumentToken String

這是必填欄位。

這個 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 清單<SupportedCardNetworks>

請改用 facitationationSpec。代理程式支援的發卡機構網路類型。

這個欄位已淘汰。
prepaidCardDisallowed 布林

請改用 facitationationSpec。是否允許預付卡做為付款方式。

這個欄位已淘汰。
billingAddressRequired 布林

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

這個欄位已淘汰。
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
}

商家資訊

請使用這個物件，為網站設定 Google Pay API 支援。

下表列出 MerchantInfo 類型的屬性：

屬性 類型 說明
merchantId String

Google Pay 核發的 Google 商家 ID。
merchantName String

這是必填欄位。

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

OnFulfillmentPaymentData

使用這個物件傳送 PaymentType 的「&_tFONF&MENT;」額外資料。

下表列出 OnFulfillmentPaymentData 類型的屬性：

屬性 類型 說明
supportedPaymentOptions 清單<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"
}

付款資料要求

請使用這個物件，為網站設定 Google Pay API 支援。

下表列出 PaymentDataRequest 類型的屬性：

屬性 類型 說明
apiVersion 缺點

這是必填欄位。

主要 API 版本。

值：2
apiVersionMinor 缺點

這是必填欄位。

次要 API 版本。

值：0
merchantInfo MerchantInfo

這是必填欄位。

(Google Pay 商家 ID) 要求付款資料的商家相關資訊。
allowedPaymentMethods 清單<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,
        "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 類型的屬性：

屬性 類型 說明
displayName String

這是必填欄位。

收據上向使用者顯示的付款方式名稱。
paymentType PaymentType

這是必填欄位。
googleProvidedPaymentInstrument GoogleProvidedPaymentInstrument

可供動作使用的權杖。只有在你在 CheckoutResponseMessage 中指定付款選項時，才需要指定這個值。

以下範例為 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"
}

付款方式

請使用這個物件，為網站設定 Google Pay API 支援。

下表列出 PaymentMethod 類型的屬性：

屬性 類型 說明
type 缺點

這是必填欄位。

支援付款方式的簡短 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 類型的屬性：

屬性 類型 說明
必須選取下列其中一組屬性。
googleProvidedOptions 群組 1 GoogleProvidedPaymentOptions

與 actionProvidedOptions 互斥。使用此付款方式透過 gPay 進行線上付款。
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

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

付款選項列舉

PaymentOptionsEnums 類型包含下列值：

  • Cash
  • Card
  • UPI
  • Paytm

PaymentType

PaymentType 類型包含下列值：

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

支援的發卡機構

定義與 GoogleProvidedPaymentOptions 相關的類型。

SupportedCardNetworks 類型包含下列值：

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

TokenizationParameters

定義與 GoogleProvidedPaymentOptions 相關的類型。

下表列出 TokenizationParameters 類型的屬性：

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

這是必填欄位。

請改用 facitationationSpec。可接受的權杖類型。
parameters Parameters

請改用 facitationationSpec。

權杖化規格

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

下表列出 TokenizationSpecification 類型的屬性：

屬性 類型 說明
type 缺點

這是必填欄位。
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 缺點

這是必填欄位。

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

值：ESTIMATED
totalPrice String

這是必填欄位。

交易的總金額，可選擇將小數點小數設為兩位。這個欄位的值必須與 car.totalPrice 相同。

以下範例為 TransactionInfo 元素：

範例

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