Implement advanced order updates

After a customer submits an order, you can notify the customer of changes to the order by sending an order update message to Google. Google then relays that message to the customer within the ordering UI.

Common reasons for sending order updates include:

  • The estimated fulfillment time for the order becomes available or changes.
  • The state of an order changes.
  • The order can no longer be fulfilled.
  • The price of a menu item included in the order changed.
  • The customer has a new way to manage their order, such as a customer support or restaurant phone number.
  • The receipt for the order becomes available.

For example, the following example uses an order update to change the status of a customer's order from CREATED to CONFIRMED after the restaurant confirms the order:

Use case How to implement
Use case 1: Restaurant confirms the order An OrderUpdate with a CONFIRMED status is sent to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and estimatedFulfillmentTime.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
        "actionOrderId": "sample_action_order_id",
        "orderState": {
          "state": "CONFIRMED",
          "label": "Provider confirmed"
        },
        "receipt": {
          "userVisibleOrderId": "userVisibleId1234"
        },
        "updateTime": "2017-07-17T12:00:00Z",
        "orderManagementActions": [
          {
            "type": "CUSTOMER_SERVICE",
            "button": {
              "title": "Contact customer service",
              "openUrlAction": {
                "url": "mailto:support@example.com"
              }
            }
          },
          {
            "type": "EMAIL",
            "button": {
              "title": "Email restaurant",
              "openUrlAction": {
                "url": "mailto:person@example.com"
              }
            }
          },
          {
            "type": "CALL_RESTAURANT",
            "button": {
              "title": "Call restaurant",
              "openUrlAction": {
                "url": "tel:+16505554679"
              }
            }
          },
          {
            "type": "CALL_DRIVER",
            "button": {
              "title": "Call driver",
              "openUrlAction": {
                "url": "tel:+16505554681"
              }
            }
          }
        ],
        "infoExtension": {
           "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
           "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
        }
      }
  }
}

For the basics of implementing order updates for your project, read the guide Async order updates.

The next sections provide examples for more advanced order update scenarios.

Rejected status

The examples below demonstrate an AsyncOrderUpdateRequestMessage for orders that have been rejected for various reasons. Some examples of rejection reasons are when the restaurant can no longer fulfill the order or when the delivery address associated with the order is out of range.

Use case How to implement
Use case 1: Order is rejected because the provider cannot contact the restaurant or the restaurant cannot fulfill the order. Send an OrderUpdate with a REJECTED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, rejectionInfo, and foodOrderError of error type NO_CAPACITY.
Use case 2: Order is rejected because the driver is unavailable or the delivery address is out of range. Send an OrderUpdate with a REJECTED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, rejectionInfo, and foodOrderError of error type OUT_OF_SERVICE_AREA.
Use case 3: Order is rejected because the restaurant is closed unexpectedly or is closing. Send an OrderUpdate with a REJECTED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, rejectionInfo, and foodOrderError of error type CLOSED.
Use case 4: Order is rejected because some of the items are out of stock. Send an OrderUpdate with a REJECTED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, rejectionInfo, and foodOrderError of error type AVAILABILITY_CHANGED.
Use case 5: Order is rejected for unknown or uncategorized reasons. Send an OrderUpdate with a REJECTED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and rejectionInfo of error type UNKNOWN.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
         "type": "UNKNOWN",
         "reason": "Sorry, the restaurant cannot take your order right now."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "foodOrderErrors": [
          {
            "error": "NO_CAPACITY",
            "description": "Sorry, the restaurant cannot take your order right now."
          }
        ]
      }
    }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
         "type": "UNKNOWN",
         "reason": "Sorry, delivery is currently not available to your address."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "foodOrderErrors": [
          {
            "error": "OUT_OF_SERVICE_AREA",
            "description": "Sorry, delivery is currently not available to your address."
          }
        ]
      }
    }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
         "type": "UNKNOWN",
         "reason": "Sorry, the restaurant is closed unexpectedly."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "foodOrderErrors": [
          {
            "error": "CLOSED",
            "description": "Sorry, the restaurant is closed unexpectedly."
          }
        ]
      }
    }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
         "type": "UNKNOWN",
         "reason": "Sorry, some of items are not available right now."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "foodOrderErrors": [
          {
            "error": "AVAILABILITY_CHANGED",
            "id": "sample_menu_item_id",
            "description": "Sorry, some of the items are not available right now."
          }
        ]
      }
    }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
         "type": "UNKNOWN",
         "reason": "Sorry, your order is rejected."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ]
    }
  }
}

Cancelled status

The example below demonstrates an AsyncOrderUpdateRequestMessage for orders cancelled by customer request.

Use case How to implement
Use case 1: Order is cancelled by customer request Send an OrderUpdate with a CANCELLED status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and cancellationInfo.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CANCELLED",
        "label": "Order cancelled"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "cancellationInfo": {
         "reason": "Customer requested"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ]
    }
  }
}

Fulfilled status

The example below demonstrates an AsyncOrderUpdateRequestMessage for orders that have been been fulfilled.

Use case How to implement
Use case 1: Order is fulfilled Send an OrderUpdate with a FULFILLED status to Google. It must have actionOrderId, userVisibleOrderId, and orderManagementActions.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "FULFILLED",
        "label": "Order delivered"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "fulfillmentInfo": {
         "deliveryTime": "2017-05-10T02:30:00.000Z"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ]
    }
  }
}

In-transit status

The example below demonstrates an AsyncOrderUpdateRequestMessage for delivery orders that are in transit to the customer.

Use case How to implement
Use case 1: Delivery order is in transit. Send an OrderUpdate with a IN_TRANSIT status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and estimatedFulfillmentTime.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "IN_TRANSIT",
        "label": "Order is on the way"
      },
      "inTransitInfo": {
        "updatedTime": "2017-07-17T12:00:00Z"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
         "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
         "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}

Ready-for-pickup status

The example below demonstrates an AsyncOrderUpdateRequestMessage for orders that are ready to be picked up by the customer.

Use case How to implement
Use case 1: Order is ready to be picked up. Send an OrderUpdate with a READY_FOR_PICKUP status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and estimatedFulfillmentTime.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "READY_FOR_PICKUP",
        "label": "Order is ready for pickup"
      },
      "updateTime": "2018-04-15T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
         "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
         "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}

Food-in-preparation status

The example below demonstrates an AsyncOrderUpdateRequestMessage for orders that are being prepared by the restaurant.

Use case How to implement
Use case 1: Order is being prepared by the restaurant. Send an OrderUpdate with a IN_PREPARATION status to Google. It must have actionOrderId, userVisibleOrderId, orderManagementActions, and estimatedFulfillmentTime.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "IN_PREPARATION",
        "label": "Order is being prepared"
      },
      "updateTime": "2018-04-15T11:30:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
         "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
         "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}

Order changed status

The examples below demonstrate an AsyncOrderUpdateRequestMessage for various changes made to a customer's order.

Use case 1: Estimated fulfillment time needs to be updated. Send an OrderUpdate to Google with an order status, actionOrderId, userVisibleOrderId, orderManagementAction, and the updated estimatedFulfillmentTime.
Use case 2: Total price of the order needs to be updated. Send an OrderUpdate to Google with an order status, actionOrderId, userVisibleOrderId, orderManagementAction, estimatedFulfillmentTime, and the updated totalPrice.
Use case 3: Order management actions of the order needs to be updated. Send an OrderUpdate to Google with an order status, actionOrderId, userVisibleOrderId, estimatedFulfillmentTime, and the updated orderManagementActions.

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
        "actionOrderId": "sample_action_order_id",
        "orderState": {
          "state": "CONFIRMED",
          "label": "Provider confirmed"
        },
        "receipt": {
          "userVisibleOrderId": "userVisibleId1234"
        },
        "updateTime": "2017-07-17T12:00:00Z",
        "orderManagementActions": [
          {
            "type": "CUSTOMER_SERVICE",
            "button": {
              "title": "Contact customer service",
              "openUrlAction": {
                "url": "mailto:support@example.com"
              }
            }
          },
          {
            "type": "EMAIL",
            "button": {
              "title": "Email restaurant",
              "openUrlAction": {
                "url": "mailto:person@example.com"
              }
            }
          },
          {
            "type": "CALL_RESTAURANT",
            "button": {
              "title": "Call restaurant",
              "openUrlAction": {
                "url": "tel:+16505554679"
              }
            }
          },
          {
            "type": "CALL_DRIVER",
            "button": {
              "title": "Call driver",
              "openUrlAction": {
                "url": "tel:+16505554681"
              }
            }
          }
        ],
        "infoExtension": {
           "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
           "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
        }
      }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CONFIRMED",
        "label": "Provider confirmed"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "totalPrice": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "20",
          "nanos": 500000000
        }
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:support@example.com"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:person@example.com"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:+16505554679"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:+16505554681"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
      }
    }
  }
}

JSON

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
        "actionOrderId": "sample_action_order_id",
        "orderState": {
          "state": "CONFIRMED",
          "label": "Provider confirmed"
        },
        "receipt": {
          "userVisibleOrderId": "userVisibleId1234"
        },
        "updateTime": "2017-07-17T12:00:00Z",
        "orderManagementActions": [
          {
            "type": "CUSTOMER_SERVICE",
            "button": {
              "title": "Contact customer service",
              "openUrlAction": {
                "url": "mailto:support@example.com"
              }
            }
          },
          {
            "type": "EMAIL",
            "button": {
              "title": "Email restaurant",
              "openUrlAction": {
                "url": "mailto:person@example.com"
              }
            }
          },
          {
            "type": "CALL_RESTAURANT",
            "button": {
              "title": "Call restaurant",
              "openUrlAction": {
                "url": "tel:+16505554679"
              }
            }
          },
          {
            "type": "CALL_DRIVER",
            "button": {
              "title": "Call driver",
              "openUrlAction": {
                "url": "tel:+16505554681"
              }
            }
          }
        ],
        "infoExtension": {
           "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
           "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
        }
      }
  }
}