促銷抵免額

促銷活動可讓您和 Google 以折扣價鼓勵客戶試用您的訂餐服務。Google 支援整合「訂購端對端動作」與您的促銷活動管理系統。

支援的折扣類型如下：

  • Google 贊助的促銷代碼：由 Google 預先填入或使用者輸入的促銷代碼。
  • 第三方贊助的促銷代碼：由您的訂餐服務提供促銷代碼，供使用者輸入。
  • 第三方贊助的自動折扣：沒有促銷代碼，由您的訂餐服務自動套用折扣。

無論折扣類型為何，Google 都會向您的餐點訂購執行要求發出結帳呼叫，確認並套用折扣。

身為訂餐服務的開發人員，您必須對實作項目做出一些變更，以便計算有效促銷代碼的折扣或傳送無效促銷代碼的錯誤訊息、管理促銷代碼兌換限制，以及追蹤報銷資料。

如何處理促銷活動

如要實作支援促銷活動的執行要求，請按照下列指示操作：

  1. 設定促銷活動整合功能。(如果您不使用 Google 贊助的促銷代碼，請略過這個步驟)。
  2. 透過促銷活動提供結帳流程。
  3. 導入含有促銷活動的訂單。

設定促銷活動整合功能

本節說明如果您打算使用 Google 贊助的促銷代碼，該如何設定促銷活動整合。如果您只想支援第三方贊助商的促銷代碼或折扣，您可以自行指定設定，並略過本節的步驟。

Google 會指定贊助者的促銷活動類型，並與您聯絡以設定整合。我們提供下列詳細資訊：

  • 折扣金額。
  • 最低購物車價值。
  • 促銷代碼使用的開始和結束日期。
  • 促銷活動廣告活動的預算金額上限。
  • 促銷代碼可使用的次數。

促銷代碼範例：

  • FopaNewUser：10% (固定百分比)，最多可折扣 $50 美元。
  • FopaMoreThan50：$10 美元 (固定金額折扣)。

如 Google 決定暫停申請代碼，我們會與您聯絡。

設定付款

如需設定撥款程序，請與您的 Google EAP 顧問聯絡。 只有在最終訂單狀態為下列任一種時，Google 才會退還費用：

  • CONFIRMED
  • IN_TRANSIT
  • READY_FOR_PICKUP
  • IN_PREPARATION
  • FULFILLED

透過促銷活動導入結帳功能

本節說明如何在支援促銷代碼 (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 ...}

運算折扣

如果促銷代碼有效，執行要求應計算折扣金額值，然後傳回 CheckoutResponseMessage，其中包含在 otherItems 陣列中計算出的折扣值。訂單總價不得為負數。如果折扣金額超過購物車金額，請回傳最高金額以將訂單總價轉譯為 $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 的促銷代碼無效 (例如已過期、無效或無法辨識)，請傳送含有 foodOrderError 且含有適用錯誤代碼和原因文字的 CheckoutResponseMessage，以及 correctedProposedOrder 和 paymentOptions 物件。

如果執行要求從同一項要求中發現多個促銷代碼錯誤，請先傳回無法復原的錯誤，然後再傳送可復原的錯誤。按照以下方式排定檢查的優先順序 (從高到低)：

  • PROMO_NOT_RECOGNIZED
  • PROMO_EXPIRED
  • PROMO_USER_INELIGIBLE
  • PROMO_ORDER_INELIGIBLE
  • PROMO_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."
      }
    ]
  }
}