Set up submit order

After a customer successfully checks out through the Food Ordering user interface, Google sends your Food Ordering web service a JSON request that contains the information for the order. Your web service must receive this order, process it, and respond back to Google with the state of the order.

This section describes the order request message format sent by Google, called the SubmitOrderRequestMessage, and the format of the response message you must provide, called the SubmitOrderResponseMessage. For more information about the order fulfillment lifecycle, see the Fulfillment overview.

Order fulfillment implementation

The Food Ordering web service you build to work with Food Ordering must include a URL endpoint for receiving order messages from Google. For order processing, your web service receives a SubmitOrderRequestMessage in JSON format as a POST request from Google. This request contains a customer order, including taxes, fees, and payment information. Upon receiving a submit order request, your web service must do the following:

  • Check transaction eligibility, such as card verification or fraud detection.
  • Create an order in your system.
  • Authorize the payment method and call the charge API of your payment processor when applicable.
  • Respond with the appropriate state of the order: CREATED, CONFIRMED, or REJECTED.

After processing the order, your fulfillment code must provide a response in the form of a SubmitOrderResponseMessage JSON message back to Google.

For more information about the Food Ordering fulfillment web service implementation requirements, see the Fulfillment overview.

Order request message

When a customer chooses to place an order during the Food Ordering flow, Google sends a request to your web service with a JSON message called a SubmitOrderRequestMessage that contains the following data:

  1. Intent: The inputs[0].intent field of every submit order request body contains the actions.intent.TRANSACTION_DECISION string value.
  2. Order: The inputs[0].arguments[0].transactionDecisionValue field of a submit order request contains an Order object that represents the customer's order to be placed, along with payment details.
  3. Sandbox flag: The isInSandbox field of a submit order request indicates whether the transaction uses sandbox payments.

Order request example

The following is an example SubmitOrderRequestMessage:

JSON

{
    "user": {},
    "conversation": {
        "conversationId": "CTKbKfUlHCyDEdcz_5PBJTtf"
    },
    "inputs": [
        {
            "intent": "actions.intent.TRANSACTION_DECISION",
            "arguments": [
                {
                    "transactionDecisionValue": {
                        "order": {
                            "finalOrder": {
                                "cart": {
                                    "merchant": {
                                        "id": "restaurant/Restaurant/QWERTY",
                                        "name": "Tep Tep Chicken Club"
                                    },
                                    "lineItems": [
                                        {
                                            "name": "Spicy Fried Chicken",
                                            "type": "REGULAR",
                                            "id": "299977679",
                                            "quantity": 2,
                                            "price": {
                                                "type": "ESTIMATE",
                                                "amount": {
                                                    "currencyCode": "AUD",
                                                    "units": "39",
                                                    "nanos": 600000000
                                                }
                                            },
                                            "offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
                                            "extension": {
                                                "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                                            }
                                        }
                                    ],
                                    "extension": {
                                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                                        "fulfillmentPreference": {
                                            "fulfillmentInfo": {
                                                "delivery": {
                                                    "deliveryTimeIso8601": "P0M"
                                                }
                                            }
                                        },
                                        "location": {
                                            "coordinates": {
                                                "latitude": -33.8376441,
                                                "longitude": 151.0868736
                                            },
                                            "formattedAddress": "Killoola St, 1, Concord West NSW 2138",
                                            "zipCode": "2138",
                                            "city": "Concord West",
                                            "postalAddress": {
                                                "regionCode": "AU",
                                                "postalCode": "2138",
                                                "administrativeArea": "NSW",
                                                "locality": "Concord West",
                                                "addressLines": [
                                                    "Killoola St",
                                                    "1"
                                                ]
                                            }
                                        },
                                        "contact": {
                                            "displayName": "Hab Sy",
                                            "email": "hab9878.sy@gmail.com",
                                            "phoneNumber": "+61000000000",
                                            "firstName": "Hab",
                                            "lastName": "Sy"
                                        }
                                    }
                                },
                                "otherItems": [
                                    {
                                        "name": "Delivery fee",
                                        "type": "DELIVERY",
                                        "price": {
                                            "type": "ESTIMATE",
                                            "amount": {
                                                "currencyCode": "AUD",
                                                "units": "3",
                                                "nanos": 500000000
                                            }
                                        }
                                    },
                                    {
                                        "name": "Subtotal",
                                        "type": "SUBTOTAL",
                                        "price": {
                                            "type": "ESTIMATE",
                                            "amount": {
                                                "currencyCode": "AUD",
                                                "units": "39",
                                                "nanos": 600000000
                                            }
                                        }
                                    }
                                ],
                                "totalPrice": {
                                    "type": "ESTIMATE",
                                    "amount": {
                                        "currencyCode": "AUD",
                                        "units": "43",
                                        "nanos": 100000000
                                    }
                                },
                                "extension": {
                                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
                                }
                            },
                            "googleOrderId": "01412971004192156198",
                            "orderDate": "2020-10-22T09:02:06.173Z",
                            "paymentInfo": {
                                "displayName": "Pay when you get your food",
                                "paymentType": "ON_FULFILLMENT"
                            },
                            "customerInfo": {
                                "email": "hab9878.sy@gmail.com"
                            }
                        }
                    }
                }
            ]
        }
    ],
    "directActionOnly": true,
    "isInSandbox": true
}
    

Order response message

After receiving a request, your Food Ordering web service processes the request and sends back a SubmitOrderResponseMessage that includes the following data:

  • OrderUpdate: An object containing the state of the order, and any post-order actions available to the user, such as contacting support and viewing order details, which you define in the finalResponse.richResponse.items[0].structuredResponse.orderUpdate field of the response.

Order update field

When your web service sends a SubmitOrderResponseMessage, it contains an OrderUpdate field that includes the following fields:

  • actionOrderId: The unique ID of the order, which is used to uniquely identify the order in your system and refer to it when sending subsequent order updates.
  • orderState: An OrderState object representing the state of the order.
  • orderManagementActions: Post-order actions available to the user, such as contacting customer support and viewing order details.
  • totalPrice: The total price of the order.

An order can be in one of the following states:

  • CREATED: Your fulfillment endpoint processed the order successfully, but the provider has not yet confirmed the order.
  • CONFIRMED: Your fulfillment endpoint processed the order successfully, and the provider has confirmed the order.
  • REJECTED: There was a problem and your fulfillment endpoint could not create or confirm the order, which can include problems with payment.

If you set an order to a REJECTED state, specify the reason in the rejectionInfo field of OrderUpdate. Use FoodOrderUpdateExtension.FoodOrderErrors values in conjunction with rejectionInfo of type UNKNOWN and provide a description.

Order response example

The following is an example SubmitOrderResponseMessage:

JSON

{
    "finalResponse": {
        "richResponse": {
            "items": [
                {
                    "structuredResponse": {
                        "orderUpdate": {
                            "actionOrderId": "1603357328160",
                            "orderState": {
                                "state": "CONFIRMED",
                                "label": "Pending"
                            },
                            "updateTime": "2020-10-22T02:02:08-07:00",
                            "orderManagementActions": [
                                {
                                    "type": "CUSTOMER_SERVICE",
                                    "button": {
                                        "title": "Call customer service",
                                        "openUrlAction": {
                                            "url": "tel:+61234561000"
                                        }
                                    }
                                },
                                {
                                    "type": "VIEW_DETAILS",
                                    "button": {
                                        "title": "View order details",
                                        "openUrlAction": {
                                            "url": "https://partner.com/view/orderstatus"
                                        }
                                    }
                                }
                            ],
                            "receipt": {
                                "userVisibleOrderId": "BXZ-1603357328"
                            }
                        }
                    }
                }
            ]
        }
    }
}