Chương trình khuyến mãi cho phép bạn và Google khuyến khích khách hàng dùng thử dịch vụ đặt món ăn của bạn với giá chiết khấu. Google hỗ trợ tích hợp Đơn đặt hàng của bạn với Google Actions bằng hệ thống quản lý chương trình khuyến mãi của bạn.
Chúng tôi hỗ trợ các loại chiết khấu sau:
- Mã khuyến mãi do Google tài trợ: Mã khuyến mãi được Google điền sẵn tự động hoặc do người dùng nhập.
- Mã khuyến mãi do bên thứ ba tài trợ: Mã khuyến mãi cho người dùng nhập, do dịch vụ đặt đồ ăn của bạn cung cấp.
- Chiết khấu tự động do bên thứ ba tài trợ: Chiết khấu mà dịch vụ đặt món ăn của bạn tự động áp dụng mà không cần mã khuyến mãi.
Bất kể loại chiết khấu, Google đều sẽ thực hiện cuộc gọi thanh toán đến địa chỉ thực hiện đơn đặt món của bạn để xác minh và áp dụng chiết khấu.
Là nhà phát triển của một dịch vụ đặt món ăn, bạn cần thực hiện một số thay đổi đối với phương thức triển khai của mình để tính toán các khoản chiết khấu cho mã khuyến mãi hợp lệ hoặc gửi lỗi cho mã khuyến mãi không hợp lệ, quản lý hạn mức sử dụng mã khuyến mãi và theo dõi dữ liệu kế toán để hoàn tiền.
Cách xử lý chương trình khuyến mãi
Để triển khai một phương thức thực hiện đơn hàng hỗ trợ chương trình khuyến mãi, hãy làm như sau:
- Thiết lập chế độ tích hợp chương trình khuyến mãi. (Bỏ qua bước này nếu bạn không sử dụng mã khuyến mại do Google tài trợ.)
- Triển khai quy trình thanh toán bằng các chương trình khuyến mãi.
- Triển khai đơn đặt hàng gửi kèm khuyến mãi.
Thiết lập chế độ tích hợp chương trình khuyến mãi
Phần này mô tả cách tích hợp chương trình khuyến mãi nếu bạn dự định sử dụng mã khuyến mãi do Google tài trợ. Nếu chỉ muốn hỗ trợ mã khuyến mãi hoặc ưu đãi chiết khấu do bên thứ ba tài trợ, bạn có thể chỉ định chế độ thiết lập của riêng mình và bỏ qua phần này.
Google chỉ định loại chương trình khuyến mãi để tài trợ và liên hệ với bạn để thiết lập chế độ tích hợp. Chúng tôi cung cấp các chi tiết sau:
- Số tiền chiết khấu.
- Giá trị giỏ hàng tối thiểu.
- Ngày bắt đầu và ngày kết thúc để sử dụng mã khuyến mại.
- Số tiền tối đa được lập ngân sách cho chiến dịch quảng cáo.
- Số lần mã khuyến mại có thể được sử dụng.
Ví dụ về mã khuyến mại:
FopaNewUser: 10% (phần trăm cố định) với mức giảm giá tối đa là 50 USD.FopaMoreThan50: $10 (số tiền cố định được giảm).
Nếu Google quyết định tạm dừng áp dụng mã này, chúng tôi sẽ liên hệ với bạn.
Thiết lập thanh toán
Liên hệ với tư vấn viên EAP của Google để thiết lập quá trình giải ngân. Google chỉ hoàn tiền cho các giao dịch liên quan đến mã khuyến mãi do Google tài trợ nếu trạng thái đơn đặt hàng cuối cùng là một trong các trạng thái sau:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Triển khai thanh toán với khuyến mại
Phần này mô tả việc triển khai quy trình xử lý thanh toán khi bạn hỗ trợ mã khuyến mãi (do Google tài trợ hoặc do bên thứ ba tài trợ). Đối với
chiết khấu tự động được bên thứ ba tài trợ, bạn chỉ cần trả về
mục hàng giảm giá trong CheckoutResponseMessage (không cần kiểm tra mã khuyến mãi).
Trong quá trình thực hiện đơn đặt món, Google sẽ gửi một mã khuyến mãi trong CheckoutRequestMessage để bạn thực hiện đơn hàng. Người dùng có thể thay đổi giỏ hàng hoặc
mã khuyến mãi cho các yêu cầu thanh toán lặp lại.
Để kiểm tra xem đây có phải là lần đầu tiên người dùng áp dụng mã khuyến mãi hay không, hãy làm như sau:
- Mã khuyến mãi do Google tài trợ: Google kiểm tra xem người dùng cũ có đang cố gắng sử dụng lại mã khuyến mãi đó hay không. Bạn không cần làm gì cả.
- Mã khuyến mãi do bên thứ ba tài trợ hoặc ưu đãi giảm giá tự động: Nếu chưa triển khai việc liên kết tài khoản và người dùng đồng ý, thì bạn sẽ không thể kiểm tra chi tiết của người dùng trong quá trình xử lý yêu cầu thanh toán. Thay vào đó, hãy kiểm tra điều này trong quá trình xử lý
SubmitOrderRequestMessage, sử dụng chi tiếtContact(chẳng hạn như địa chỉ email của người dùng) từ đối tượngFoodCartExtension.
Xác định lỗi hoặc tính toán các khoản chiết khấu với phương thức thực hiện đơn hàng dựa trên yêu cầu thanh toán mới nhất. Khi làm như vậy, hãy đảm bảo rằng hệ thống của bạn không giữ thông tin trạng thái cũ.
Kiểm tra tính hợp lệ của mã khuyến mại
Việc thực hiện đơn hàng phải kiểm tra tính hợp lệ hoặc tính đủ điều kiện của một mã khuyến mãi nhất định đối với các điều khoản được quy định, chẳng hạn như ngày hết hạn, mức sử dụng tối đa và mức giảm giá tối đa. Sau đó, hãy phản hồi một cách thích hợp trong CheckoutResponseMessage với mức chiết khấu đã tính toán hoặc bằng foodOrderErrors nếu không thể áp dụng mã khuyến mãi. Nếu bạn phát hiện lỗi mã khuyến mãi, hãy làm theo quy trình được mô tả trong bài viết Xử lý lỗi với chương trình khuyến mãi.
Đoạn mã sau đây cho thấy ví dụ foodOrderErrors về mã khuyến mãi.
Hãy đảm bảo rằng correctedProposedOrder không bao gồm các nút
khuyến mãi.
"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 ...}
Tính chiết khấu
Nếu mã khuyến mãi hợp lệ, phương thức thực hiện phải tính toán giá trị bằng tiền chiết khấu và gửi lại một CheckoutResponseMessage với giá trị chiết khấu đã tính trong mảng otherItems. Tổng giá đơn đặt hàng không được
âm. Nếu số tiền chiết khấu vượt quá số tiền của giỏ hàng, hãy gửi lại số tiền tối đa để hiển thị tổng giá của đơn đặt hàng thành 0 đô la.
Đoạn mã sau đây cho thấy phần ví dụ CheckoutResponseMessage về chương trình giảm giá khuyến mãi:
"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",
}
]
}
Phát hành quảng cáo không được sử dụng
Không phải mọi yêu cầu thanh toán đều dẫn đến yêu cầu gửi đơn đặt hàng. Nếu phương thức thực hiện của bạn bị tạm ngưng trong một chương trình khuyến mãi tại thời điểm thanh toán, hãy đảm bảo bạn có cơ chế để giải phóng khoản tiền giữ lại nếu chương trình khuyến mãi không được xác nhận thông qua đơn đặt hàng sau một khoảng thời gian nhất định. Điều này đảm bảo rằng dịch vụ đặt món ăn của bạn duy trì đúng hạn mức chiến dịch.
Xử lý lỗi trong chương trình khuyến mãi
Nếu phương thức thực hiện đơn hàng của bạn xác định rằng mã khuyến mãi từ CheckoutRequestMessage không hợp lệ (ví dụ: mã này đã hết hạn, không hợp lệ hoặc không được nhận dạng), hãy gửi một CheckoutResponseMessage có foodOrderError chứa mã lỗi và văn bản lý do hiện hành cùng với các đối tượng correctedProposedOrder và paymentOptions.
Nếu việc thực hiện đơn hàng gặp nhiều lỗi mã khuyến mãi từ cùng một yêu cầu, hãy gửi lại các lỗi không thể khôi phục trước khi gửi lại lỗi có thể khôi phục. Sắp xếp mức độ ưu tiên cho các bước kiểm tra như sau (từ mức độ ưu tiên từ cao đến thấp):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Ví dụ
Dưới đây là ví dụ về yêu cầu thanh toán với mã khuyến mại:
{
"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
}
Dưới đây là phản hồi thanh toán tương ứng của phương thức thực hiện nếu mã khuyến mãi hợp lệ:
{
"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": []
}
}
}
Dưới đây là ví dụ về phản hồi thanh toán nếu mã khuyến mại không hợp lệ:
{
"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"
}
}
}
]
}
}
}
Triển khai đơn đặt hàng gửi kèm khuyến mại
Trong quá trình thực hiện đơn đặt hàng, hãy kiểm tra xem đây có phải là lần đầu tiên
người dùng áp dụng mã khuyến mãi hay không. Trong quá trình xử lý SubmitOrderRequestMessage, bạn có thể kiểm tra việc này bằng cách sử dụng Contact thông tin chi tiết (chẳng hạn như địa chỉ email của người dùng) từ đối tượng FoodCartExtension.
Bạn cũng nên kiểm tra lại phạm vi áp dụng của mã khuyến mãi:
- Nếu mã có thể áp dụng: Xác nhận đơn đặt hàng và đánh dấu phiếu giảm giá đã được đổi.
- Nếu mã không còn áp dụng: Từ chối đơn đặt hàng có lỗi
PROMO_NOT_APPLICABLE. Bạn có thể cung cấp lý do từ chối cụ thể bằng cơ chế tương tự như đối vớiFoodOrderUpdateExtension.
Ví dụ
Dưới đây là ví dụ về yêu cầu đặt hàng gửi kèm khuyến mại:
{
"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
}
Dưới đây là ví dụ về nội dung phản hồi đơn đặt hàng tương ứng từ một phương thức thực hiện nếu mã khuyến mãi hợp lệ:
{
"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": []
}
}
}
Dưới đây là ví dụ về phản hồi gửi đơn đặt hàng nếu mã khuyến mại không hợp lệ:
"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."
}
]
}
}