Fulfillment actions schema

This page describes the payload of the fulfillment web service (Order with Google API) when working with the Order with Google Built-in Action API. For a machine-readable version of this information, you can download the JSON schema.

Base Types

Cart

Contains details of the order, as well as whether the request is for pickup or delivery. A cart also contains delivery details, gratuity, and the delivery address. The Cart object is defined in a Checkout AppRequest.f You include a copy of the cart in your Checkout AppResponse

The following table lists the properties for the Cart type:

Property Type Description
@type Const

The type of this object. Omit this field if the parent Cart object is part of ProposedOrder.

Value: type.googleapis.com/google.actions.v2.orders.Cart

id String

Optional ID of the cart.

merchant Merchant

Merchant affiliated with this cart.

lineItems List<LineItem>

Required.

List of the good(s) or service(s) that the user is ordering.

Must have no fewer than 1 item.

promotions List<Promotion>

Promotion that is applied in this cart. Only one promotion is currently supported.

notes String

Notes about the order or delivery instructions.

extension FoodCartExtension

Defines details about the user, such as fulfillment preferences.

The following example shows a Cart element:

Example 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.Cart",
  "merchant": {
    "id": "https://www.exampleprovider.com/merchant/id1",
    "name": "Cucina Venti"
  },
  "lineItems": [
    {
      "name": "Sizzling Prawns Dinner",
      "type": "REGULAR",
      "id": "sample_item_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "16",
          "nanos": 750000000
        }
      },
      "subLines": [
        {
          "note": "Notes for this item."
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
        "options": [
          {
            "id": "sample_addon_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
            "name": "Honey Mustard",
            "price": {
              "currencyCode": "USD"
            },
            "quantity": 1
          },
          {
            "id": "sample_addon_offer_id_2",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
            "name": "BBQ Sauce",
            "price": {
              "currencyCode": "USD",
              "nanos": 500000000
            },
            "quantity": 1
          }
        ]
      }
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
    "fulfillmentPreference": {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P0M"
        }
      }
    },
    "location": {
      "coordinates": {
        "latitude": 37.788783,
        "longitude": -122.41384
      },
      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
      "zipCode": "94043",
      "city": "Mountain View",
      "postalAddress": {
        "regionCode": "US",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1350 Charleston Road"
        ]
      },
      "notes": "Gate code is #111"
    }
  }
}

Example 2

{
  "merchant": {
    "id": "https://www.exampleprovider.com/merchant/id1",
    "name": "Falafel Bite"
  },
  "lineItems": [
    {
      "name": "Pita Chips",
      "type": "REGULAR",
      "id": "sample_item_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "2",
          "nanos": 750000000
        }
      },
      "subLines": [
        {
          "note": "Notes for this item."
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
        "options": [
          {
            "id": "sample_addon_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
            "name": "Honey Mustard",
            "price": {
              "currencyCode": "USD"
            },
            "quantity": 1
          },
          {
            "id": "sample_addon_offer_id_2",
            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
            "name": "BBQ Sauce",
            "price": {
              "currencyCode": "USD",
              "nanos": 500000000
            },
            "quantity": 1
          }
        ]
      }
    },
    {
      "name": "Chicken Shwarma Wrap",
      "type": "REGULAR",
      "id": "sample_item_offer_id_2",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "8"
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    },
    {
      "name": "Greek Salad",
      "type": "REGULAR",
      "id": "sample_item_offer_id_3",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "9",
          "nanos": 990000000
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    },
    {
      "name": "Prawns Biryani",
      "type": "REGULAR",
      "id": "sample_item_offer_id_4",
      "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
      "quantity": 1,
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "15",
          "nanos": 990000000
        }
      },
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
      }
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
    "fulfillmentPreference": {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P90M"
        }
      }
    },
    "location": {
      "coordinates": {
        "latitude": 37.788783,
        "longitude": -122.41384
      },
      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
      "zipCode": "94043",
      "city": "Mountain View",
      "postalAddress": {
        "regionCode": "US",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1350 Charleston Road"
        ]
      },
      "notes": "Gate code is #111"
    }
  }
}

Contact

Specifies details about the person receiving the order. It is available only in AppResponse.

The following table lists the properties for the Contact type:

Property Type Description
displayName String

Name of the person receiving the order, as you would like it to be displayed. Use this field if firstName and lastName are not specified.

Example: Lovefood Ordering

email String

Email address of the person receiving the order.

Example: ilovefood@example.com

firstName String

First name of the person receiving the order.

Example: Lovefood

lastName String

Surname of the person receiving the order.

Example: Ordering

phoneNumber String

Phone number of the person receiving the order, including the country code.

Example: +16501234567

emailVerified Boolean

Indicates whether the person receiving the order is logged in with their Google account.

The following example shows a Contact element:

Example

{
  "displayName": "Lovefood Ordering",
  "email": "ilovefood@example.com",
  "phoneNumber": "+16501234567"
}

CustomPushMessage

Contains the OrderUpdate for the request.

The following table lists the properties for the CustomPushMessage type:

Property Type Description
orderUpdate OrderUpdate

Required.

Updated information for the order.

The following example shows a CustomPushMessage element:

Example

{
  "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"
          }
        }
      }
    ],
    "receipt": {
      "userVisibleOrderId": "userVisibleId1234"
    },
    "infoExtension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
      "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
    }
  }
}

DeliveryInfo

The following table lists the properties for the DeliveryInfo type:

Property Type Description
deliveryTimeIso8601 String

Estimated delivery time, in ISO 8601 time stamp format: "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" or duration format: "P(n)Y(n)M(n)DT(n)H(n)M(n)S". For instance, PT90M represents a duration of 90 minutes. The default value ,"PT0M", indicates that the preferred delivery time is as soon as possible. Reference: https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. Use this to update the estimated delivery time during checkout response.

Example: PT90M

The following example shows a DeliveryInfo element:

Example

{
  "deliveryTimeIso8601": "PT90M"
}

Disclaimer

The following table lists the properties for the Disclaimer type:

Property Type Description
predefinedMessage PredefinedMessage

Required.

To show predefined disclaimer messages during checkout.

feeAmount Money

Partner will charge the merchant a N amount fee for this order.

feeAmountRange FeeAmountRange

Partner will charge the restaurant a N to M amount fee per order.

feePercent Number

Partner will charge the merchant a N% fee for this order.

feePercentRange FeePercentRange

Partner will charge the merchant a N% to M% fee per order.

The following example shows a Disclaimer element:

Example 1

{
  "predefinedMessage": "NEW_YORK_DELIVERY_FEE_TIP_DISCLAIMER"
}

Example 2

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE"
}

Example 3

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feePercent": 25
}

Example 4

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feePercentRange": {
    "minFeePercent": 20,
    "maxFeePercent": 30
  }
}

Example 5

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feeAmount": {
    "currencyCode": "AUD",
    "units": 2,
    "nanos": 500000000
  }
}

Example 6

{
  "predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
  "feeAmountRange": {
    "minFeeAmount": {
      "currencyCode": "AUD",
      "units": 2,
      "nanos": 500000000
    },
    "maxFeeAmount": {
      "currencyCode": "AUD",
      "units": 10,
      "nanos": 0
    }
  }
}

Error

The Error type has the following possible values:

  • CLOSED: Restaurant is closed for business at ordering time.
  • NO_CAPACITY: There is no available service capacity (for example, a temporary outage due to peak times).
  • NO_COURIER_AVAILABLE: Unable to process the order because of limited delivery personnel.
  • REQUIREMENTS_NOT_MET: Constraints for accepting the order have not been met (for example, minimum basket size).
  • UNAVAILABLE_SLOT: The order cannot be fulfilled at the order ahead time specified by DeliveryInfo or PickupInfo.
  • OUT_OF_SERVICE_AREA: The order cannot be delivered to the user's address.
  • PROMO_EXPIRED: Could not apply as promotion expired.
  • PROMO_NOT_APPLICABLE: Generic error code to catch all cases of failure to apply promo code, if none of the other promo code errors fit.
  • PROMO_NOT_RECOGNIZED: The coupon code was not recognized.
  • PROMO_ORDER_INELIGIBLE: The current order is not eligible for this coupon.
  • PROMO_USER_INELIGIBLE: The current user is not eligible for this coupon.
  • AVAILABILITY_CHANGED: The item is no longer available, or there are insufficient items to fulfill the request.
  • INCORRECT_PRICE: Price errors in fees or total.
  • INVALID: A LineItem, FulfillmentOption, or Promotion contains invalid data.
  • NOT_FOUND: A LineItem, FulfillmentOption, or Promotion cannot be found.
  • PRICE_CHANGED: The price of an item has changed.

FeeAmountRange

The following table lists the properties for the FeeAmountRange type:

Property Type Description
minFeeAmount Money

Lower bound of fee amount charged..

maxFeeAmount Money

Upper bound of fee amount charged..

FeePercentRange

The following table lists the properties for the FeePercentRange type:

Property Type Description
minFeePercent Number

Lower bound of fee percent charged.

maxFeePercent Number

Upper bound of fee percent charged.

FoodCartExtension

Contains details about the user, such as fulfillment preferences.

The following table lists the properties for the FoodCartExtension type:

Property Type Description
@type Const

Type of this extension. This field is always set to "type.googleapis.com/google.actions.v2.orders.FoodCartExtension".

Value: type.googleapis.com/google.actions.v2.orders.FoodCartExtension

contact Contact

Contact information for the person receiving the order. Details include the person's name, phone number, and email address.

fulfillmentPreference FulfillmentOption

Required.

User's fulfillment preference.

location Location

In the CheckoutRequestMessage, this field specifies the delivery address, which is required if the order is for delivery. For orders that are for takeout or pickup, this field is not included in the message.

The following example shows a FoodCartExtension element:

Example 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
  "fulfillmentPreference": {
    "fulfillmentInfo": {
      "delivery": {
        "deliveryTimeIso8601": "P0M"
      }
    }
  },
  "location": {
    "coordinates": {
      "latitude": 37.788783,
      "longitude": -122.41384
    },
    "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
    "zipCode": "94043",
    "city": "Mountain View",
    "postalAddress": {
      "regionCode": "US",
      "postalCode": "94043",
      "administrativeArea": "CA",
      "locality": "Mountain View",
      "addressLines": [
        "1350 Charleston Road"
      ]
    },
    "notes": "Gate code is #111"
  }
}

Example 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
  "fulfillmentPreference": {
    "fulfillmentInfo": {
      "pickup": {
        "pickupTimeIso8601": "P0M"
      }
    }
  },
  "contact": {
    "displayName": "Lovefood Ordering",
    "email": "ilovefood@example.com",
    "phoneNumber": "+16501234567"
  }
}

FoodErrorExtension

Identifies one or more errors that occurred while processing a request. The following table describes the fields of the FoodErrorExtension type. Errors can be sent in a CheckoutResponse.

The following table lists the properties for the FoodErrorExtension type:

Property Type Description
@type Const

Required.

Type of this extension.

Value: type.googleapis.com/google.actions.v2.orders.FoodErrorExtension

foodOrderErrors List<FoodOrderError>

Required.

Array of FoodOrderError objects that describe the errors that occurred. Recommended one error per cart or per item.

Must have no fewer than 1 item.

correctedProposedOrder ProposedOrder

Required when foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED".

A new ProposedOrder with corrections. Return this object if there are recoverable errors in the original ProposedOrder. For example, a change in the price of one or more line items in the cart is a recoverable error. Recoverable errors with a valid ProposedOrder are advanced to the confirmation stage, instead of requiring the user to review their cart.

paymentOptions PaymentOptions

Required when foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED".

Default payment options selected for the user.

additionalPaymentOptions List<PaymentOptions>

Alternative payment options available to the user.

The following example shows a FoodErrorExtension element:

Example

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
  "foodOrderErrors": [
    {
      "error": "PRICE_CHANGED",
      "id": "sample_item_offer_id_1",
      "description": "The price has changed.",
      "updatedPrice": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 750000000
      }
    },
    {
      "error": "PRICE_CHANGED",
      "id": "sample_item_offer_id_2",
      "description": "The price has changed.",
      "updatedPrice": {
        "currencyCode": "USD",
        "units": "8"
      }
    }
  ],
  "correctedProposedOrder": {
    "id": "sample_corrected_proposed_order_id_1",
    "otherItems": [
      {
        "name": "New customer discount",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "-5",
            "nanos": -500000000
          }
        },
        "type": "DISCOUNT"
      },
      {
        "name": "Delivery fee",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "3",
            "nanos": 500000000
          }
        },
        "type": "DELIVERY"
      },
      {
        "name": "Tax",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "1",
            "nanos": 500000000
          }
        },
        "type": "TAX"
      }
    ],
    "cart": {
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Falafel Bite"
      },
      "lineItems": [
        {
          "name": "Pita Chips",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        },
        {
          "name": "Chicken Shwarma Wrap",
          "type": "REGULAR",
          "id": "sample_item_offer_id_2",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "8"
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Greek Salad",
          "type": "REGULAR",
          "id": "sample_item_offer_id_3",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "9",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Prawns Biryani",
          "type": "REGULAR",
          "id": "sample_item_offer_id_4",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "15",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          }
        },
        "location": {
          "coordinates": {
            "latitude": 37.788783,
            "longitude": -122.41384
          },
          "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
          "zipCode": "94043",
          "city": "Mountain View",
          "postalAddress": {
            "regionCode": "US",
            "postalCode": "94043",
            "administrativeArea": "CA",
            "locality": "Mountain View",
            "addressLines": [
              "1350 Charleston Road"
            ]
          },
          "notes": "Gate code is #111"
        }
      }
    },
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "36",
        "nanos": 730000000
      }
    },
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ]
    }
  },
  "paymentOptions": {
    "googleProvidedOptions": {
      "tokenizationParameters": {
        "tokenizationType": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "stripe",
          "stripe:publishableKey": "pk_live_stripe_client_key",
          "stripe:version": "2017-04-06"
        }
      },
      "supportedCardNetworks": [
        "AMEX",
        "DISCOVER",
        "MASTERCARD",
        "JCB",
        "VISA"
      ],
      "prepaidCardDisallowed": true
    }
  }
}

FoodItemExtension

Defines add-ons for food items.

The following table lists the properties for the FoodItemExtension type:

Property Type Description
@type Const

Required.

Type of this extension. This field is always set to "type.googleapis.com/google.actions.v2.orders.FoodItemExtension".

Value: type.googleapis.com/google.actions.v2.orders.FoodItemExtension

options List<FoodItemOption>

An option can be an add-on item or add-on group containing a set of add-ons.

The following example shows a FoodItemExtension element:

Example

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
  "options": [
    {
      "id": "sample_addon_offer_id_1",
      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
      "name": "Honey Mustard",
      "price": {
        "currencyCode": "USD"
      },
      "quantity": 1
    },
    {
      "id": "sample_addon_offer_id_2",
      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
      "name": "BBQ Sauce",
      "price": {
        "currencyCode": "USD",
        "nanos": 500000000
      },
      "quantity": 1,
      "subOptions": [
        {
          "id": "10239138",
          "offerId": "912391723",
          "name": "Fries",
          "price": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 230000000
          },
          "quantity": 1
        }
      ]
    }
  ]
}

FoodItemOption

The following table lists the properties for the FoodItemOption type:

Property Type Description
id String

Unique ID assigned by Google. When you send a FoodOrderError or AsyncOrderUpdateRequest, use this field to differentiate in cases where a cart contains more than one item with the same offerId.

Example: 39231093

offerId String

The offer ID for the item.

Example: 912835081

name String

The option name.

Example: Honey Mustard

price Money
note String

Note related to the option.

quantity Number

For options that are items, the number of items.

Example: 3

subOptions List<FoodItemOption>

Sub-options for the option, if any.

Example: [ { "id": "71283712", "offerId": "51209121", "name": "BBQ Sauce", "price": { "currencyCode": "USD", "units": "3", "nanos": 780000000 }, "quantity": 2 }, { "id": "102941024", "offerId": "12084102", "name": "Ketchup", "price": { "currencyCode": "USD", "units": "2", "nanos": 980000000 }, "quantity": 6 } ]

The following example shows a FoodItemOption element:

Example 1

{
  "id": "10293231",
  "offerId": "1918491",
  "name": "Honey Mustard",
  "price": {
    "currencyCode": "USD",
    "units": "1",
    "nanos": 250000000
  },
  "quantity": 5
}

Example 2

{
  "id": "123166552",
  "offerId": "912849184",
  "name": "Make It A Meal",
  "price": {
    "currencyCode": "USD",
    "units": "3",
    "nanos": 730000000
  },
  "quantity": 1,
  "subOptions": [
    {
      "id": "10239138",
      "offerId": "912391723",
      "name": "Fries",
      "price": {
        "currencyCode": "USD",
        "units": "2",
        "nanos": 230000000
      },
      "quantity": 1
    },
    {
      "id": "57159183",
      "offerId": "81837123",
      "name": "Drink",
      "price": {
        "currencyCode": "USD",
        "units": "3",
        "nanos": 130000000
      },
      "quantity": 1
    }
  ]
}

FoodOrderError

Contains details about errors in a CheckoutResponse.

The following table lists the properties for the FoodOrderError type:

Property Type Description
error Error

Required.

id String

Required when error = "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "PRICE_CHANGED", "INVALID", or "NOT_FOUND".

This field is required for item-level errors. It is the Google-assigned LineItem.id for menu items or FoodItemOption.id for add-ons.

description String

Description of the error. This description is for internal logging and is not visible to users.

updatedPrice Money

Required when error = "PRICE_CHANGED".

New price of an item that caused the error. This is required only when error is "PRICE_CHANGED".

availableQuantity Integer

Required when error = "INVALID", or "NOT_FOUND".

New available quantity of the item that caused the error. This is required only when error is "INVALID" or "NOT_FOUND". The value should be zero for "INVALID" and "NOT_FOUND".

The following example shows a FoodOrderError element:

Example 1

{
  "error": "CLOSED",
  "description": "This store is currently reachable. Please try again later."
}

Example 2

{
  "error": "PRICE_CHANGED",
  "id": "french_fries",
  "description": "The price has changed.",
  "updatedPrice": {
    "currencyCode": "USD",
    "units": "2",
    "nanos": 750000000
  }
}

FoodOrderExtension

Contains fulfillment info about the order.

The following table lists the properties for the FoodOrderExtension type:

Property Type Description
@type Const

Type of this extension. This field is always set to "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension".

Value: type.googleapis.com/google.actions.v2.orders.FoodOrderExtension

availableFulfillmentOptions List<FulfillmentOption>

Represents available fulfillment options for the order.

optinForRemarketing Boolean

User request to opt in to your marketing channels. By default, you cannot send marketing content without user consent. If optinForRemarketing is true, you can subscribe the user. If optinForRemarketing is false or not present, you must keep the subscription status in your system as-is. Users cannot opt out through Google, only through an unsubscription function provided in your marketing channels. This flag is only present in SubmitOrderRequestMessage.

The following example shows a FoodOrderExtension element:

Example 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
  "availableFulfillmentOptions": [
    {
      "fulfillmentInfo": {
        "delivery": {
          "deliveryTimeIso8601": "P0M"
        }
      },
      "expiresAt": "2017-07-17T12:30:00Z"
    }
  ]
}

Example 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
  "availableFulfillmentOptions": [
    {
      "fulfillmentInfo": {
        "pickup": {
          "pickupTimeIso8601": "P0M"
        }
      },
      "expiresAt": "2020-08-20T11:41:00Z"
    }
  ],
  "optinForRemarketing": true
}

FulfillmentOption

You can use a FulfillmentOption object in the following ways:
  • In Checkout AppRequest and Submit AppRequest, the Cart.extension.fulfillmentPreference: Stores the user's preference (delivery or pickup). The price is always 0 the when the checkout request is sent.
  • In Checkout AppResponse, the ProposedOrder.extension.availableFulfillmentOptions: Defines one or more delivery options (currently, only one option is supported). You specify the default option as a LineItem in ProposedOrder.otherItems. The offerId of FulfillmentOption should match the ID of the LineItem specified in ProposedOrder.otherItems.

The following table lists the properties for the FulfillmentOption type:

Property Type Description
offerId String

Unique identifier for this fulfillment option, if any.

fulfillmentInfo FulfillmentOptionInfo

Required.

expiresAt ISO Timestamp

Time at which this fulfillment option expires.

price Money

Cost of this option.

The following example shows a FulfillmentOption element:

Example

{
  "offerId": "offer5",
  "fulfillmentInfo": {
    "pickup": {
      "pickupTimeIso8601": "P0M"
    }
  },
  "expiresAt": "2019-05-02T00:00:00-07:00",
  "price": {
    "currencyCode": "USD",
    "units": "5",
    "nanos": 230000000
  }
}

FulfillmentOptionInfo

Defines information related to FulfillmentInfo.

The following table lists the properties for the FulfillmentOptionInfo type:

Property Type Description
Exactly one of the following groups of properties is required.
delivery Group 1 DeliveryInfo

If present, indicates delivery order.

pickup Group 2 PickupInfo

If present, indicates a pickup order.

Image

The following table lists the properties for the Image type:

Property Type Description
sourceUrl String

Required.

URL for the image. At a minimum, the image should be 72x72 pixels. For best results, use an image that is at least 216x216 pixels. The image must be less than 6 MB and 64 megapixels.

LineItem

Defines the contents of a cart (Cart.lineItems) or additional charges for an order (ProposedOrder.otherItems).

The following table lists the properties for the LineItem type:

Property Type Description
id String

Required when type = "REGULAR".

For a LineItem in a Cart (ProposedOrder.cart.lineItems[0].id), this is the unique ID created by Google when creating the order. For a LineItem in a ProposedOrder (ProposedOrder.otherItems[0].id), which is used to add items such as delivery fees and taxes, the value of id is defined by the provider. For example, in a cart there are two of the same items with different preparation instructions (such as two medium pizzas with different sets of toppings). In this case, both items have the same base offerId. When you send an order update request to indicate that an item is rejected, use this ID as the disambiguator. In other words, if one of the pizzas is rejected because it lacks a particular topping, the id helps Google determine which item in the order you are referring to. This field is required except in otherItems.

name String

Required.

Name of the line item. This is a user-visible string, and should be sentence case when possible (like "Delivery fee", "Service charge", "Tax"). This field is truncated at 100 characters for users.

type LineItemType

Required.

quantity Integer

Required when type = "REGULAR".

Number of items included. Not applicable to ProposedOrder.otherItems.

description String

Description of the item.

price Price

Required.

The price of the item or items. This value reflects the total price of all goods or services for this line item (in other words, add the cost of any add-ons and multiply by the quantity). For example: If a $10 item has a quantity of 3, the price would be $30. For one pizza with a base price of $5 and a $1 add-on, the price would be $6. For two pizzas (quantity = 2) with a base price of $5 and each with a $1 add-on, the price would be $12. Each LineItem should have a price, even if the price is "0". When type is DISCOUNT, specify the value as a negative (for example, "-2").

subLines List<SublineNote>

Optional and only valid if type is "REGULAR". An item-specific note from the user may be sent in this field in the checkout request and order submission request. Ensure that the merchant receives the note when it is provided. It will be in the request as subLines[0].note, which is the only value provided in this field when it is present in a request.

Must have no more than 1 item.

offerId String

Required when type = "REGULAR".

The offer ID of the MenuItem for the item. Not applicable to ProposedOrder.otherItems.

extension FoodItemExtension

Defines add-ons for food items.

The following example shows a LineItem element:

Example 1

{
  "name": "New customer discount",
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "-5",
      "nanos": -500000000
    }
  },
  "type": "DISCOUNT"
}

Example 2

{
  "name": "Pita Chips",
  "type": "REGULAR",
  "id": "sample_item_offer_id_1",
  "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
  "quantity": 1,
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "2",
      "nanos": 750000000
    }
  },
  "subLines": [
    {
      "note": "Notes for this item."
    }
  ],
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
    "options": [
      {
        "id": "sample_addon_offer_id_1",
        "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
        "name": "Honey Mustard",
        "price": {
          "currencyCode": "USD"
        },
        "quantity": 1
      },
      {
        "id": "sample_addon_offer_id_2",
        "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
        "name": "BBQ Sauce",
        "price": {
          "currencyCode": "USD",
          "nanos": 500000000
        },
        "quantity": 1
      }
    ]
  }
}

LineItemType

The LineItemType type has the following possible values:

  • REGULAR: Goods line item. Applicable to Cart.lineItems.
  • TAX: Tax line item. Applicable to ProposedOrder.otherItems.
  • DISCOUNT: Discount line item. Note that the price should be negative. Applicable to ProposedOrder.otherItems.
  • GRATUITY: Gratuity line item. Generally reserved for the SubmitOrderRequestMessage for a user-selected tip. Applicable to ProposedOrder.otherItems.
  • DELIVERY: Delivery line item. Applicable to ProposedOrder.otherItems.
  • SUBTOTAL: Subtotal line item. Applicable to ProposedOrder.otherItems.
  • FEE: Additional line item not covered by the other types. Applicable to ProposedOrder.otherItems.

Location

Specifies an address for food ordering. The Location type is used in a Cart to indicate the destination of a delivery order only. The finalized location is also present in TransactionDecisionValue if the user places the order. For orders that specify pickup, a location is not included at all (not even an empty one).

The following table lists the properties for the Location type:

Property Type Description
coordinates Coordinates
formattedAddress String

Display address of the location.

Example: 1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States

postalAddress PostalAddress
zipCode String

Example: 90210

city String

The name of the city.

Example: Los Angeles

notes String

Notes about the location, such as gate codes. It should be 500 characters or less.

Example: Gate code is #111

The following example shows a Location element:

Example

{
  "coordinates": {
    "latitude": 37.788783,
    "longitude": -122.41384
  },
  "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
  "zipCode": "94043",
  "city": "Mountain View",
  "postalAddress": {
    "regionCode": "US",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1350 Charleston Road"
    ]
  },
  "notes": "Gate code is #111"
}

Merchant

The following table lists the properties for the Merchant type:

Property Type Description
id String

The ID of the merchant. If specified, matches with the Restaurant.@id in the Restaurant feed.

Example: https://www.exampleprovider.com/merchant/id1

name String

Required.

User visible name of the merchant.

Example: Falafel Bite

The following example shows a Merchant element:

Example

{
  "id": "https://www.exampleprovider.com/merchant/id1",
  "name": "Falafel Bite"
}

Money

The following table lists the properties for the Money type:

Property Type Description
currencyCode String

Required.

A 3-letter currency code in ISO 4217 format.

Example: USD

units String

The whole units of the amount. For example, if currencyCode is "USD", then "1" unit is one US dollar.

Example: 36

nanos Integer

Number of nano (10^-9) units of the amount. The value must be between -999,999,999 and +999,999,999, inclusive. Use the following rules: If units is positive, nanos must be positive or zero. If units is zero, nanos can be positive, zero, or negative. If units is negative, nanos must be negative or zero. For example $-1.75 is represented as units = -1 and nanos = -750,000,000.

Example: 730000000

The following example shows a Money element:

Example 1

{
  "currencyCode": "USD",
  "units": "36",
  "nanos": 730000000
}

Example 2

{
  "currencyCode": "EUR",
  "units": "10"
}

Order

Contains the final order, including taxes, fees, and delivery charges, as well as payment information. This object is received by your action in a Submit AppRequest.

The following table lists the properties for the Order type:

Property Type Description
finalOrder ProposedOrder

Required.

The proposed order that caused the order.

googleOrderId String

Required.

Order ID assigned by Google. This ID should be stable for the entire life cycle of an order. This ID is not visible to the end user.

orderDate ISO Timestamp

Required.

Date and time the order was created.

paymentInfo PaymentInfo

Required.

Payment information corresponding to payment for this order.

The following example shows a Order element:

Example

{
  "finalOrder": {
    "cart": {
      "notes": "Guest prefers their food to be hot when it is delivered.",
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Cucina Venti"
      },
      "lineItems": [
        {
          "name": "Sizzling Prawns Dinner",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "16",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "pickup": {
              "pickupTimeIso8601": "P0M"
            }
          }
        },
        "contact": {
          "displayName": "Lovefood Ordering",
          "email": "ilovefood@example.com",
          "phoneNumber": "+16501234567"
        }
      }
    },
    "otherItems": [
      {
        "name": "Service fee",
        "type": "FEE",
        "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": "Tip",
        "type": "GRATUITY",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 590000000
          }
        }
      }
    ],
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "23",
        "nanos": 710000000
      }
    },
    "id": "sample_final_order_id",
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "pickup": {
              "pickupTimeIso8601": "P0M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ],
      "optinForRemarketing": true
    }
  },
  "googleOrderId": "sample_google_order_id",
  "orderDate": "2017-07-17T12:00:00Z",
  "paymentInfo": {
    "displayName": "Visa\u2006****\u20061111",
    "googleProvidedPaymentInstrument": {
      "instrumentToken": "abcd"
    },
    "paymentType": "PAYMENT_CARD"
  }
}

OrderUpdate

The following table describes the fields of the OrderUpdate type which is included in AppResponse.

The following table lists the properties for the OrderUpdate type:

Property Type Description
actionOrderId String

Required.

Unique ID of the order in the integrator's system that is used to identify the order for which the update is sent. If receipt.user_visible_order_id is not provided at least once in OrderUpdate for a "CREATED" order, this ID will be the inputed user visible ID displayed in the Google order card.

orderState OrderState

Required.

The new state of the order.

lineItemUpdates Map<String, LineItemUpdate>
updateTime ISO Timestamp

Required.

The time at which the order was updated.

orderManagementActions List<OrderManagementAction>

Post-order actions such as contacting support and viewing order details.

Must have no fewer than 1 item and no more than 6 items.

rejectionInfo RejectionInfo

Required when orderState.state = "REJECTED".

cancellationInfo CancellationInfo

Required when orderState.state = "CANCELLED".

inTransitInfo InTransitInfo

This field is deprecated.

fulfillmentInfo FulfillmentInfo

This field is deprecated.

receipt Receipt

Required when orderState.state = "CONFIRMED", "IN_PREPARATION", or "READY_FOR_PICKUP".

Provide the user-visible order ID in a receipt.

totalPrice Price

Total price of the order.

infoExtension FoodOrderUpdateExtension

Defines more details of the order update, such as the interval for estimated delivery or pickup.

The following example shows a OrderUpdate element:

Example

{
  "actionOrderId": "sample_action_order_id",
  "orderState": {
    "state": "CONFIRMED",
    "label": "Provider confirmed"
  },
  "totalPrice": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "41",
      "nanos": 600000000
    }
  },
  "lineItemUpdates": {
    "sample_item_id_1": {
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "3",
          "nanos": 500000000
        }
      },
      "reason": "This item has an updated price."
    }
  },
  "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"
        }
      }
    }
  ],
  "infoExtension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
    "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
  }
}

PickupInfo

The following table lists the properties for the PickupInfo type:

Property Type Description
pickupTimeIso8601 String

Estimated pickup time, in ISO 8601 time stamp format: "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" or duration format: "P(n)Y(n)M(n)DT(n)H(n)M(n)S". For instance, PT90M represents a duration of 90 minutes. The default value ,"PT0M", indicates that the preferred pickup time is as soon as possible. Reference: https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. Use this to update the estimated pickup time during checkout response.

Example: PT90M

The following example shows a PickupInfo element:

Example

{
  "pickupTimeIso8601": "PT90M"
}

PostalAddress

The following table lists the properties for the PostalAddress type:

Property Type Description
regionCode String

Required.

A two-letter country code.

Example: US

postalCode String

The postal code.

Example: 94043

administrativeArea String

Highest administrative subdivision which is used for postal addresses of a country or region. This can be a state, a province, an oblast, or a prefecture.

Example: CA

locality String

The city or town for this location. In regions of the world where localities are not well defined or do not fit into this structure, do not specify locality and use the addressLines field instead.

Example: Mountain View

addressLines List<String>

One or more lines that you can use to specify the street address. This field shouldn't be modified because it can contain unclear localities.

Example: [ "1350 Charleston Road" ]

recipients List<String>

List of the recipients for an order. This field is only available in billingAddress.

The following example shows a PostalAddress element:

Example

{
  "regionCode": "US",
  "postalCode": "94043",
  "administrativeArea": "CA",
  "locality": "Mountain View",
  "addressLines": [
    "1350 Charleston Road"
  ]
}

Price

The following table lists the properties for the Price type:

Property Type Description
type Enum [ "ESTIMATE", "ACTUAL" ]

Required.

The promotion coupon code.

amount Money

Required.

Promotion

The following table lists the properties for the Promotion type:

Property Type Description
coupon String

Required.

The promotion coupon code.

ProposedOrder

The following table lists the properties for the ProposedOrder type:

Property Type Description
id String

Optional ID for the proposed order.

cart Cart

Required.

User's items.

otherItems List<LineItem>

Items added by the provider, such as delivery charges, other fees, and taxes. otherItems may also contain gratuity and/or discount added by the user.

Must have no more than 10 items.

image Image

Image associated with the proposed order.

totalPrice Price

Required.

Total price of the proposed order.

extension FoodOrderExtension

Required.

Defines fulfillment information for food orders.

disclaimers List<Disclaimer>

Corresponds to disclaimer messages that will be shown in the UI prior to order being placed.

The following example shows a ProposedOrder element:

Example

{
  "id": "sample_proposed_order_id_1",
  "otherItems": [
    {
      "name": "New customer discount",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "-5",
          "nanos": -500000000
        }
      },
      "type": "DISCOUNT"
    },
    {
      "name": "Delivery fee",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "3",
          "nanos": 500000000
        }
      },
      "type": "DELIVERY"
    },
    {
      "name": "Tax",
      "price": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "1",
          "nanos": 500000000
        }
      },
      "type": "TAX"
    }
  ],
  "cart": {
    "merchant": {
      "id": "https://www.exampleprovider.com/merchant/id1",
      "name": "Falafel Bite"
    },
    "lineItems": [
      {
        "name": "Pita Chips",
        "type": "REGULAR",
        "id": "sample_item_offer_id_1",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "2",
            "nanos": 750000000
          }
        },
        "subLines": [
          {
            "note": "Notes for this item."
          }
        ],
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
          "options": [
            {
              "id": "sample_addon_offer_id_1",
              "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
              "name": "Honey Mustard",
              "price": {
                "currencyCode": "USD"
              },
              "quantity": 1
            },
            {
              "id": "sample_addon_offer_id_2",
              "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
              "name": "BBQ Sauce",
              "price": {
                "currencyCode": "USD",
                "nanos": 500000000
              },
              "quantity": 1
            }
          ]
        }
      },
      {
        "name": "Chicken Shwarma Wrap",
        "type": "REGULAR",
        "id": "sample_item_offer_id_2",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "8"
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      },
      {
        "name": "Greek Salad",
        "type": "REGULAR",
        "id": "sample_item_offer_id_3",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "9",
            "nanos": 990000000
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      },
      {
        "name": "Prawns Biryani",
        "type": "REGULAR",
        "id": "sample_item_offer_id_4",
        "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
        "quantity": 1,
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "15",
            "nanos": 990000000
          }
        },
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
        }
      }
    ],
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
      "fulfillmentPreference": {
        "fulfillmentInfo": {
          "delivery": {
            "deliveryTimeIso8601": "P90M"
          }
        }
      },
      "location": {
        "coordinates": {
          "latitude": 37.788783,
          "longitude": -122.41384
        },
        "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
        "zipCode": "94043",
        "city": "Mountain View",
        "postalAddress": {
          "regionCode": "US",
          "postalCode": "94043",
          "administrativeArea": "CA",
          "locality": "Mountain View",
          "addressLines": [
            "1350 Charleston Road"
          ]
        },
        "notes": "Gate code is #111"
      }
    }
  },
  "totalPrice": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "36",
      "nanos": 730000000
    }
  },
  "extension": {
    "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
    "availableFulfillmentOptions": [
      {
        "fulfillmentInfo": {
          "delivery": {
            "deliveryTimeIso8601": "P0M"
          }
        },
        "expiresAt": "2017-07-17T12:30:00Z"
      }
    ]
  }
}

SublineNote

The following table lists the properties for the SublineNote type:

Property Type Description
note String

Required.

Timestamp

The date and time, in the following format: "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"

TransactionDecisionValue

Contains the Order.

The following table lists the properties for the TransactionDecisionValue type:

Property Type Description
order Order

Required.

Order to be placed with payment details.

The following example shows a TransactionDecisionValue element:

Example

{
  "order": {
    "finalOrder": {
      "cart": {
        "notes": "Guest prefers their food to be hot when it is delivered.",
        "merchant": {
          "id": "https://www.exampleprovider.com/merchant/id1",
          "name": "Cucina Venti"
        },
        "lineItems": [
          {
            "name": "Sizzling Prawns Dinner",
            "type": "REGULAR",
            "id": "sample_item_offer_id_1",
            "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
            "quantity": 1,
            "price": {
              "type": "ESTIMATE",
              "amount": {
                "currencyCode": "USD",
                "units": "16",
                "nanos": 750000000
              }
            },
            "subLines": [
              {
                "note": "Notes for this item."
              }
            ],
            "extension": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
              "options": [
                {
                  "id": "sample_addon_offer_id_1",
                  "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                  "name": "Honey Mustard",
                  "price": {
                    "currencyCode": "USD"
                  },
                  "quantity": 1
                },
                {
                  "id": "sample_addon_offer_id_2",
                  "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                  "name": "BBQ Sauce",
                  "price": {
                    "currencyCode": "USD",
                    "nanos": 500000000
                  },
                  "quantity": 1
                }
              ]
            }
          }
        ],
        "extension": {
          "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
          "fulfillmentPreference": {
            "fulfillmentInfo": {
              "pickup": {
                "pickupTimeIso8601": "P0M"
              }
            }
          },
          "contact": {
            "displayName": "Lovefood Ordering",
            "email": "ilovefood@example.com",
            "phoneNumber": "+16501234567"
          }
        }
      },
      "otherItems": [
        {
          "name": "Service fee",
          "type": "FEE",
          "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": "Tip",
          "type": "GRATUITY",
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 590000000
            }
          }
        }
      ],
      "totalPrice": {
        "type": "ESTIMATE",
        "amount": {
          "currencyCode": "USD",
          "units": "23",
          "nanos": 710000000
        }
      },
      "id": "sample_final_order_id",
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
        "availableFulfillmentOptions": [
          {
            "fulfillmentInfo": {
              "pickup": {
                "pickupTimeIso8601": "P0M"
              }
            },
            "expiresAt": "2017-07-17T12:30:00Z"
          }
        ],
        "optinForRemarketing": true
      }
    },
    "googleOrderId": "sample_google_order_id",
    "orderDate": "2017-07-17T12:00:00Z",
    "paymentInfo": {
      "displayName": "Visa\u2006****\u20061111",
      "googleProvidedPaymentInstrument": {
        "instrumentToken": "abcd"
      },
      "paymentType": "PAYMENT_CARD"
    }
  }
}

Fulfillment Request

AppRequest

The following table lists the properties for the AppRequest type:

Property Type Description
isInSandbox Boolean

Indicates whether the subsequent transactions are done in a sandbox environment.

conversation Conversation
inputs List<Input>

Required.

Contains the expected arguments for checking out a cart.

Must have exactly 1 item.

The following example shows a AppRequest element:

Example 1

{
  "isInSandbox": true,
  "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": "Cucina Venti"
            },
            "lineItems": [
              {
                "name": "Sizzling Prawns Dinner",
                "type": "REGULAR",
                "id": "sample_item_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                "quantity": 1,
                "price": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "16",
                    "nanos": 750000000
                  }
                },
                "subLines": [
                  {
                    "note": "Notes for this item."
                  }
                ],
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                  "options": [
                    {
                      "id": "sample_addon_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                      "name": "Honey Mustard",
                      "price": {
                        "currencyCode": "USD"
                      },
                      "quantity": 1
                    },
                    {
                      "id": "sample_addon_offer_id_2",
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                      "name": "BBQ Sauce",
                      "price": {
                        "currencyCode": "USD",
                        "nanos": 500000000
                      },
                      "quantity": 1
                    }
                  ]
                }
              }
            ],
            "extension": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
              "fulfillmentPreference": {
                "fulfillmentInfo": {
                  "delivery": {
                    "deliveryTimeIso8601": "P0M"
                  }
                }
              },
              "location": {
                "coordinates": {
                  "latitude": 37.788783,
                  "longitude": -122.41384
                },
                "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
                "zipCode": "94043",
                "city": "Mountain View",
                "postalAddress": {
                  "regionCode": "US",
                  "postalCode": "94043",
                  "administrativeArea": "CA",
                  "locality": "Mountain View",
                  "addressLines": [
                    "1350 Charleston Road"
                  ]
                },
                "notes": "Gate code is #111"
              }
            }
          }
        }
      ]
    }
  ]
}

Example 2

{
  "isInSandbox": true,
  "inputs": [
    {
      "intent": "actions.intent.TRANSACTION_DECISION",
      "arguments": [
        {
          "transactionDecisionValue": {
            "order": {
              "finalOrder": {
                "cart": {
                  "notes": "Guest prefers their food to be hot when it is delivered.",
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Cucina Venti"
                  },
                  "lineItems": [
                    {
                      "name": "Sizzling Prawns Dinner",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "16",
                          "nanos": 750000000
                        }
                      },
                      "subLines": [
                        {
                          "note": "Notes for this item."
                        }
                      ],
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                        "options": [
                          {
                            "id": "sample_addon_offer_id_1",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                            "name": "Honey Mustard",
                            "price": {
                              "currencyCode": "USD"
                            },
                            "quantity": 1
                          },
                          {
                            "id": "sample_addon_offer_id_2",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                            "name": "BBQ Sauce",
                            "price": {
                              "currencyCode": "USD",
                              "nanos": 500000000
                            },
                            "quantity": 1
                          }
                        ]
                      }
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    },
                    "contact": {
                      "displayName": "Lovefood Ordering",
                      "email": "ilovefood@example.com",
                      "phoneNumber": "+16501234567"
                    }
                  }
                },
                "otherItems": [
                  {
                    "name": "Service fee",
                    "type": "FEE",
                    "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": "Tip",
                    "type": "GRATUITY",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "2",
                        "nanos": 590000000
                      }
                    }
                  }
                ],
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "23",
                    "nanos": 710000000
                  }
                },
                "id": "sample_final_order_id",
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2017-07-17T12:30:00Z"
                    }
                  ],
                  "optinForRemarketing": true
                }
              },
              "googleOrderId": "sample_google_order_id",
              "orderDate": "2017-07-17T12:00:00Z",
              "paymentInfo": {
                "displayName": "Visa\u2006****\u20061111",
                "googleProvidedPaymentInstrument": {
                  "instrumentToken": "abcd"
                },
                "paymentType": "PAYMENT_CARD"
              }
            }
          }
        }
      ]
    }
  ]
}

CheckoutRequestMessage

A CheckoutRequestMessage is an AppRequest with the actions.foodordering.intent.CHECKOUT intent.

SubmitOrderRequestMessage

A SubmitOrderRequestMessage is an AppRequest with the actions.foodordering.intent.TRANSACTION_DECISION intent.

Conversation

A Conversation is unique to one session only. You can use it to link multiple Checkout and SubmitOrder Actions together if needed.

The following table lists the properties for the Conversation type:

Property Type Description
conversationId String

Required.

Unique ID for the conversation.

The following example shows a Conversation element:

Example

{
  "conversationId": "CQnJ7Z4i7UmvEZ9ph3AxyZRJ"
}

Input

The expected arguments for checking out a cart.

The following table lists the properties for the Input type:

Property Type Description
intent Enum [ "actions.foodordering.intent.CHECKOUT", "actions.intent.TRANSACTION_DECISION" ]

Required.

Set to "actions.foodordering.intent.CHECKOUT" for checkout request message OR "actions.intent.TRANSACTION_DECISION" for submit order request message.

arguments List<Argument>

Required.

Contains the Cart to be checked out or the order to be placed

Must have exactly 1 item.

Argument

Contains details about the food items that the user wants to check out. For checkout, only extension is applicable. For submit order, only transactionDecisionValue is applicable

The following table lists the properties for the Argument type:

Property Type Description
Exactly one of the following groups of properties is required.
extension Group 1 Cart

Details the food items that the user wants to check out.

transactionDecisionValue Group 2 TransactionDecisionValue

Contains the order to be placed along with payment details.

Fulfillment Response

AppResponse

The following table lists the properties for the AppResponse type:

Property Type Description
expectUserResponse Const

Set to false.

Value: False

finalResponse FinalResponse

Required.

Contains your response to the cart checkout.

The following example shows a AppResponse element:

Example 1

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "checkoutResponse": {
              "proposedOrder": {
                "id": "sample_proposed_order_id_1",
                "otherItems": [
                  {
                    "name": "New customer discount",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5",
                        "nanos": -500000000
                      }
                    },
                    "type": "DISCOUNT"
                  },
                  {
                    "name": "Delivery fee",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    },
                    "type": "DELIVERY"
                  },
                  {
                    "name": "Tax",
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 500000000
                      }
                    },
                    "type": "TAX"
                  }
                ],
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Pita Chips",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "2",
                          "nanos": 750000000
                        }
                      },
                      "subLines": [
                        {
                          "note": "Notes for this item."
                        }
                      ],
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
                        "options": [
                          {
                            "id": "sample_addon_offer_id_1",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                            "name": "Honey Mustard",
                            "price": {
                              "currencyCode": "USD"
                            },
                            "quantity": 1
                          },
                          {
                            "id": "sample_addon_offer_id_2",
                            "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                            "name": "BBQ Sauce",
                            "price": {
                              "currencyCode": "USD",
                              "nanos": 500000000
                            },
                            "quantity": 1
                          }
                        ]
                      }
                    },
                    {
                      "name": "Chicken Shwarma Wrap",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_2",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "8"
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    },
                    {
                      "name": "Greek Salad",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_3",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "9",
                          "nanos": 990000000
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    },
                    {
                      "name": "Prawns Biryani",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_4",
                      "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "15",
                          "nanos": 990000000
                        }
                      },
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "delivery": {
                          "deliveryTimeIso8601": "P90M"
                        }
                      }
                    },
                    "location": {
                      "coordinates": {
                        "latitude": 37.788783,
                        "longitude": -122.41384
                      },
                      "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
                      "zipCode": "94043",
                      "city": "Mountain View",
                      "postalAddress": {
                        "regionCode": "US",
                        "postalCode": "94043",
                        "administrativeArea": "CA",
                        "locality": "Mountain View",
                        "addressLines": [
                          "1350 Charleston Road"
                        ]
                      },
                      "notes": "Gate code is #111"
                    }
                  }
                },
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "36",
                    "nanos": 730000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "delivery": {
                          "deliveryTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2017-07-17T12:30:00Z"
                    }
                  ]
                }
              },
              "paymentOptions": {
                "googleProvidedOptions": {
                  "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
                }
              },
              "additionalPaymentOptions": [
                {
                  "actionProvidedOptions": {
                    "paymentType": "ON_FULFILLMENT",
                    "displayName": "Cash on delivery."
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Example 2

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "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": "CUSTOMER_SERVICE",
                  "button": {
                    "title": "Call customer service",
                    "openUrlAction": {
                      "url": "tel:+18005554679"
                    }
                  }
                },
                {
                  "type": "EMAIL",
                  "button": {
                    "title": "Email restaurant",
                    "openUrlAction": {
                      "url": "mailto:person@example.com"
                    }
                  }
                },
                {
                  "type": "CALL_RESTAURANT",
                  "button": {
                    "title": "Call restaurant",
                    "openUrlAction": {
                      "url": "tel:+16505554679"
                    }
                  }
                }
              ],
              "infoExtension": {
                "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
                "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
              }
            }
          }
        }
      ]
    }
  }
}

Example 3

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "error": {
              "@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
              "foodOrderErrors": [
                {
                  "error": "CLOSED",
                  "description": "The restaurant is closed."
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Example 4

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "structuredResponse": {
            "checkoutResponse": {
              "proposedOrder": {
                "otherItems": [
                  {
                    "name": "Delivery Fees",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "3",
                        "nanos": 500000000
                      }
                    },
                    "type": "DELIVERY"
                  },
                  {
                    "name": "Tax",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "1",
                        "nanos": 370000000
                      }
                    },
                    "type": "TAX"
                  },
                  {
                    "name": "Promotion",
                    "subLines": [],
                    "price": {
                      "type": "ESTIMATE",
                      "amount": {
                        "currencyCode": "USD",
                        "units": "-5",
                        "nanos": 0
                      }
                    },
                    "id": "OWG_ACTIVE_CODE",
                    "type": "DISCOUNT"
                  }
                ],
                "cart": {
                  "merchant": {
                    "id": "https://www.exampleprovider.com/merchant/id1",
                    "name": "Falafel Bite"
                  },
                  "lineItems": [
                    {
                      "name": "Pita Chips",
                      "type": "REGULAR",
                      "id": "sample_item_offer_id_1",
                      "quantity": 1,
                      "price": {
                        "type": "ESTIMATE",
                        "amount": {
                          "currencyCode": "USD",
                          "units": "2",
                          "nanos": 750000000
                        }
                      },
                      "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                      "extension": {
                        "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
                      }
                    }
                  ],
                  "promotions": [
                    {
                      "coupon": "OWG_ACTIVE_CODE"
                    }
                  ],
                  "extension": {
                    "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
                    "fulfillmentPreference": {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      }
                    }
                  }
                },
                "totalPrice": {
                  "type": "ESTIMATE",
                  "amount": {
                    "currencyCode": "USD",
                    "units": "14",
                    "nanos": 860000000
                  }
                },
                "extension": {
                  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
                  "availableFulfillmentOptions": [
                    {
                      "fulfillmentInfo": {
                        "pickup": {
                          "pickupTimeIso8601": "P0M"
                        }
                      },
                      "expiresAt": "2018-04-10T01:20:08.471Z"
                    }
                  ]
                }
              },
              "paymentOptions": {
                "googleProvidedOptions": {
                  "tokenizationParameters": {
                    "tokenizationType": "PAYMENT_GATEWAY",
                    "parameters": {
                      "gateway": "stripe",
                      "stripe:publishableKey": "pk_live_stripe_client_key",
                      "stripe:version": "2017-04-06"
                    }
                  },
                  "supportedCardNetworks": [
                    "AMEX",
                    "DISCOVER",
                    "MASTERCARD",
                    "VISA",
                    "JCB"
                  ],
                  "prepaidCardDisallowed": true,
                  "billingAddressRequired": true
                }
              }
            }
          }
        }
      ]
    }
  }
}

CheckoutResponseMessage

A CheckoutResponseMessage is an AppResponse with a checkoutResponse or error in the StructuredResponse.

SubmitOrderResponseMessage

A SubmitOrderResponseMessage is an AppResponse with an orderUpdate in the StructuredResponse.

FinalResponse

Your response to the cart checkout or SubmitOrderRequestMessage.

The following table lists the properties for the FinalResponse type:

Property Type Description
richResponse RichResponse

Required.

Contains your response to the CheckoutRequestMessage or SubmitOrderRequestMessage.

CheckoutResponse

The following table lists the properties for the CheckoutResponse type:

Property Type Description
proposedOrder ProposedOrder

Required.

Proposed order to use for the transaction.

paymentOptions PaymentOptions

Required.

Default payment option selected for the user.

additionalPaymentOptions List<PaymentOptions>

Alternative payment options available to the user.

The following example shows a CheckoutResponse element:

Example

{
  "proposedOrder": {
    "id": "sample_proposed_order_id_1",
    "otherItems": [
      {
        "name": "New customer discount",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "-5",
            "nanos": -500000000
          }
        },
        "type": "DISCOUNT"
      },
      {
        "name": "Delivery fee",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "3",
            "nanos": 500000000
          }
        },
        "type": "DELIVERY"
      },
      {
        "name": "Tax",
        "price": {
          "type": "ESTIMATE",
          "amount": {
            "currencyCode": "USD",
            "units": "1",
            "nanos": 500000000
          }
        },
        "type": "TAX"
      }
    ],
    "cart": {
      "merchant": {
        "id": "https://www.exampleprovider.com/merchant/id1",
        "name": "Falafel Bite"
      },
      "lineItems": [
        {
          "name": "Pita Chips",
          "type": "REGULAR",
          "id": "sample_item_offer_id_1",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "2",
              "nanos": 750000000
            }
          },
          "subLines": [
            {
              "note": "Notes for this item."
            }
          ],
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
            "options": [
              {
                "id": "sample_addon_offer_id_1",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
                "name": "Honey Mustard",
                "price": {
                  "currencyCode": "USD"
                },
                "quantity": 1
              },
              {
                "id": "sample_addon_offer_id_2",
                "offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
                "name": "BBQ Sauce",
                "price": {
                  "currencyCode": "USD",
                  "nanos": 500000000
                },
                "quantity": 1
              }
            ]
          }
        },
        {
          "name": "Chicken Shwarma Wrap",
          "type": "REGULAR",
          "id": "sample_item_offer_id_2",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "8"
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Greek Salad",
          "type": "REGULAR",
          "id": "sample_item_offer_id_3",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "9",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        },
        {
          "name": "Prawns Biryani",
          "type": "REGULAR",
          "id": "sample_item_offer_id_4",
          "offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
          "quantity": 1,
          "price": {
            "type": "ESTIMATE",
            "amount": {
              "currencyCode": "USD",
              "units": "15",
              "nanos": 990000000
            }
          },
          "extension": {
            "@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
          }
        }
      ],
      "extension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
        "fulfillmentPreference": {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P90M"
            }
          }
        },
        "location": {
          "coordinates": {
            "latitude": 37.788783,
            "longitude": -122.41384
          },
          "formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
          "zipCode": "94043",
          "city": "Mountain View",
          "postalAddress": {
            "regionCode": "US",
            "postalCode": "94043",
            "administrativeArea": "CA",
            "locality": "Mountain View",
            "addressLines": [
              "1350 Charleston Road"
            ]
          },
          "notes": "Gate code is #111"
        }
      }
    },
    "totalPrice": {
      "type": "ESTIMATE",
      "amount": {
        "currencyCode": "USD",
        "units": "36",
        "nanos": 730000000
      }
    },
    "extension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
      "availableFulfillmentOptions": [
        {
          "fulfillmentInfo": {
            "delivery": {
              "deliveryTimeIso8601": "P0M"
            }
          },
          "expiresAt": "2017-07-17T12:30:00Z"
        }
      ]
    }
  },
  "paymentOptions": {
    "googleProvidedOptions": {
      "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
    }
  },
  "additionalPaymentOptions": [
    {
      "actionProvidedOptions": {
        "paymentType": "ON_FULFILLMENT",
        "displayName": "Cash on delivery."
      }
    }
  ]
}

Item

Contains your response to a cart checkout or SubmitOrderRequestMessage.

The following table lists the properties for the Item type:

Property Type Description
structuredResponse StructuredResponse

Required.

RichResponse

Contains your response to a cart checkout.

The following table lists the properties for the RichResponse type:

Property Type Description
items List<Item>

Required.

Must have exactly 1 item.

StructuredResponse

For CheckoutResponseMessage, this can be one of the following: CheckoutResponse Indicates a successful checkout. OR FoodErrorExtension: Indicates a failure during checkout. The response can included a corrected ProposedOrder and PaymentOptions or an error message with no PaymentOptions. For SubmitOrderResponseMessage, only orderUpdate is applicable.

The following table lists the properties for the StructuredResponse type:

Property Type Description
Exactly one of the following groups of properties is required.
checkoutResponse Group 1 CheckoutResponse

Checked out items plus taxes and discounts.

error Group 2 FoodErrorExtension

Errors observed in the cart items. Depending on the nature of the error, this property can include a corrected ProposedOrder and PaymentOptions, or just an error message with no PaymentOptions.

orderUpdate Group 3 OrderUpdate

Asynchronous order updates

This section describes the high-level types that make up the requests and responses of a typical food ordering built-in action interaction.

AsyncOrderUpdateRequestMessage

Notifies the user of changes, after an order has been submitted and confirmed. For example, you can notify the user that the order is in transit or if the price has changed. For more information, see

The following table lists the properties for the AsyncOrderUpdateRequestMessage type:

Property Type Description
isInSandbox Boolean

Indicates that the order for which this update was sent is a sandbox payment.

customPushMessage CustomPushMessage

Required.

Contains the OrderUpdate for the request.

The following example shows a AsyncOrderUpdateRequestMessage element:

Example

{
  "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",
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "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"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
      }
    }
  }
}

AsyncOrderUpdateResponseMessage

After you successfully send an AsyncOrderUpdateRequestMessage, Google responds with an HTTP 200 status and an empty body. If the update was unsuccessful, Google responds with details about why the order update failed.

Order update types

Button

Defines a user interface element that you can add to provide user interaction.

The following table lists the properties for the Button type:

Property Type Description
title String

Required.

The display label. Use sentence case with 30 characters or less to ensure proper rendering.

Example: Contact us

openUrlAction OpenUrlAction

Required.

The following example shows a Button element:

Example

{
  "title": "Send us feedback",
  "openUrlAction": {
    "url": "mailto:person@example.com"
  }
}

CancellationInfo

The following table lists the properties for the CancellationInfo type:

Property Type Description
reason String

Required.

Displayable text reason for the rejection when OrderState.state is "CANCELLED".

Example: Restaurant closed

The following example shows a CancellationInfo element:

Example

{
  "reason": "Insufficient inventory"
}

FoodOrderUpdateExtension

This type provides a user with an estimated interval for when the order will be delivered or ready for pickup. Send this extension in an OrderUpdate whenever the information is available or has changed since it was last sent.

Provide a conservative estimate for the fulfillment interval so that user expectations are consistently met. For example, if the order is estimated to be delivered today at 13:00, you should send an estimated interval that is consistent with the variations due to traffic conditions, such as today at 12:45 to 13:15.

An ISO 8601 duration or timestamp is interpreted to mean the interval from the updateTime of the OrderUpdate (in essence, "now") to the updateTime plus duration. Don't use this format unless "now" is actually a reasonable expectation.

An ISO 8601 interval is interpreted to mean the interval from the start to the end of the interval.

The following table lists the properties for the FoodOrderUpdateExtension type:

Property Type Description
@type Const

Type of this extension. This field is always set to "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension".

Value: type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension

estimatedFulfillmentTimeIso8601 String

The estimated time when the order will be delivered or be ready for pickup. The string must be in ISO 8601 format and must correspond to an interval rather than a single fixed time. Acceptable conventions are: Intervals, Durations, and Dates/Times. This field can be sent in SubmitOrderResponseMessage, or AsyncOrderUpdateRequestMessage when the information becomes available or there is a change, such as early or delayed arrivals.

Example: 2017-07-17T13:00:00Z/2017-07-17T13:30:00Z

foodOrderErrors List<FoodOrderError>

Describes the errors that occurred post-order. Recommended one error per cart or per item. Use FoodOrderUpdateExtension.FoodOrderErrors for any errors not covered by RejectionInfo.

Must have no fewer than 1 item.

The following example shows a FoodOrderUpdateExtension element:

Example 1

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
  "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}

Example 2

{
  "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
  "foodOrderErrors": [
    {
      "error": "NO_CAPACITY",
      "description": "Sorry, the restaurant cannot take your order right now."
    }
  ]
}

FulfillmentInfo

The following table lists the properties for the FulfillmentInfo type:

Property Type Description
Exactly one of the following groups of properties is required.
deliveryTime Group 1 ISO Timestamp

Use estimatedFulfillmentTimeIso8601 in FoodOrderingUpdateExtension message

pickupTime Group 2 ISO Timestamp

Use estimatedFulfillmentTimeIso8601 in FoodOrderingUpdateExtension message

The following example shows a FulfillmentInfo element:

Example 1

{
  "deliveryTime": "2017-05-10T02:36:38.803Z"
}

Example 2

{
  "pickupTime": "2019-12-26T07:24:27.803Z"
}

InTransitInfo

The following table lists the properties for the InTransitInfo type:

Property Type Description
updatedTime ISO Timestamp

Use estimatedFulfillmentTimeIso8601 in FoodOrderingUpdateExtension message

The following example shows a InTransitInfo element:

Example

{
  "updatedTime": "2017-05-10T02:36:38.803Z"
}

LineItemUpdate

The following table lists the properties for the LineItemUpdate type:

Property Type Description
orderState OrderState
price Price
reason String

Reason for the change. Required for price changes.

The following example shows a LineItemUpdate element:

Example

{
  "orderState": {
    "state": "CONFIRMED",
    "label": "Provider confirmed"
  },
  "price": {
    "type": "ESTIMATE",
    "amount": {
      "currencyCode": "USD",
      "units": "5",
      "nanos": 500000000
    }
  },
  "reason": "Menu updated prices."
}

OpenUrlAction

The following table lists the properties for the OpenUrlAction type:

Property Type Description
url String

Required.

The action triggered by clicking or touching the button. The list of applicable prefixes depends on orderManagementActionType. "EMAIL": The prefix must be "mailto". "CALL": The prefix must be "tel". "CUSTOMER_SERVICE": The prefix must be "mailto", "tel", "http", or "https".

Example: https://www.google.com

OrderManagementAction

Order management enables users to get post-order support and should be sent in each OrderUpdate within the submit order AppResponse and each subsequent AsyncOrderUpdateRequestMessage Order management actions sent for a particular order can vary based on the state.

For example, in the "CREATED" state, CUSTOMER_SERVICE might reference your customer support telephone. Then, in the "CONFIRMED" state, CUSTOMER_SERVICE can change to the restaurant's telephone if that becomes the best point of contact for the customer. Similarly, once the order is in the "FULFILLED" state, CUSTOMER_SERVICE can reference your support email addresss.

The following table lists the properties for the OrderManagementAction type:

Property Type Description
type OrderManagementActionType

Required.

button Button

Required.

The following example shows a OrderManagementAction element:

Example 1

{
  "type": "CUSTOMER_SERVICE",
  "button": {
    "title": "Contact customer service",
    "openUrlAction": {
      "url": "mailto:support@example.com"
    }
  }
}

Example 2

{
  "type": "EMAIL",
  "button": {
    "title": "Email restaurant",
    "openUrlAction": {
      "url": "mailto:person@example.com"
    }
  }
}

OrderManagementActionType

Defines types related to OrderManagementAction.

The OrderManagementActionType type has the following possible values:

  • CUSTOMER_SERVICE: Email and/or contact number of customer service to be shown on order confirmation page. This is required. openUrlAction.url prefix must be "mailto", "tel", "http", or "https".
  • EMAIL: Email action on order details page only. openUrlAction.url prefix must be "mailto".
  • CALL_DRIVER: Call action on order details page only. openUrlAction.url prefix must be "tel".
  • CALL_RESTAURANT: Call action on order details page only. openUrlAction.url prefix must be "tel".

OrderState

The current state of the order. Each state value of OrderState also corresponds to a purchase status on myaccount.google.com.

The following table lists the properties for the OrderState type:

Property Type Description
state OrderStateEnum

Required.

label String

Required.

The user-visible display string for the state. Use sentence case.

Example: Your order has been received

The following example shows a OrderState element:

Example

{
  "state": "CONFIRMED",
  "label": "Provider confirmed"
}

OrderStateEnum

Defines types related to OrderState.

The OrderStateEnum type has the following possible values:

  • CREATED: Order created by integrator and waiting for confirmation by provider. Corresponds to the "Ordered" purchase status.
  • CONFIRMED: Order confirmed by provider and is active. Corresponds to the "Accepted" purchase status.
  • REJECTED: Order rejected by integrator or provider. Corresponds to the "Declined" purchase status.
  • CANCELLED: User cancelled the order. Corresponds to the "Cancelled" purchase status.
  • IN_PREPARATION: Food is being prepared. Corresponds to the "Status unknown" purchase status.
  • READY_FOR_PICKUP: Food is ready for pickup. Corresponds to the "Ready for pickup" purchase status.
  • IN_TRANSIT: Order is being delivered. Corresponds to the "In progress" purchase status.
  • FULFILLED: User received what was ordered. Corresponds to the "Picked up" purchase status.

Receipt

Send this type in a submit order AppResponse, where OrderState is "CONFIRMED", "FULFILLED", or "IN_TRANSIT". Send receipt at the time when the userVisibleOrderId becomes available. You don't need to keep sending the receipt in subsequent updates.

The following table lists the properties for the Receipt type:

Property Type Description
userVisibleOrderId String

Required.

Required if the order is "CONFIRMED", "IN_TRANSIT", or "FULFILLED". This field is the single user-facing ID for this order (usually the restaurant's order ID), displayed in both the integrator's receipt and the Google order card. The user must be able to use this ID to reference their order for customer service with the provider and integrator. You only need to provide this ID one time in any given OrderUpdate. Until it is provided, the actionOrderId is the userVisibleOrderId. For example, you may not have a userVisibleOrderId until the order is confirmed by the restaurant. Once confirmed, you must then send an AsyncOrderUpdateRequestMessage with an OrderUpdate and a Receipt.

The following example shows a Receipt element:

Example

{
  "userVisibleOrderId": "userVisibleId1234"
}

RejectionInfo

The following table lists the properties for the RejectionInfo type:

Property Type Description
type RejectionType

Required.

reason String

Reason for the rejection used for internal logging. This field is not visible to users.

The following example shows a RejectionInfo element:

Example

{
  "type": "PAYMENT_DECLINED",
  "reason": "There is an issue with payment processing."
}

RejectionType

The RejectionType type has the following possible values:

  • INELIGIBLE: User is not eligible due to policy or risk-related concerns.
  • PAYMENT_DECLINED: There is an issue with payment processing.
  • UNAVAILABLE_SLOT: The order cannot be fulfilled at the order ahead time specified by DeliveryInfo or PickupInfo.
  • PROMO_NOT_APPLICABLE: There is an issue with the promotion.
  • UNKNOWN: Any other reason.

Payment-related types

This section describes the payment-related types used for food ordering fulfillment.

ActionProvidedPaymentOptions

Requirements for an action-provided payment method.

The following table lists the properties for the ActionProvidedPaymentOptions type:

Property Type Description
paymentType PaymentType

Required.

displayName String

Required.

Name of the payment instrument displayed on the receipt.

Example: Taco Points Total

onFulfillmentPaymentData OnFulfillmentPaymentData

Additional data for the paymentType "ON_FULFILLMENT". For example, you can use this field to specify if cash or card are supported on fulfillment.

The following example shows a ActionProvidedPaymentOptions element:

Example

{
  "paymentType": "ON_FULFILLMENT",
  "displayName": "Pay when you get your food.",
  "onFulfillmentPaymentData": {
    "supportedPaymentOptions": [
      "Cash",
      "Card"
    ]
  }
}

AllowedAuthMethods

The AllowedAuthMethods type has the following possible values:

  • PAN_ONLY: Authentication method associated with payment cards stored on file with the user's Google Account. Returned payment data includes personal account number (PAN) with the expiration month and the expiration year.

AllowedCardNetworks

The AllowedCardNetworks type has the following possible values:

  • AMEX
  • DISCOVER
  • INTERAC
  • JCB
  • MASTERCARD
  • VISA

CardParameters

Use this object to configure your site's support for the Google Pay API.

The following table lists the properties for the CardParameters type:

Property Type Description
allowedAuthMethods List<Const>

Required.

Fields supported to authenticate a card transaction.

Must have no fewer than 1 item.

allowedCardNetworks List<AllowedCardNetworks>

Required.

One or more card networks that you support that are also supported by the Google Pay API.

Must have no fewer than 1 item.

billingAddressRequired Boolean

Set to true if you require a billing address. Only request a billing address if it's required to process the transaction. Additional data requests can increase friction in the checkout process and lead to lower conversion rates.

cvcRequired Boolean

Set to true if using TimesofMoney, false for all other payment processors.

The following example shows a CardParameters element:

Example

{
  "allowedAuthMethods": [
    "PAN_ONLY"
  ],
  "allowedCardNetworks": [
    "AMEX",
    "DISCOVER"
  ],
  "billingAddressRequired": false,
  "cvcRequired": false
}

GoogleProvidedPaymentInstrument

The following table lists the properties for the GoogleProvidedPaymentInstrument type:

Property Type Description
instrumentToken String

Required.

Base 64-encoded string containing the payment token for charging the user with a participating Google Pay processor, per the previously specified GoogleProvidedPaymentOptions.

billingAddress PostalAddress

Billing address for the payment.

The following example shows a GoogleProvidedPaymentInstrument element:

Example

{
  "instrumentToken": "abcd",
  "billingAddress": {
    "regionCode": "US",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1350 Charleston Road"
    ]
  }
}

GoogleProvidedPaymentOptions

Requirements for Google-provided payment method.

The following table lists the properties for the GoogleProvidedPaymentOptions type:

Property Type Description
facilitationSpecification String

A PaymentDataRequest JSON as a string. Use this object to configure your site's support for the Google Pay API.

supportedCardNetworks List<SupportedCardNetworks>

Use facilitationSpecification instead. Type of card networks supported by the agent.

This field is deprecated.

prepaidCardDisallowed Boolean

Use facilitationSpecification instead. Whether or not a prepaid card is allowed as a payment type.

This field is deprecated.

billingAddressRequired Boolean

Use facilitationSpecification instead. Whether or not a billing address is required.

This field is deprecated.

tokenizationParameters TokenizationParameters

This field is deprecated.

The following example shows a GoogleProvidedPaymentOptions element:

Example 1

{
  "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
}

Example 2

{
  "tokenizationParameters": {
    "tokenizationType": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "braintree",
      "braintree:apiVersion": "v1",
      "braintree:sdkVersion": "1.4.0",
      "braintree:merchantId": "a1b2c3d4e5",
      "braintree:clientKey": "production_braintree_client_key",
      "braintree:authorizationFingerprint": "same_as_client_key"
    }
  },
  "supportedCardNetworks": [
    "AMEX",
    "DISCOVER",
    "MASTERCARD",
    "JCB",
    "VISA"
  ],
  "prepaidCardDisallowed": true
}

Example 3

{
  "tokenizationParameters": {
    "tokenizationType": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "stripe",
      "stripe:publishableKey": "pk_live_stripe_client_key",
      "stripe:version": "2017-04-06"
    }
  },
  "supportedCardNetworks": [
    "AMEX",
    "DISCOVER",
    "MASTERCARD",
    "VISA",
    "JCB"
  ],
  "prepaidCardDisallowed": true,
  "billingAddressRequired": true
}

MerchantInfo

Use this object to configure your site's support for the Google Pay API.

The following table lists the properties for the MerchantInfo type:

Property Type Description
merchantId String

Google merchant identifier issued to you by Google Pay.

merchantName String

Required.

Merchant name encoded as UTF-8. Merchant name is rendered in the payment sheet.

OnFulfillmentPaymentData

Use this object to send additional data for the PaymentType "ON_FULFILLMENT".

The following table lists the properties for the OnFulfillmentPaymentData type:

Property Type Description
supportedPaymentOptions List<PaymentOptionsEnums>

List of payment options available to the user at the time of order fulfillment.

The following example shows a OnFulfillmentPaymentData element:

Example

{
  "supportedPaymentOptions": [
    "Cash",
    "Card"
  ]
}

Parameters

Defines types related to TokenizationParameters.

The following table lists the properties for the Parameters type:

Property Type Description
gateway String

Required.

Example: braintree

gatewayMerchantId String
[additionalKey: string] String Additional key-value pairs

The following example shows a Parameters element:

Example 1

{
  "gatewayMerchantId": "90412491",
  "gateway": "olo"
}

Example 2

{
  "gateway": "braintree",
  "braintree:apiVersion": "v1",
  "braintree:sdkVersion": "1.4.0",
  "braintree:merchantId": "YOUR_MERCHANT_ID",
  "braintree:clientKey": "YOUR_BRAINTREE_SANDVOX_OR_PRODUCTION_KEY"
}

PaymentDataRequest

Use this object to configure your site's support for the Google Pay API.

The following table lists the properties for the PaymentDataRequest type:

Property Type Description
apiVersion Const

Required.

Major API version.

Value: 2

apiVersionMinor Const

Required.

Minor API version.

Value: 0

merchantInfo MerchantInfo

Required.

(Google Pay merchant ID) Information about the merchant that requests payment data.

allowedPaymentMethods List<PaymentMethod>

Required.

Specifies support for one or more payment methods supported by the Google Pay API.

transactionInfo TransactionInfo

Required.

Details about the authorization of the transaction based upon whether the user agrees to the transaction or not. This field includes total price and price status.

The following example shows a PaymentDataRequest element:

Example

{
  "apiVersion": 2,
  "apiVersionMinor": 0,
  "merchantInfo": {
    "merchantId": "10391231",
    "merchantName": "Burrito Town"
  },
  "allowedPaymentMethods": [
    {
      "type": "CARD",
      "parameters": {
        "allowedAuthMethods": [
          "PAN_ONLY"
        ],
        "allowedCardNetworks": [
          "VISA",
          "AMEX",
          "MASTERCARD"
        ],
        "billingAddressRequired": true,
        "cvcRequired": true
      },
      "tokenizationSpecification": {
        "type": "PAYMENT_GATEWAY",
        "parameters": {
          "gateway": "stripe",
          "stripe:version": "2019-05-16",
          "stripe:publishableKey": "pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA"
        }
      }
    }
  ],
  "transactionInfo": {
    "currencyCode": "INR",
    "totalPriceStatus": "ESTIMATED",
    "totalPrice": "185.00"
  }
}

PaymentInfo

Payment-related information for an order.

The following table lists the properties for the PaymentInfo type:

Property Type Description
displayName String

Required.

User-visible name of the payment instrument to display on the receipt.

paymentType PaymentType

Required.

googleProvidedPaymentInstrument GoogleProvidedPaymentInstrument

Token that can be used by the action. Only specify this if you specified GoogleProvidedPaymentOptions as a payment option in the CheckoutResponseMessage.

The following example shows a PaymentInfo element:

Example 1

{
  "displayName": "Visa\u2006****\u20061111",
  "googleProvidedPaymentInstrument": {
    "instrumentToken": "abcd"
  },
  "paymentType": "PAYMENT_CARD"
}

Example 2

{
  "displayName": "Visa\u2006****\u20061111",
  "googleProvidedPaymentInstrument": {
    "instrumentToken": "abcd",
    "billingAddress": {
      "regionCode": "US",
      "postalCode": "94043",
      "administrativeArea": "CA",
      "locality": "Mountain View",
      "addressLines": [
        "123 Random Street",
        "Unit ABC"
      ],
      "recipients": [
        "sample_receipient"
      ]
    }
  },
  "paymentType": "PAYMENT_CARD"
}

PaymentMethod

Use this object to configure your site's support for the Google Pay API.

The following table lists the properties for the PaymentMethod type:

Property Type Description
type Const

Required.

Short identifier for the supported payment method. Only CARD is currently supported.

Value: CARD

parameters CardParameters

Required.

Parameters required to configure the provided payment method type.

tokenizationSpecification TokenizationSpecification

Required.

Configure an account or decryption provider to receive payment information. This property is required for the CARD payment method.

The following example shows a PaymentMethod element:

Example

{
  "type": "CARD",
  "parameters": {
    "allowedAuthMethods": [
      "PAN_ONLY"
    ],
    "allowedCardNetworks": [
      "VISA",
      "AMEX",
      "MASTERCARD"
    ],
    "billingAddressRequired": false
  },
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gatewayMerchantId": "90412491",
      "gateway": "olo"
    }
  }
}

PaymentOptions

The following table lists the properties for the PaymentOptions type:

Property Type Description
Exactly one of the following groups of properties is required.
googleProvidedOptions Group 1 GoogleProvidedPaymentOptions

Mutually exclusive with actionProvidedOptions. Use this for online payment using gPay.

actionProvidedOptions Group 2 ActionProvidedPaymentOptions

Mutually exclusive with googleProvidedOptions. Use this for "cash on delivery" or "pay on fulfillment".

The following example shows a PaymentOptions element:

Example 1

{
  "googleProvidedOptions": {
    "facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": {  \"merchantId\": \"Merchant ID\",  \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [  {    \"type\": \"CARD\",    \"parameters\": {      \"allowedAuthMethods\": [        \"PAN_ONLY\"      ],      \"allowedCardNetworks\": [        \"VISA\",        \"AMEX\",        \"MASTERCARD\"      ],      \"billingAddressRequired\": false    },    \"tokenizationSpecification\": {      \"type\": \"PAYMENT_GATEWAY\",      \"parameters\": {        \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\",        \"gateway\": \"stripe\",        \"stripe:version\": \"2019-05-16\"      }    }  }],\"transactionInfo\": {  \"currencyCode\": \"AUD\",  \"totalPriceStatus\": \"ESTIMATED\",  \"totalPrice\": \"1.0\"}}"
  }
}

Example 2

{
  "actionProvidedOptions": {
    "paymentType": "ON_FULFILLMENT",
    "displayName": "Pay when you get your food.",
    "onFulfillmentPaymentData": {
      "supportedPaymentOptions": [
        "Cash",
        "Card"
      ]
    }
  }
}

PaymentOptionsEnums

The PaymentOptionsEnums type has the following possible values:

  • Cash
  • Card
  • UPI
  • Paytm

PaymentType

The PaymentType type has the following possible values:

  • PAYMENT_CARD: For GoogleProvidedPaymentOptions.
  • ON_FULFILLMENT: For ActionProvidedPaymentOptions.

SupportedCardNetworks

Defines types related to GoogleProvidedPaymentOptions.

The SupportedCardNetworks type has the following possible values:

  • UNSPECIFIED_CARD_NETWORK
  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA

TokenizationParameters

Defines types related to GoogleProvidedPaymentOptions.

The following table lists the properties for the TokenizationParameters type:

Property Type Description
tokenizationType Enum [ "UNSPECIFIED_TOKENIZATION_TYPE", "PAYMENT_GATEWAY" ]

Required.

Use facilitationSpecification instead. Type of tokens acceptable.

parameters Parameters

Use facilitationSpecification instead.

TokenizationSpecification

This object allows you to configure an account to receive chargeable payment information.

The following table lists the properties for the TokenizationSpecification type:

Property Type Description
type Const

Required.

parameters Parameters

Required.

The following example shows a TokenizationSpecification element:

Example 1

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gatewayMerchantId": "1247192",
    "gateway": "cybersource"
  }
}

Example 2

{
  "type": "PAYMENT_GATEWAY",
  "parameters": {
    "gateway": "stripe",
    "stripe:version": "2018-10-31",
    "stripe:publishableKey": "12378127"
  }
}

TransactionInfo

This object describes a transaction that determines a payer's ability to pay. It's used to present a payment authorization dialog.

The following table lists the properties for the TransactionInfo type:

Property Type Description
currencyCode String

Required.

ISO 4217 alphabetic currency code.

transactionId String

Unique ID that identifies a transaction attempt. Merchants may use an existing ID or generate a specific one for Google Pay transaction attempts. This field is required when you send callbacks to the Google Transaction Events API.

totalPriceStatus Const

Required.

Use "ESTIMATED" as the default. Total price may adjust based on the details of the response, such as sales tax collected based on a billing address.

Value: ESTIMATED

totalPrice String

Required.

Total monetary value of the transaction with an optional decimal precision of two decimal places. This field should have the same value as cart.totalPrice.

The following example shows a TransactionInfo element:

Example

{
  "totalPriceStatus": "ESTIMATED",
  "totalPrice": "12.34",
  "currencyCode": "USD"
}