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