通过促销活动，您和 Google 可以通过折扣价格来激励客户试用您的外卖服务。Google 支持将您的端到端订购操作与促销活动管理系统集成。
支持以下类型的折扣：
- Google 赞助的促销代码：由 Google 自动预先填充或由用户输入的促销代码。
- 第三方赞助的促销代码：供用户输入的促销代码，由您的外卖服务提供。
- 第三方赞助的自动折扣：您的外卖服务无需促销代码即可自动应用的折扣。
无论折扣类型如何，Google 都会向您的外卖执行服务进行结账调用，以验证并应用折扣。
作为食品订餐服务的开发者，您需要对实现进行一些更改，以便计算有效促销代码的折扣或发送无效促销代码的错误消息、管理促销代码兑换限制，以及跟踪退款的会计数据。
如何处理促销活动
如需实现支持促销活动的执行方式，请执行以下操作：
- 设置促销活动集成。（如果您不使用 Google 赞助的促销代码，请跳过此步骤。）
- 实现带促销优惠的结账。
- 实现提交含促销信息的订单。
设置促销活动集成
如果您打算使用 Google 赞助的促销代码，本部分将介绍如何设置促销活动集成。如果您只想支持第三方赞助的促销代码或折扣，可以自行指定设置，并跳过本部分。
Google 会指定要赞助的促销活动类型，并与您联系以设置集成。我们会提供以下详细信息：
- 折扣金额。
- 购物车最低金额。
- 促销代码的使用开始日期和结束日期。
- 为促销活动预算的最高美元金额。
- 促销代码的可使用次数。
促销代码示例：
FopaNewUser：8 折（固定百分比），最高可抵扣 50 美元。FopaMoreThan50：10 美元（固定金额折扣）。
如果 Google 决定暂停应用代码，会与您联系。
设置付款
请与您的 Google EAP 顾问联系，设置发放流程。只有在最终订单状态为以下某种状态时，Google 才会为涉及 Google 赞助的促销代码的交易退款：
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
实现带有促销活动的结账
本部分介绍了在支持促销代码（由 Google 赞助或由第三方赞助）时如何实现结账处理。对于第三方赞助的自动折扣，您只需在 CheckoutResponseMessage 中返回折扣订单项（无需检查促销代码）。
在处理外卖订单期间，Google 会向您的执行方式发送一个 CheckoutRequestMessage 中的促销代码。用户在重复发出结账请求时可以更改购物车或促销代码。
如需检查这是用户首次应用促销代码，请执行以下操作：
- Google 赞助的促销代码：Google 会检查回访用户是否尝试再次使用同一促销代码；您无需执行任何操作。
- 第三方赞助的促销代码或自动折扣：如果您尚未实现账号关联和用户选择接受，则在处理结账请求期间将无法查看用户的详细信息。而是应在
SubmitOrderRequestMessage处理期间，使用FoodCartExtension对象中的Contact详细信息（例如用户的电子邮件地址）进行检查。
根据最新的结账请求，找出错误或计算履单折扣。执行此操作时，请确保您的系统不会保留过时状态信息。
检查促销代码的有效性
您的执行方式应根据规定的条款（例如失效日期、使用次数上限和折扣上限）检查给定促销代码的有效性或资格条件。然后，在 CheckoutResponseMessage 中使用计算出的折扣进行适当响应；如果无法应用促销代码，则使用 foodOrderErrors 进行响应。如果您发现促销代码存在错误，请按照处理促销活动错误中所述的流程操作。
以下代码段显示了促销代码的示例 foodOrderErrors。
确保 correctedProposedOrder 不包含促销活动节点。
"foodOrderErrors": [
{
"error": "PROMO_NOT_APPLICABLE",
// Copy promotions.coupon string from CheckoutRequest as the ID
"id": "GoogleNewUser",
"description": "Promotion could not be applied"
}
],
"correctedProposedOrder": {// required ...},
"paymentOptions": {// required ...}
计算折扣
如果促销代码有效，您的执行方式应计算折扣金额，并在 otherItems 数组中发回包含计算的折扣金额的 CheckoutResponseMessage。订单总价不得为负数。如果折扣金额超过购物车金额，请发回最高美元金额，以使订单总金额为 0 美元。
以下代码段显示了促销折扣的 CheckoutResponseMessage 部分示例：
"proposedOrder": {
"otherItems": [
. . .
{
"name": "Discount",
// copy promotions.coupon field from CheckoutRequest as the id
"id": "GoogleNewUser",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-3",
"nanos": -500000000
}
},
"type": "DISCOUNT",
}
]
}
释放未使用的促销活动
并非每项结账请求都会导致提交订单请求。如果您的履单服务在结账调用时对促销优惠进行预授权，请确保您有相应的机制，以便在特定时间过后，如果客户未通过提交订单来兑换促销优惠，则释放预授权。这可确保您的外卖服务保持正确的广告系列配额。
处理促销活动错误
如果您的执行方式确定 CheckoutRequestMessage 中的促销代码无效（例如，已过期、无效或未被识别），请发送一个 CheckoutResponseMessage，其中包含包含适用错误代码和原因文本的 foodOrderError，以及 correctedProposedOrder 和 paymentOptions 对象。
如果您的执行服务在同一请求中发现多个促销代码错误，请先发回不可恢复的错误，然后再发回可恢复的错误。请按如下顺序（从高到低）确定检查的优先级：
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
示例
以下是包含促销代码的结账请求示例：
{ "accessToken": "test_access_token", "lastSeen": "2018-06-22T19:25:39Z" }, "conversation": { "conversationId": "XYZ" }, "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": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "sample_item_offer_id_1", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } } } } } ] } ], "directActionOnly": true, "isInSandbox": true }
如果促销代码有效，则执行方式如下所示：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "checkoutResponse": { "proposedOrder": { "otherItems": [ { "name": "Delivery Fees", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "3", "nanos": 500000000 } }, "type": "DELIVERY" }, { "name": "Tax", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "1", "nanos": 370000000 } }, "type": "TAX" }, { "name": "Promotion", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "-5", "nanos": 0 } }, "id": "FOPAACTIVECODE", "type": "DISCOUNT" } ], "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "2529103", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } } } }, "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 820000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension", "availableFulfillmentOptions": [ { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } }, "expiresAt": "2018-06-22T19:30:52.596Z" } ] } }, "orderOptions": {}, "paymentOptions": { "googleProvidedOptions": { "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "stripe", "stripe:publishableKey": "example_stripe_client_key", "stripe:version": "2017-04-06" } }, "supportedCardNetworks": [ "AMEX", "DISCOVER", "MASTERCARD", "VISA", "JCB" ], "prepaidCardDisallowed": true } } } } } ], "suggestions": [] } } }
以下是促销代码无效时的结账响应示例：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "error": { "foodOrderErrors": [ { "error": "PROMO_NOT_RECOGNIZED", "id": "SOMEPROMO", "description": "Coupon not found" } ], "correctedProposedOrder": { "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "id": "sample_item_offer_id_4", "name": "Prawns Biryani", "type": "REGULAR", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "18", "nanos": 750000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/offer/id4", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "extension": { "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } }, "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension" }, "promotions": [] }, "otherItems": [ { "name": "Tax", "type": "TAX", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "1", "nanos": 650000000 } } } ], "termsOfServiceUrl": "https://exampleprovider.com/terms", "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "20", "nanos": 400000000 } }, "extension": { "availableFulfillmentOptions": [ { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "PT0M" } } } ], "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "paymentOptions": { "googleProvidedOptions": { "prepaidCardDisallowed": false, "billingAddressRequired": true, "tokenizationParameters": { "tokenizationType": "PAYMENT_GATEWAY", "parameters": { "gateway": "braintree", "braintree:apiVersion": "v1", "braintree:sdkVersion": "1.4.0", "braintree:merchantId": "example_braintree_merchant_ID", "braintree:clientKey": "example_braintree_client_key", "braintree:authorizationFingerprint": "example_braintree_fingerprint" } } } }, "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension" } } } ] } } }
实现提交含促销信息的订单
在提交的订单执行中，检查用户是否是首次应用促销代码。在处理 SubmitOrderRequestMessage 期间，您可以使用 FoodCartExtension 对象中的 Contact 详细信息（例如用户的电子邮件地址）进行检查。
您还应重新检查促销代码的适用性：
- 如果代码适用：确认订单并将优惠券标记为已兑换。
- 如果代码已不再适用：使用
PROMO_NOT_APPLICABLE错误拒绝订单。您可以使用与FoodOrderUpdateExtension相同的机制提供具体拒绝原因。
示例
以下是包含促销信息的提交订单请求示例：
{ "conversation": { "conversationId": "example_conversation_ID" }, "inputs": [ { "intent": "actions.intent.TRANSACTION_DECISION", "arguments": [ { "transactionDecisionValue": { "order": { "finalOrder": { "cart": { "merchant": { "id": "https://www.exampleprovider.com/merchant/id1", "name": "Falafel Bite" }, "lineItems": [ { "name": "Falafel Tray", "type": "REGULAR", "id": "sample_item_offer_id_1", "quantity": 1, "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } }, "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1", "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension" } } ], "promotions": [ { "coupon": "FOPAACTIVECODE" } ], "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension", "fulfillmentPreference": { "fulfillmentInfo": { "pickup": { "pickupTimeIso8601": "P0M" } } }, "contact": { "displayName": "Food Ordering", "email": "example.provider@gmail.com", "phoneNumber": "+19993334444", "firstName": "Food", "lastName": "Ordering" } } }, "otherItems": [ { "name": "Delivery Fees", "type": "DELIVERY", "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": "Promotion", "type": "DISCOUNT", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "-5" } }, "id": "FOPAACTIVECODE" }, { "name": "Subtotal", "type": "SUBTOTAL", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 950000000 } } }, { "name": "Tip", "type": "GRATUITY", "price": { "type": "ESTIMATE", "amount": { "currencyCode": "USD" } } } ], "totalPrice": { "type": "ESTIMATE", "amount": { "currencyCode": "USD", "units": "9", "nanos": 820000000 } }, "extension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension" } }, "googleOrderId": "example_google_order_ID", "orderDate": "2018-06-22T19:30:59.502Z", "paymentInfo": { "displayName": "example_display_name", "googleProvidedPaymentInstrument": { "instrumentToken": "example_instrument_token" }, "paymentType": "PAYMENT_CARD" }, "locale": "en" } } } ] } ], "directActionOnly": true, "isInSandbox": true }
如果促销代码有效，以下是来自履单服务的相应提交订单响应示例：
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "structuredResponse": { "orderUpdate": { "actionOrderId": "example_action_order_ID", "orderState": { "state": "CREATED", "label": "Order is created with partner." }, "updateTime": "2018-06-22T19:31:01.556Z", "orderManagementActions": [ { "type": "CALL_RESTAURANT", "button": { "title": "Call Us", "openUrlAction": { "url": "tel:+1-111-111-1111" } } }, { "type": "EMAIL", "button": { "title": "Email Us", "openUrlAction": { "url": "mailto:example.provider@gmail.com" } } }, { "type": "CUSTOMER_SERVICE", "button": { "title": "Customer Service", "openUrlAction": { "url": "http://www.google.com" } } } ] } } } ], "suggestions": [] } } }
以下是促销代码无效时提交订单响应的示例：
"orderUpdate": { "actionOrderId": "sample_action_order_id", "orderState": { "state": "REJECTED", "label": "Order rejected." }, "updateTime": "2017-05-10T02:30:00.000Z", "rejectionInfo": { "type": "PROMO_NOT_APPLICABLE", "reason": "Sorry, there's something wrong. Try another code?" }, "orderManagementActions": [ { "type": "CUSTOMER_SERVICE", "button": { "title": "Contact customer service", "openUrlAction": { "url": "mailto:support@example.com" } } }, { "type": "EMAIL", "button": { "title": "Email restaurant", "openUrlAction": { "url": "mailto:example.provider@example.com" } } }, { "type": "CALL_RESTAURANT", "button": { "title": "Call restaurant", "openUrlAction": { "url": "tel:+19993334444" } } } ], "infoExtension": { "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension", "foodOrderErrors": [ { "error": "PROMO_USER_INELIGIBLE", "description": "Sorry, you can only use this promotion once." } ] } }