Join us live on October 8th for the virtual Google Assistant Developer Day. Register now.

Method: fulfill

RPC which represents the fulfillment API

HTTP request

Uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation
{
  "handler": {
    object (Handler)
  },
  "intent": {
    object (Intent)
  },
  "scene": {
    object (Scene)
  },
  "session": {
    object (Session)
  },
  "user": {
    object (User)
  },
  "home": {
    object (Home)
  },
  "device": {
    object (Device)
  },
  "context": {
    object (Context)
  }
}
Fields
handler

object (Handler)

Required. Information to fulfillment on how to handle the request. For example a request intending to get a fact might have a handler with a name of "getFact".

intent

object (Intent)

Required. Represents the last matched intent.

scene

object (Scene)

Optional. info on the current and next scene when the function was called. Will be filled when the fulfillment call is made within the scope of a scene.

session

object (Session)

Required. Holds session data like the session id and session parameters.

user

object (User)

Required. User who initiated the conversation.

home

object (Home)

Optional. Information related to the HomeGraph structure that the target device belongs to. See https://developers.google.com/actions/smarthome/concepts/homegraph.

device

object (Device)

Required. info on the device the user is using to interact with the Action.

context

object (Context)

Optional. Information of current context of the request. Includes but isn't limited to active media session info or canvas info.

Response body

If successful, the response body contains data with the following structure:

Represents a response sent from a developer's fulfillment to actions on Google.

JSON representation
{
  "prompt": {
    object (Prompt)
  },
  "scene": {
    object (Scene)
  },
  "session": {
    object (Session)
  },
  "user": {
    object (User)
  },
  "home": {
    object (Home)
  },
  "device": {
    object (Device)
  },
  "expected": {
    object (Expected)
  }
}
Fields
prompt

object (Prompt)

Optional. Represents the prompts to be sent to the user, these prompts will be appended to previously added messages unless explicitly overwritten.

scene

object (Scene)

Optional. Represents the current and next scene. If Scene.next is set the runtime will immediately transition to the specified scene.

session

object (Session)

Optional. Describes data for the current session, session parameters can be created, updated, or removed by the fulfillment.

user

object (User)

Optional. Use to specify user parameters to send back.

home

object (Home)

Optional. Used to specify parameters related to the HomeGraph structure that the target device belongs to. See https://developers.google.com/actions/smarthome/concepts/homegraph.

device

object (Device)

Optional. Use to move between Assistant devices the user has access to.

expected

object (Expected)

Optional. Describes the expectations for the next dialog turn.

Handler

Represents a fulfillment handler that maps event information from actions on Google to fulfillment. Use the handler name to determine what code you should run in fulfillment. For instance, a handler might be used to get information on a user's order information with a handler name like "OrderLookup" while another might get product information from a database, with a handler name like "GetProductInfo".

JSON representation
{
  "name": string
}
Fields
name

string

Optional. The name of the handler.

Intent

Represents an intent.

JSON representation
{
  "name": string,
  "params": {
    string: {
      object(IntentParameterValue)
    },
    ...
  },
  "query": string
}
Fields
name

string

Required. The name of the last matched intent.

params

map (key: string, value: object (IntentParameterValue))

Required. Represents parameters identified as part of intent matching. This is a map of the name of the identified parameter to the value of the parameter identified from user input. All parameters defined in the matched intent that are identified will be surfaced here.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

query

string

Optional. Typed or spoken input from the end user that matched this intent. This will be populated when an intent is matched, based on the user input.

Scene

Represent a scene. Scenes can call fulfillment, add prompts, and collect slot values from the user. Scenes are triggered by events or intents and can trigger events and match intents to transition to other scenes.

JSON representation
{
  "name": string,
  "slotFillingStatus": enum (SlotFillingStatus),
  "slots": {
    string: {
      object(Slot)
    },
    ...
  },
  "next": {
    object (NextScene)
  }
}
Fields
name

string

Required. name of the current scene.

slotFillingStatus

enum (SlotFillingStatus)

Required. The current status of slot filling. This field is read-only.

slots

map (key: string, value: object (Slot))

The slots associated with the current scene. Handler responses cannot return slots which were not sent in the request.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

next

object (NextScene)

Optional. Information on the scene to be executed next.

SlotFillingStatus

Represents the current status of slot filling.

Enums
UNSPECIFIED Fallback value when the usage field is not populated.
INITIALIZED The slots have been initialized but slot filling has not started.
COLLECTING The slot values are being collected.
FINAL All slot values are final and cannot be changed.

NextScene

Represents the scene to be executed next.

JSON representation
{
  "name": string
}
Fields
name

string

name of the scene to be executed next.

Session

Contains information on the current conversation session

JSON representation
{
  "id": string,
  "params": {
    string: value,
    ...
  },
  "typeOverrides": [
    {
      object (TypeOverride)
    }
  ],
  "languageCode": string
}
Fields
id

string

Required. Globally unique ID of the current conversation session. This field is read-only.

params

map (key: string, value: value (Value format))

Required. List of all parameters collected from forms and intents during the session. Key is the parameter name. Parameters defined here will be merged with parameters already defined in the session. Parameters with a null value will be removed from the session.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

typeOverrides[]

object (TypeOverride)

Optional. Types scoped to the session. Session type defines can supplement or replace existing types. type names must be unique.

languageCode

string

Language of the current conversation session. Follows IETF BCP-47 language code http://www.rfc-editor.org/rfc/bcp/bcp47.txt. This could be different from user locale if the action uses multi-language features. For example, when handler_response.expected.language is set, it changes the conversation language for all following turns, which will be reflected in this field.

TypeOverride

Represents an override for a type.

JSON representation
{
  "name": string,
  "mode": enum (TypeOverrideMode),
  "synonym": {
    object (SynonymType)
  }
}
Fields
name

string

Required. name of the type to supplement or override.

mode

enum (TypeOverrideMode)

Required. How this type should be merged with other type values.

synonym

object (SynonymType)

TypeOverrideMode

The types of modifications for a session entity type.

Enums
TYPE_UNSPECIFIED Not specified. This value should be never used.
TYPE_REPLACE The type definitions in this response will replace the type definitions that have been defined previously.
TYPE_MERGE The type definitions in this response will be merged with type definitions that have been defined previously. New type definitions will overwrite existing type definitions.

SynonymType

Represents a type with synonyms.

JSON representation
{
  "entries": [
    {
      object (Entry)
    }
  ]
}
Fields
entries[]

object (Entry)

Required. List of entries for the synonym type.

Entry

Represents a entry for a synonym type.

JSON representation
{
  "name": string,
  "synonyms": [
    string
  ],
  "display": {
    object (EntryDisplay)
  }
}
Fields
name

string

Required. name of the entry (e.g. "bicycle"). The entry in this field must be included in repeated synonyms field to be recogonized as a valid type value.

synonyms[]

string

Required. List of synonyms for the entry (e.g. "bike", "cycle").

display

object (EntryDisplay)

Optional. The item display's information.

EntryDisplay

JSON representation
{
  "title": string,
  "description": string,
  "image": {
    object (Image)
  },
  "footer": string,
  "openUrl": {
    object (OpenUrl)
  }
}
Fields
title

string

Required. Title of the item. When tapped, this text will be posted back to the conversation verbatim as if the user had typed it. Each title must be unique among the set of collection items.

description

string

Optional. Body text of the card.

image

object (Image)

Optional. The image to display.

footer

string

Optional. Footer text for the browsing collection item, displayed below the description. Single line of text, truncated with an ellipsis.

openUrl

object (OpenUrl)

URL of document associated with browsing carousel item. Required for browsing carousel.

Image

An image displayed in the card.

JSON representation
{
  "url": string,
  "alt": string,
  "height": integer,
  "width": integer
}
Fields
url

string

The source url of the image. Images can be JPG, PNG and GIF (animated and non-animated). For example,https://www.agentx.com/logo.png. Required.

alt

string

A text description of the image to be used for accessibility, e.g. screen readers. Required.

height

integer

The height of the image in pixels. Optional.

width

integer

The width of the image in pixels. Optional.

OpenUrl

JSON representation
{
  "url": string,
  "hint": enum (UrlHint)
}
Fields
url

string

The url field which could be any of: - http/https urls for opening an App-linked App or a webpage

hint

enum (UrlHint)

Indicates a hint for the url type.

UrlHint

Different types of url hints.

Enums
AMP URL that points directly to AMP content, or to a canonical URL which refers to AMP content via .

User

Represents the user making a request to the Action.

JSON representation
{
  "locale": string,
  "params": {
    string: value,
    ...
  },
  "accountLinkingStatus": enum (AccountLinkingStatus),
  "verificationStatus": enum (UserVerificationStatus),
  "lastSeenTime": string,
  "engagement": {
    object (Engagement)
  },
  "packageEntitlements": [
    {
      object (PackageEntitlements)
    }
  ]
}
Fields
locale

string

Primary locale setting of the user making the request. Follows IETF BCP-47 language code http://www.rfc-editor.org/rfc/bcp/bcp47.txt However, the script subtag is not included.

params

map (key: string, value: value (Value format))

Optional. List of all parameters associated with the current user.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

accountLinkingStatus

enum (AccountLinkingStatus)

Whether the user account is linked to the app.

verificationStatus

enum (UserVerificationStatus)

Indicates the verification status of the user.

lastSeenTime

string (Timestamp format)

The timestamp of the last interaction with this user. This field will be omitted if the user has not interacted with the agent before.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

engagement

object (Engagement)

The engagement of the current user including any subscriptions to intents.

packageEntitlements[]

object (PackageEntitlements)

User's entitlements related to the Android package associated with the current action.

AccountLinkingStatus

Indicates whether the end user has linked their account to this app.

Enums
ACCOUNT_LINKING_STATUS_UNSPECIFIED Unknown.
NOT_LINKED User has not linked their account to this app.
LINKED User has linked their account to this app.

UserVerificationStatus

Indicates whether Google has verified the user. A VERIFIED status indicates that you can save data across conversations using the params field or with account linking.

Enums
USER_VERIFICATION_STATUS_UNSPECIFIED Unknown.
GUEST Guest user.
VERIFIED verified user.

Engagement

Provides additional read-only information about what engagement mechanisms the current user has registered for. For example, it can be useful to know what intents the user is already subscribed to in order to avoid asking them to subscribe to the same intent again. i.e. This information can be used to conditionally route to a scene to set up DailyUpdates or PushNotifications only if the user has not subscribed already.

JSON representation
{
  "pushNotificationIntents": [
    {
      object (IntentSubscription)
    }
  ],
  "dailyUpdateIntents": [
    {
      object (IntentSubscription)
    }
  ]
}
Fields
pushNotificationIntents[]

object (IntentSubscription)

Contains a list of intents which the user has enabled push notification for.

dailyUpdateIntents[]

object (IntentSubscription)

Contains a list of intents which the user has enabled daily update for.

IntentSubscription

Describes an existing IntentSubscription.

JSON representation
{
  "intent": string,
  "contentTitle": string
}
Fields
intent

string

name of the intent which is subscribed to.

contentTitle

string

A short description of the subscription. It is used as the notification's label and when Assistant is requesting permission from the user.

PackageEntitlements

A List of user's entitlements related to a package name.

JSON representation
{
  "packageName": string,
  "entitlements": [
    {
      object (Entitlement)
    }
  ]
}
Fields
packageName

string

The Android package name specified in the action package.

entitlements[]

object (Entitlement)

The user's entitlements for the given package.

Entitlement

Defines a user's digital entitlement.

JSON representation
{
  "sku": string,
  "skuType": enum (SkuType),
  "inAppDetails": {
    object (SignedData)
  }
}
Fields
sku

string

Product sku. Package name for paid app, suffix of Finsky docid for in-app purchase and in-app subscription. Match getSku() in Play InApp Billing API.

skuType

enum (SkuType)

The type of SKU.

inAppDetails

object (SignedData)

Only present for in-app purchase and in-app subs.

SkuType

Enums
SKU_TYPE_UNSPECIFIED
IN_APP In-app purchase
SUBSCRIPTION Subscriptions
APP Paid apps

SignedData

JSON representation
{
  "inAppPurchaseData": {
    object
  },
  "inAppDataSignature": string
}
Fields
inAppPurchaseData

object (Struct format)

Contains all inapp purchase data in JSON format. See details in table 6 of https://developer.android.com/google/play/billing/billing_reference.html.

inAppDataSignature

string

Matches IN_APP_DATA_SIGNATURE from getPurchases() method in Play InApp Billing API.

Home

Represents the HomeGraph structure that the user's target device belongs to.

JSON representation
{
  "params": {
    string: value,
    ...
  }
}
Fields
params

map (key: string, value: value (Value format))

Optional. List of parameters associated with the HomeGraph structure the target device belongs to.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Device

Represents the device the user is using to make a request to the Action.

JSON representation
{
  "capabilities": [
    enum (Capability)
  ]
}
Fields
capabilities[]

enum (Capability)

Required. the capabilities of the device making a request to the Action.

Capability

capabilities the device surface supports at the time of the request.

Enums
UNSPECIFIED Unspecified device capability.
SPEECH device can speak to the user via text-to-speech or SSML.
RICH_RESPONSE device can display rich responses like cards, lists and tables.
LONG_FORM_AUDIO device can play long form audio media like music and podcasts.
INTERACTIVE_CANVAS device can display a interactive canvas response.

Context

Contains context information when user makes query. Such context includes but not limited to info about active media session, state of canvas web app, etc.

JSON representation
{
  "media": {
    object (MediaContext)
  }
}
Fields
media

object (MediaContext)

Contains context information about current active media session.

MediaContext

Contains context information about current active media session.

JSON representation
{
  "progress": string
}
Fields
progress

string (Duration format)

Media progress of current active media file.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

Prompt

Represent a response to a user.

JSON representation
{
  "override": boolean,
  "firstSimple": {
    object (Simple)
  },
  "content": {
    object (Content)
  },
  "lastSimple": {
    object (Simple)
  },
  "suggestions": [
    {
      object (Suggestion)
    }
  ],
  "link": {
    object (Link)
  },
  "canvas": {
    object (Canvas)
  },
  "orderUpdate": {
    object (OrderUpdate)
  }
}
Fields
override

boolean

Optional. Mode for how this messages should be merged with previously defined messages. "true" clears all previously defined messages (first and last simple, content, suggestions link and canvas) and adds messages defined in this prompt. "false" adds messages defined in this prompt to messages defined in previous responses. Leaving this field to "false" also enables appending to some fields inside Simple prompts, the Suggestions prompt, and the Canvas prompt (part of the Content prompt). The Content and Link messages are always overwritten if defined in the prompt. Default value is "false".

firstSimple

object (Simple)

Optional. The first voice and text-only response.

content

object (Content)

Optional. A content like a card, list or media to display to the user.

lastSimple

object (Simple)

Optional. The last voice and text-only response.

suggestions[]

object (Suggestion)

Optional. Suggestions to be displayed to the user which will always appear at the end of the response. If the "override" field in the containing prompt is "false", the titles defined in this field will be added to titles defined in any previously defined suggestions prompts and duplicate values will be removed.

canvas

object (Canvas)

Optional. Represents a Interactive Canvas response to be sent to the user.

orderUpdate

object (OrderUpdate)

Optional Action responds with an OrderUpdate after receiving the order during the transactions flow. On receipt of this, Google records this update to the order, and if successful, displays a receipt card along with the TTS sent on display devices.

Simple

Represents a simple prompt to be send to a user.

JSON representation
{
  "speech": string,
  "text": string
}
Fields
speech

string

Optional. Represents the speech to be spoken to the user. Can be SSML or text to speech. If the "override" field in the containing prompt is "true", the speech defined in this field replaces the previous Simple prompt's speech.

text

string

Optional text to display in the chat bubble. If not given, a display rendering of the speech field above will be used. Limited to 640 chars. If the "override" field in the containing prompt is "true", the text defined in this field replaces to the previous Simple prompt's text.

Content

JSON representation
{

  // Union field content can be only one of the following:
  "card": {
    object (Card)
  },
  "image": {
    object (Image)
  },
  "table": {
    object (Table)
  },
  "media": {
    object (Media)
  },
  "collection": {
    object (Collection)
  },
  "list": {
    object (List)
  }
  // End of list of possible types for union field content.
}
Fields

Union field content.

content can be only one of the following:

card

object (Card)

A basic card.

image

object (Image)

An image.

table

object (Table)

Table card.

media

object (Media)

Response indicating a set of media to be played.

collection

object (Collection)

A card presenting a collection of options to select from.

list

object (List)

A card presenting a list of options to select from.

Card

A basic card for displaying some information, e.g. an image and/or text.

JSON representation
{
  "title": string,
  "subtitle": string,
  "text": string,
  "image": {
    object (Image)
  },
  "imageFill": enum (ImageFill),
  "button": {
    object (Link)
  }
}
Fields
title

string

Overall title of the card. Optional.

subtitle

string

Optional.

text

string

Body text of the card. Supports a limited set of markdown syntax for formatting. Required, unless image is present.

image

object (Image)

A hero image for the card. The height is fixed to 192dp. Optional.

imageFill

enum (ImageFill)

How the image background will be filled. Optional.

button

object (Link)

Button. Optional.

ImageFill

Possible image display options for affecting the presentation of the image. This should be used for when the image's aspect ratio does not match the image container's aspect ratio.

Enums
UNSPECIFIED
GRAY Fill the gaps between the image and the image container with gray bars.
WHITE Fill the gaps between the image and the image container with white bars.
CROPPED Image is scaled such that the image width and height match or exceed the container dimensions. This may crop the top and bottom of the image if the scaled image height is greater than the container height, or crop the left and right of the image if the scaled image width is greater than the container width. This is similar to "Zoom Mode" on a widescreen TV when playing a 4:3 video.

Table

A table card for displaying a table of text.

JSON representation
{
  "title": string,
  "subtitle": string,
  "image": {
    object (Image)
  },
  "columns": [
    {
      object (TableColumn)
    }
  ],
  "rows": [
    {
      object (TableRow)
    }
  ],
  "button": {
    object (Link)
  }
}
Fields
title

string

Overall title of the table. Optional but must be set if subtitle is set.

subtitle

string

Subtitle for the table. Optional.

image

object (Image)

Image associated with the table. Optional.

columns[]

object (TableColumn)

Headers and alignment of columns.

rows[]

object (TableRow)

Row data of the table. The first 3 rows are guaranteed to be shown but others might be cut on certain surfaces. Please test with the simulator to see which rows will be shown for a given surface. On surfaces that support the WEB_BROWSER capability, you can point the user to a web page with more data.

button

object (Link)

Button.

TableColumn

JSON representation
{
  "header": string,
  "align": enum (HorizontalAlignment)
}
Fields
header

string

Header text for the column.

align

enum (HorizontalAlignment)

Horizontal alignment of content w.r.t column. If unspecified, content will be aligned to the leading edge.

HorizontalAlignment

The alignment of the content within the cell.

Enums
UNSPECIFIED
LEADING Leading edge of the cell. This is the default.
CENTER Content is aligned to the center of the column.
TRAILING Content is aligned to the trailing edge of the column.

TableRow

Describes a row in the table.

JSON representation
{
  "cells": [
    {
      object (TableCell)
    }
  ],
  "divider": boolean
}
Fields
cells[]

object (TableCell)

Cells in this row. The first 3 cells are guaranteed to be shown but others might be cut on certain surfaces. Please test with the simulator to see which cells will be shown for a given surface.

divider

boolean

Indicates whether there should be a divider after each row.

TableCell

Describes a cell in a row.

JSON representation
{
  "text": string
}
Fields
text

string

Text content of the cell.

Media

Represents one media object. Contains information about the media, such as name, description, url, etc.

JSON representation
{
  "mediaType": enum (MediaType),
  "startOffset": string,
  "optionalMediaControls": [
    enum (OptionalMediaControls)
  ],
  "mediaObjects": [
    {
      object (MediaObject)
    }
  ]
}
Fields
mediaType

enum (MediaType)

startOffset

string (Duration format)

Start offset of the first media object.

A duration in seconds with up to nine fractional digits, terminated by 's'. Example: "3.5s".

optionalMediaControls[]

enum (OptionalMediaControls)

Optional media control types this media response session can support. If set, request will be made to 3p when a certain media event happens. If not set, 3p must still handle two default control type, FINISHED and FAILED.

mediaObjects[]

object (MediaObject)

List of Media Objects

MediaType

Media type of this response.

Enums
MEDIA_TYPE_UNSPECIFIED
AUDIO Audio file.
MEDIA_STATUS_ACK Response to acknowledge a media status report.

OptionalMediaControls

Optional media control types the media response can support

Enums
OPTIONAL_MEDIA_CONTROLS_UNSPECIFIED Unspecified value
PAUSED Paused event. Triggered when user pauses the media.
STOPPED Stopped event. Triggered when user exits out of 3p session during media play.

MediaObject

Represents a single media object

JSON representation
{
  "name": string,
  "description": string,
  "url": string,
  "image": {
    object (MediaImage)
  }
}
Fields
name

string

name of this media object.

description

string

description of this media object.

url

string

The url pointing to the media content.

image

object (MediaImage)

Image to show with the media card.

MediaImage

JSON representation
{

  // Union field image can be only one of the following:
  "large": {
    object (Image)
  },
  "icon": {
    object (Image)
  }
  // End of list of possible types for union field image.
}
Fields

Union field image.

image can be only one of the following:

large

object (Image)

A large image, such as the cover of the album, etc.

icon

object (Image)

A small image icon displayed on the right from the title. It's resized to 36x36 dp.

Collection

A card for presenting a collection of options to select from.

JSON representation
{
  "title": string,
  "subtitle": string,
  "items": [
    {
      object (CollectionItem)
    }
  ],
  "imageFill": enum (ImageFill)
}
Fields
title

string

Title of the collection. Optional.

subtitle

string

Subtitle of the collection. Optional.

items[]

object (CollectionItem)

min: 2 max: 10

imageFill

enum (ImageFill)

How the image backgrounds of collection items will be filled. Optional.

CollectionItem

An item in the collection

JSON representation
{
  "key": string
}
Fields
key

string

Required. The NLU key that matches the entry key name in the associated type.

List

A card for presenting a list of options to select from.

JSON representation
{
  "title": string,
  "subtitle": string,
  "items": [
    {
      object (ListItem)
    }
  ]
}
Fields
title

string

Title of the list. Optional.

subtitle

string

Subtitle of the list. Optional.

items[]

object (ListItem)

min: 2 max: 30

ListItem

An item in the list

JSON representation
{
  "key": string
}
Fields
key

string

Required. The NLU key that matches the entry key name in the associated type.

Suggestion

JSON representation
{
  "title": string
}
Fields
title

string

Required. The text shown in the suggestion chip. When tapped, this text will be posted back to the conversation verbatim as if the user had typed it. Each title must be unique among the set of suggestion chips. Max 25 chars

Canvas

Represents an Interactive Canvas response to be sent to the user. This can be used in conjunction with the "firstSimple" field in the containing prompt to speak to the user in addition to displaying a interactive canvas response. The maximum size of the response is 50k bytes.

JSON representation
{
  "url": string,
  "data": [
    value
  ],
  "suppressMic": boolean
}
Fields
url

string

URL of the interactive canvas web app to load. If not set, the url from current active canvas will be reused.

data[]

value (Value format)

Optional. JSON data to be passed through to the immersive experience web page as an event. If the "override" field in the containing prompt is "false" data values defined in this Canvas prompt will be added after data values defined in previous Canvas prompts.

suppressMic

boolean

Optional. Default value: false.

OrderUpdate

Update to an order.

JSON representation
{
  "type": enum (Type),
  "order": {
    object (Order)
  },
  "updateMask": string,
  "userNotification": {
    object (UserNotification)
  },
  "reason": string
}
Fields
type
(deprecated)

enum (Type)

Deprecated: Use OrderUpdate.update_mask instead. If type = SNAPSHOT, OrderUpdate.order should be the entire order. If type = ORDER_STATUS, this is the order level status change. Only order.last_update_time and this vertical status are picked up. Note: type.ORDER_STATUS only supports PurcahaseOrderExtension status updates and there is no plan to extend this support. Instead, we recommend using updateMask as it is more generic, extensible and can be used for all verticals.

order

object (Order)

updateMask

string (FieldMask format)

Note: There are following consideration/recommendations for following special fields: 1. order.last_update_time will always be updated as part of the update request. 2. order.create_time, order.google_order_id and order.merchant_order_id will be ignored if provided as part of the updateMask.

A comma-separated list of fully qualified names of fields. Example: "user.displayName,photo".

userNotification

object (UserNotification)

If specified, displays a notification to the user with the specified title and text. Specifying a notification is a suggestion to notify and is not guaranteed to result in a notification.

reason

string

Reason for the change/update.

Type

Deprecated: Use OrderUpdate.update_mask instead. Allowed updates to an order.

Enums
TYPE_UNSPECIFIED type unspecified, should not set this explicitly.
ORDER_STATUS Only update status of the order.
SNAPSHOT Update order snapshot.

Order

Order entity. Note: 1. All strings at all levels must be less than 1000 chars unless otherwise specified. 2. All repeated fields at all levels must be less than 50 in count unless otherwise specified. 3. All timestamps at all levels, if specified, must be valid timestamps.

JSON representation
{
  "googleOrderId": string,
  "merchantOrderId": string,
  "userVisibleOrderId": string,
  "userVisibleStateLabel": string,
  "buyerInfo": {
    object (UserInfo)
  },
  "image": {
    object (Image)
  },
  "createTime": string,
  "lastUpdateTime": string,
  "transactionMerchant": {
    object (Merchant)
  },
  "contents": {
    object (Contents)
  },
  "priceAttributes": [
    {
      object (PriceAttribute)
    }
  ],
  "followUpActions": [
    {
      object (Action)
    }
  ],
  "paymentData": {
    object (PaymentData)
  },
  "termsOfServiceUrl": string,
  "note": string,
  "promotions": [
    {
      object (Promotion)
    }
  ],
  "disclosures": [
    {
      object (Disclosure)
    }
  ],
  "vertical": {
    "@type": string,
    field1: ...,
    ...
  },

  // Union field verticals can be only one of the following:
  "purchase": {
    object (PurchaseOrderExtension)
  },
  "ticket": {
    object (TicketOrderExtension)
  }
  // End of list of possible types for union field verticals.
}
Fields
googleOrderId

string

Google assigned order id.

merchantOrderId

string

Required: Merchant assigned internal order id. This id must be unique, and is required for subsequent order update operations. This id may be set to the provided googleOrderId, or any other unique value. Note that the id presented to users is the userVisibleOrderId, which may be a different, more user-friendly value. Max allowed length is 128 chars.

userVisibleOrderId

string

The user facing id referencing to current order. This id should be consistent with the id displayed for this order in other contexts, including websites, apps and email.

userVisibleStateLabel
(deprecated)

string

Deprecated: Use OrderExtensions status instead. User visible label for the state of this order.

buyerInfo

object (UserInfo)

info about the buyer.

image

object (Image)

Image associated with the order.

createTime

string (Timestamp format)

Required: date and time the order was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

lastUpdateTime

string (Timestamp format)

date and time the order was last updated. Required for OrderUpdate.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

transactionMerchant

object (Merchant)

Merchant that facilitated the checkout. This could be different from a line item level provider. Example: Expedia Order with line item from ANA.

contents

object (Contents)

Required: Order contents which is a group of line items.

priceAttributes[]

object (PriceAttribute)

Price, discounts, taxes and so on.

followUpActions[]

object (Action)

Follow up actions at order level.

paymentData

object (PaymentData)

Payment related data for the order.

termsOfServiceUrl

string

A link to the terms of service that apply to order/proposed order.

note

string

Notes attached to an order.

promotions[]

object (Promotion)

All promotions that are associated with this order.

disclosures[]

object (Disclosure)

Disclosures associated with this order.

vertical
(deprecated)

object

Deprecated: Use verticals instead. These properties will apply to all line items, unless overridden in some line item. This vertical must match the line item level vertical type. Possible values: google.actions.orders.v3.verticals.purchase.PurchaseOrderExtension google.actions.orders.v3.verticals.ticket.TicketOrderExtension

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

Union field verticals. These properties will apply to all line items, unless overridden in some line item. This vertical must match the line item level vertical type. verticals can be only one of the following:
purchase

object (PurchaseOrderExtension)

Purchase order

ticket

object (TicketOrderExtension)

Ticket order

UserInfo

Information about user. This is used to represent information of the user associated with an order.

JSON representation
{
  "email": string,
  "firstName": string,
  "lastName": string,
  "displayName": string,
  "phoneNumbers": [
    {
      object (PhoneNumber)
    }
  ]
}
Fields
email

string

User email, Eg: janedoe@gmail.com.

firstName

string

First name of the user.

lastName

string

Last name of the user.

displayName

string

Display name of the user, might be different from first or last name.

phoneNumbers[]

object (PhoneNumber)

Phone numbers of the user.

PhoneNumber

Standard phone number representation.

JSON representation
{
  "e164PhoneNumber": string,
  "extension": string,
  "preferredDomesticCarrierCode": string
}
Fields
e164PhoneNumber

string

Phone number in E.164 format, as defined in International Telecommunication Union (ITU) Recommendation E.164. wiki link: https://en.wikipedia.org/wiki/E.164

extension

string

Extension is not standardized in ITU recommendations, except for being defined as a series of numbers with a maximum length of 40 digits. It is defined as a string here to accommodate for the possible use of a leading zero in the extension (organizations have complete freedom to do so, as there is no standard defined). Other than digits, some other dialling characters such as "," (indicating a wait) may be stored here. For example, in xxx-xxx-xxxx ext. 123, "123" is the extension.

preferredDomesticCarrierCode

string

The carrier selection code that is preferred when calling this phone number domestically. This also includes codes that need to be dialed in some countries when calling from landlines to mobiles or vice versa. For example, in Columbia, a "3" needs to be dialed before the phone number itself when calling from a mobile phone to a domestic landline phone and vice versa. https://en.wikipedia.org/wiki/Telephone_numbers_in_Colombia https://en.wikipedia.org/wiki/Brazilian_Carrier_Selection_Code

Note this is the "preferred" code, which means other codes may work as well.

Image

An image displayed in the card.

JSON representation
{
  "url": string,
  "accessibilityText": string,
  "height": integer,
  "width": integer
}
Fields
url

string

The source url of the image. Images can be JPG, PNG and GIF (animated and non-animated). For example,https://www.agentx.com/logo.png. Required.

accessibilityText

string

A text description of the image to be used for accessibility, e.g. screen readers. Required.

height

integer

The height of the image in pixels. Optional.

width

integer

The width of the image in pixels. Optional.

Merchant

Merchant for the cart/order/line item.

JSON representation
{
  "id": string,
  "name": string,
  "image": {
    object (Image)
  },
  "phoneNumbers": [
    {
      object (PhoneNumber)
    }
  ],
  "address": {
    object (Location)
  }
}
Fields
id

string

Optional ID assigned to merchant if any.

name

string

The name of the merchant like "Panera Bread".

image

object (Image)

The image associated with the merchant.

phoneNumbers[]

object (PhoneNumber)

Merchant's phone numbers.

address

object (Location)

Merchant's address.

Location

Container that represents a location.

JSON representation
{
  "coordinates": {
    object (LatLng)
  },
  "formattedAddress": string,
  "zipCode": string,
  "city": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "name": string,
  "phoneNumber": string,
  "notes": string,
  "placeId": string
}
Fields
coordinates

object (LatLng)

Geo coordinates. Requires the [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] permission.

formattedAddress

string

Display address, e.g., "1600 Amphitheatre Pkwy, Mountain View, CA 94043". Requires the [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] permission.

zipCode

string

Zip code. Requires the [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] or [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] permission.

city

string

city. Requires the [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] or [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] permission.

postalAddress

object (PostalAddress)

Postal address. Requires the [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] or [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] permission.

name

string

name of the place.

phoneNumber

string

Phone number of the location, e.g. contact number of business location or phone number for delivery location.

notes

string

Notes about the location.

placeId

string

placeId is used with Places API to fetch details of a place. See https://developers.google.com/places/web-service/place-id

LatLng

An object representing a latitude/longitude pair. This is expressed as a pair of doubles representing degrees latitude and degrees longitude. Unless specified otherwise, this must conform to the WGS84 standard. Values must be within normalized ranges.

JSON representation
{
  "latitude": number,
  "longitude": number
}
Fields
latitude

number

The latitude in degrees. It must be in the range [-90.0, +90.0].

longitude

number

The longitude in degrees. It must be in the range [-180.0, +180.0].

PostalAddress

Represents a postal address, e.g. for postal delivery or payments addresses. Given a postal address, a postal service can deliver items to a premise, P.O. Box or similar. It is not intended to model geographical locations (roads, towns, mountains).

In typical usage an address would be created via user input or from importing existing data, depending on the type of process.

Advice on address input / editing: - Use an i18n-ready address widget such as https://github.com/google/libaddressinput) - Users should not be presented with UI elements for input or editing of fields outside countries where that field is used.

For more guidance on how to use this schema, please see: https://support.google.com/business/answer/6397478

JSON representation
{
  "revision": integer,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
Fields
revision

integer

The schema revision of the PostalAddress. This must be set to 0, which is the latest revision.

All new revisions must be backward compatible with old revisions.

regionCode

string

Required. CLDR region code of the country/region of the address. This is never inferred and it is up to the user to ensure the value is correct. See http://cldr.unicode.org/ and http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html for details. Example: "CH" for Switzerland.

languageCode

string

Optional. BCP-47 language code of the contents of this address (if known). This is often the UI language of the input form or is expected to match one of the languages used in the address' country/region, or their transliterated equivalents. This can affect formatting in certain countries, but is not critical to the correctness of the data and will never affect any validation or other non-formatting related operations.

If this value is not known, it should be omitted (rather than specifying a possibly incorrect default).

Examples: "zh-Hant", "ja", "ja-Latn", "en".

postalCode

string

Optional. Postal code of the address. Not all countries use or require postal codes to be present, but where they are used, they may trigger additional validation with other parts of the address (e.g. state/zip validation in the U.S.A.).

sortingCode

string

Optional. Additional, country-specific, sorting code. This is not used in most regions. Where it is used, the value is either a string like "CEDEX", optionally followed by a number (e.g. "CEDEX 7"), or just a number alone, representing the "sector code" (Jamaica), "delivery area indicator" (Malawi) or "post office indicator" (e.g. Côte d'Ivoire).

administrativeArea

string

Optional. Highest administrative subdivision which is used for postal addresses of a country or region. For example, this can be a state, a province, an oblast, or a prefecture. Specifically, for Spain this is the province and not the autonomous community (e.g. "Barcelona" and not "Catalonia"). Many countries don't use an administrative area in postal addresses. E.g. in Switzerland this should be left unpopulated.

locality

string

Optional. Generally refers to the city/town portion of the address. Examples: US city, IT comune, UK post town. In regions of the world where localities are not well defined or do not fit into this structure well, leave locality empty and use addressLines.

sublocality

string

Optional. Sublocality of the address. For example, this can be neighborhoods, boroughs, districts.

addressLines[]

string

Unstructured address lines describing the lower levels of an address.

Because values in addressLines do not have type information and may sometimes contain multiple values in a single field (e.g. "Austin, TX"), it is important that the line order is clear. The order of address lines should be "envelope order" for the country/region of the address. In places where this can vary (e.g. Japan), address_language is used to make it explicit (e.g. "ja" for large-to-small ordering and "ja-Latn" or "en" for small-to-large). This way, the most specific line of an address can be selected based on the language.

The minimum permitted structural representation of an address consists of a regionCode with all remaining information placed in the addressLines. It would be possible to format such an address very approximately without geocoding, but no semantic reasoning could be made about any of the address components until it was at least partially resolved.

Creating an address only containing a regionCode and addressLines, and then geocoding is the recommended way to handle completely unstructured addresses (as opposed to guessing which parts of the address should be localities or administrative areas).

recipients[]

string

Optional. The recipient at the address. This field may, under certain circumstances, contain multiline information. For example, it might contain "care of" information.

organization

string

Optional. The name of the organization at the address.

Contents

Wrapper for line items.

JSON representation
{
  "lineItems": [
    {
      object (LineItem)
    }
  ]
}
Fields
lineItems[]

object (LineItem)

List of order line items. At least 1 lineItem is required and at-most 50 is allowed. All line items must belong to same vertical.

LineItem

One line item contains one vertical. An order or cart can have multiple line items of same vertical. Sub-line items/add-ons etc should be defined in vertical protos depending on their use cases. Note: 1. All strings at all levels must be less than 1000 chars unless otherwise specified. 2. All repeated fields at all levels must be less than 50 in count unless otherwise specified. 3. All timestamps at all levels, if specified, must be valid timestamps.

JSON representation
{
  "id": string,
  "name": string,
  "userVisibleStateLabel": string,
  "provider": {
    object (Merchant)
  },
  "priceAttributes": [
    {
      object (PriceAttribute)
    }
  ],
  "followUpActions": [
    {
      object (Action)
    }
  ],
  "recipients": [
    {
      object (UserInfo)
    }
  ],
  "image": {
    object (Image)
  },
  "description": string,
  "notes": [
    string
  ],
  "disclosures": [
    {
      object (Disclosure)
    }
  ],
  "vertical": {
    "@type": string,
    field1: ...,
    ...
  },

  // Union field verticals can be only one of the following:
  "purchase": {
    object (PurchaseItemExtension)
  },
  "reservation": {
    object (ReservationItemExtension)
  }
  // End of list of possible types for union field verticals.
}
Fields
id

string

Required: Merchant assigned identifier for line item. Used for identifying existing line item in applying partial updates. Max allowed length is 64 chars.

name

string

name of line item as displayed on the receipt. Max allowed length is 100 chars.

userVisibleStateLabel
(deprecated)

string

Deprecated. Use vertical level status instead. For example, for purchases, use PurchaseOrderExtension.status. User visible label for the state of this line item.

provider

object (Merchant)

The provider of the particular line item, if different from the overall order. Example: Expedia Order with line item provider ANA.

priceAttributes[]

object (PriceAttribute)

Line item level price and adjustments.

followUpActions[]

object (Action)

Follow up actions at line item.

recipients[]

object (UserInfo)

Line item level customers, this could be different from Order level buyer. Example: User X made restaurant reservation under name of user Y.

image

object (Image)

Small image associated with this item, if any.

description

string

Line item description.

notes[]

string

Additional notes applicable to this particular line item, for example cancellation policy.

disclosures[]

object (Disclosure)

Disclosures associated with this line item.

vertical
(deprecated)

object

Deprecated: Use verticals instead. Required: Semantic Contents of line item based on its type/vertical. Every vertical should include its own fulfillment details. Must be either one of the following values: google.actions.orders.v3.verticals.purchase.PurchaseItemExtension google.actions.orders.v3.verticals.reservation.ReservationItemExtension google.actions.orders.v3.verticals.ticket.TicketItemExtension

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

Union field verticals. Required: Semantic Contents of line item based on its type/vertical. Every vertical should include its own fulfillment details. verticals can be only one of the following:
purchase

object (PurchaseItemExtension)

Purchase orders like goods, food etc.

reservation

object (ReservationItemExtension)

Reservation orders like restaurant, haircut etc.

PriceAttribute

Price attribute of an order or a line item.

JSON representation
{
  "type": enum (Type),
  "name": string,
  "id": string,
  "state": enum (State),
  "taxIncluded": boolean,

  // Union field spec can be only one of the following:
  "amount": {
    object (Money)
  },
  "amountMillipercentage": integer
  // End of list of possible types for union field spec.
}
Fields
type

enum (Type)

Required: type of money attribute.

name

string

Required: User displayed string of the price attribute. This is sent and localized by merchant.

id

string

Optional: Id of the lineitem to which this price corresponds.

state

enum (State)

Required: state of the price: Estimate vs Actual.

taxIncluded

boolean

Whether the price is tax included.

Union field spec. Represents either monetary amount or milli percentage. spec can be only one of the following:
amount

object (Money)

Monetary amount.

amountMillipercentage
(deprecated)

integer

The percentage spec, to 1/1000th of a percent. Eg: 8.750% is represented as 8750, negative percentages represent percentage discounts. Deprecating this field. Can consider adding back when a solid usecase is required.

Type

Represents the type of money.

Enums
TYPE_UNSPECIFIED type is unspecified, clients should not have to set this explicitly.
REGULAR Regular display price, before any discounts etc have been applied.
DISCOUNT To be subtracted from the subtotal.
TAX To be added to the subtotal.
DELIVERY To be added to the subtotal.
SUBTOTAL Subtotal before some fees may be added.
FEE Any additional Fee.
GRATUITY To be added to the subtotal.
TOTAL Displayed price of order or line item.

State

Represents the price state.

Enums
STATE_UNSPECIFIED Not specified.
ESTIMATE The price is just an estimate.
ACTUAL Actual price that will be charged for user.

Money

Represents an amount of money with its currency type.

JSON representation
{
  "currencyCode": string,
  "amountInMicros": string
}
Fields
currencyCode

string

The 3-letter currency code defined in ISO 4217.

amountInMicros

string (int64 format)

Amount in micros. For example, this field should be set as 1990000 for $1.99.

Action

A follow-up action associated with the order or line item.

JSON representation
{
  "type": enum (Type),
  "title": string,
  "openUrlAction": {
    object (OpenUrlAction)
  },
  "actionMetadata": {
    object (ActionMetadata)
  }
}
Fields
type

enum (Type)

Required: type of action.

title

string

Title or label of the action, displayed to the user. Max allowed length is 100 chars.

openUrlAction

object (OpenUrlAction)

Action to take.

actionMetadata

object (ActionMetadata)

Metadata associated with an action.

Type

Possible follow-up actions.

Enums
TYPE_UNSPECIFIED Unspecified action.
VIEW_DETAILS View order details action.
MODIFY Modify order action.
CANCEL Cancel order action.
RETURN Return order action.
EXCHANGE Exchange order action.
EMAIL

email action. EMAIL and CALL types are deprecated. openUrlAction.url can be used as a phone-number or an email.

CALL

Call action.

REORDER Reorder action.
REVIEW Review order action.
CUSTOMER_SERVICE Contact customer service.
FIX_ISSUE Direct to merchant site or app to fix the issue.
DIRECTION Direction link.

OpenUrlAction

Opens the given url.

JSON representation
{
  "url": string,
  "androidApp": {
    object (AndroidApp)
  },
  "urlTypeHint": enum (UrlTypeHint)
}
Fields
url

string

The url field which could be any of: - http/https urls for opening an App-linked App or a webpage

androidApp

object (AndroidApp)

Information about the Android App if the URL is expected to be fulfilled by an Android App.

urlTypeHint

enum (UrlTypeHint)

Indicates a hint for the url type.

AndroidApp

Specification of the Android App for fulfillment restrictions

JSON representation
{
  "packageName": string,
  "versions": [
    {
      object (VersionFilter)
    }
  ]
}
Fields
packageName

string

Package name Package name must be specified when specifing Android Fulfillment.

versions[]

object (VersionFilter)

When multiple filters are specified, any filter match will trigger the app.

VersionFilter

VersionFilter should be included if specific version/s of the App are required.

JSON representation
{
  "minVersion": integer,
  "maxVersion": integer
}
Fields
minVersion

integer

Min version code or 0, inclusive.

maxVersion

integer

Max version code, inclusive. The range considered is [minVersion:maxVersion]. A null range implies any version. Examples: To specify a single version use: [target_version:target_version]. To specify any version leave minVersion and maxVersion unspecified. To specify all versions until maxVersion, leave minVersion unspecified. To specify all versions from minVersion, leave maxVersion unspecified.

UrlTypeHint

Different types of url hints.

Enums
URL_TYPE_HINT_UNSPECIFIED Unspecified
AMP_CONTENT URL that points directly to AMP content, or to a canonical URL which refers to AMP content via <link rel="amphtml">.

ActionMetadata

Related Metadata per action.

JSON representation
{
  "expireTime": string
}
Fields
expireTime

string (Timestamp format)

time when this action will expire.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

Disclosure

A product, service or policy disclosure that may be presented to the user.

JSON representation
{
  "title": string,
  "disclosureText": {
    object (DisclosureText)
  },
  "presentationOptions": {
    object (DisclosurePresentationOptions)
  }
}
Fields
title

string

Title of the disclosure. Example: "Safety information".

disclosureText

object (DisclosureText)

Content of the disclosure. Weblinks are allowed.

presentationOptions

object (DisclosurePresentationOptions)

Presentation options for the disclosure.

DisclosureText

Represents a plain text with web links.

JSON representation
{
  "template": string,
  "textLinks": [
    {
      object (TextLink)
    }
  ]
}
Fields
template

string

Text to display, containing placeholders like "{0}" and "{1}" for each textlink that should be inserted. Example: "WARNING: This product can expose you to chemicals which are known to the state of California to cause cancer. For more information go to {0}." This disclosure text must not contain any promotional or ad-like content.

DisclosurePresentationOptions

Options for the presentation of a disclosure.

JSON representation
{
  "presentationRequirement": enum (PresentationRequirement),
  "initiallyExpanded": boolean
}
Fields
presentationRequirement

enum (PresentationRequirement)

Presentation requirement of the disclosure.

initiallyExpanded

boolean

Whether the content of the disclosure should be initially expanded. By default, it is initially collapsed.

PresentationRequirement

Requirement for the presentation of the disclosure.

Enums
REQUIREMENT_UNSPECIFIED Unspecified requirement. Should not set this explicitly.
REQUIREMENT_OPTIONAL The disclosure is optional. It can be skipped if the device does not supporting showing disclosures.
REQUIREMENT_REQUIRED The disclosure is required. The conversation will be punt to phone if the device does not support showing disclosures.

PurchaseItemExtension

Line item contents of Purchase Vertical.

JSON representation
{
  "status": enum (PurchaseStatus),
  "userVisibleStatusLabel": string,
  "type": enum (PurchaseType),
  "productId": string,
  "quantity": integer,
  "unitMeasure": {
    object (MerchantUnitMeasure)
  },
  "returnsInfo": {
    object (PurchaseReturnsInfo)
  },
  "fulfillmentInfo": {
    object (PurchaseFulfillmentInfo)
  },
  "itemOptions": [
    {
      object (ItemOption)
    }
  ],
  "productDetails": {
    object (ProductDetails)
  },
  "extension": {
    "@type": string,
    field1: ...,
    ...
  }
}
Fields
status

enum (PurchaseStatus)

Required: Line item level status.

userVisibleStatusLabel

string

Required: User visible label/string for the status. Max allowed length is 50 chars.

type

enum (PurchaseType)

Required: type of purchase.

productId
(deprecated)

string

Product or offer id associated with this line item.

quantity

integer

Quantity of the item.

unitMeasure

object (MerchantUnitMeasure)

Unit measure. Specifies the size of the item in chosen units. The size, together with the active price is used to determine the unit price.

returnsInfo

object (PurchaseReturnsInfo)

Returns info for this line item. If unset, this line item inherits order level returns info.

fulfillmentInfo

object (PurchaseFulfillmentInfo)

Fulfillment info for this line item. If unset, this line item inherits order level fulfillment info.

itemOptions[]

object (ItemOption)

Additional add-ons or sub-items.

productDetails

object (ProductDetails)

Details about the product.

extension
(deprecated)

object

Any extra fields exchanged between merchant and google. Note: Use of this extension is highly discouraged. Based on the use-case/circumstances, consider one of the following: 1. Define fields in the PurchaseItemExtension if it could be used for other use-cases (ie. generic capability/functionality). 2. Use vertical_extension if it is specific to a custom, non-generic use-case/feature.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

PurchaseStatus

Purchase status associated with a purchase order or a particular line item.

Enums
PURCHASE_STATUS_UNSPECIFIED Status unspecified.
READY_FOR_PICKUP Ready for pick up.
SHIPPED Shipped.
DELIVERED Delivered.
OUT_OF_STOCK Out of stock.
IN_PREPARATION "IN_PREPARATION" could have different meaning in different context. For FOOD order it could be food is being prepared. For Retail, it could be an item is being packaged.
CREATED Order is created.
CONFIRMED The merchant confirmed the order.
REJECTED Merchant rejected the order or line item.
RETURNED The Item was returned by user.
CANCELLED The order or line item was cancelled by user.
CHANGE_REQUESTED User has requested a change to the order, and the integrator is processing this change. The order should be moved to another state after the request is handled.

PurchaseType

The purchase category.

Enums
PURCHASE_TYPE_UNSPECIFIED Unknown value.
RETAIL It includes purchases like physical goods.
FOOD It includes food order purchase.
GROCERY Grocery purchase.
MOBILE_RECHARGE Prepaid mobile recharge purchase.

MerchantUnitMeasure

Merchant unit pricing measure.

JSON representation
{
  "measure": number,
  "unit": enum (Unit)
}
Fields
measure

number

Value: Example 1.2.

unit

enum (Unit)

Unit: Example POUND, GRAM.

Unit

Enums
UNIT_UNSPECIFIED Unit unspecified.
MILLIGRAM Milligram.
GRAM Gram.
KILOGRAM Kilogram.
OUNCE Ounce.
POUND Pound.

PurchaseReturnsInfo

Returns info associated with an order or a particular line item.

JSON representation
{
  "isReturnable": boolean,
  "daysToReturn": integer,
  "policyUrl": string
}
Fields
isReturnable

boolean

If true, return is allowed.

daysToReturn

integer

Return is allowed within that many days.

policyUrl

string

Link to the return policy.

PurchaseFulfillmentInfo

Fulfillment info associated with a purchase order or a particular line item.

JSON representation
{
  "id": string,
  "fulfillmentType": enum (Type),
  "expectedFulfillmentTime": {
    object (Time)
  },
  "expectedPreparationTime": {
    object (Time)
  },
  "location": {
    object (Location)
  },
  "expireTime": string,
  "price": {
    object (PriceAttribute)
  },
  "fulfillmentContact": {
    object (UserInfo)
  },
  "shippingMethodName": string,
  "storeCode": string,
  "pickupInfo": {
    object (PickupInfo)
  }
}
Fields
id

string

Unique identifier for this service option.

fulfillmentType

enum (Type)

Required: The type of fulfillment.

expectedFulfillmentTime

object (Time)

A window if a time-range is specified or ETA if single time specified. Expected delivery or pickup time.

expectedPreparationTime

object (Time)

A window if a time-range is specified or ETA if single time specified. Expected time to prepare the food. Single-time preferred.

location

object (Location)

Pickup or delivery location.

expireTime

string (Timestamp format)

time at which this fulfillment option expires.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".

price

object (PriceAttribute)

Cost of this option.

fulfillmentContact

object (UserInfo)

User contact for this fulfillment.

shippingMethodName

string

name of the shipping method selected by the user.

storeCode

string

StoreCode of the location. Example: Walmart is the merchant and storeCode is the walmart store where fulfillment happened. https://support.google.com/business/answer/3370250?ref_topic=4596653.

pickupInfo

object (PickupInfo)

Additional information regarding how order would be picked. This field would only be applicable when fulfillment type is PICKUP.

Type

Fulfillment type.

Enums
TYPE_UNSPECIFIED type unspecified.
DELIVERY This order will be delivered.
PICKUP This order needs to be picked up.

Time

time construct to represent time of an event to use when displaying an order to the user.

JSON representation
{
  "timeIso8601": string
}
Fields
timeIso8601

string

Represents an order-event time like reservation time, delivery time and so on. Could be a duration (start & end time), just the date, date time etc. Refer https://en.wikipedia.org/wiki/ISO_8601 for all supported formats.

PickupInfo

Details about how an order is picked up. It includes details such as pickup type and additional metadata attached with each type, if any.

JSON representation
{
  "pickupType": enum (PickupType),
  "curbsideInfo": {
    object (CurbsideInfo)
  },
  "checkInInfo": [
    {
      object (CheckInInfo)
    }
  ]
}
Fields
pickupType

enum (PickupType)

Pick up method, such as INSTORE, CURBSIDE etc.

curbsideInfo

object (CurbsideInfo)

Details specific to the curbside information. If pickupType is not "CURBSIDE", this field would be ignored.

checkInInfo[]

object (CheckInInfo)

List of various methods supported by partner to support check-in.

PickupType

List of supported pickup types.

Enums
UNSPECIFIED Pick up type unspecified.
INSTORE Pick up food inside the restaurant.
CURBSIDE Park vehicle in a designated spot outside the restaurant and someone would deliver food there.

CurbsideInfo

Details about how curbside order would be facilitated.

JSON representation
{
  "curbsideFulfillmentType": enum (CurbsideFulfillmentType),
  "userVehicle": {
    object (Vehicle)
  }
}
Fields
curbsideFulfillmentType

enum (CurbsideFulfillmentType)

Partners need additional information to facilitate curbside pickup orders. Depending upon what fulfillment type is chosen, corresponding details would be collected from the user.

userVehicle

object (Vehicle)

Vehicle details of the user placing the order.

CurbsideFulfillmentType

Possible values of curbside fulfillment types.

Enums
UNSPECIFIED Curbside fulfillment type unspecified.
VEHICLE_DETAIL Vehicle detail required to facilitate curbside pickup.

Vehicle

Details about a vehicle

JSON representation
{
  "make": string,
  "model": string,
  "licensePlate": string,
  "colorName": string,
  "image": {
    object (Image)
  }
}
Fields
make

string

Vehicle make (e.g. "Honda"). This is displayed to the user and must be localized. Required.

model

string

Vehicle model (e.g. "Grom"). This is displayed to the user and must be localized. Required.

licensePlate

string

Vehicle license plate number (e.g. "1ABC234"). Required.

colorName

string

Vehicle color name, eg. black Optional.

image

object (Image)

URL to a photo of the vehicle. The photo will be displayed at approximately 256x256px. Must be a jpg or png. Optional.

CheckInInfo

Metadata required by partner to support a checkin method.

JSON representation
{
  "checkInType": enum (CheckInType)
}
Fields
checkInType

enum (CheckInType)

method used to send checkin instructions.

CheckInType

Various methods used to send checkin instructions.

Enums
CHECK_IN_TYPE_UNSPECIFIED Unknown value.
EMAIL CheckIn information would be sent by email.
SMS CheckIn information would be sent by SMS.

ItemOption

Represents add-ons or sub-items.

JSON representation
{
  "id": string,
  "name": string,
  "prices": [
    {
      object (PriceAttribute)
    }
  ],
  "note": string,
  "quantity": integer,
  "productId": string,
  "subOptions": [
    {
      object (ItemOption)
    }
  ]
}
Fields
id

string

For options that are items, unique item id.

name

string

Option name.

prices[]

object (PriceAttribute)

Option total price.

note

string

Note related to the option.

quantity

integer

For options that are items, quantity.

productId

string

Product or offer id associated with this option.

subOptions[]

object (ItemOption)

To define other nested sub options.

ProductDetails

Details about the product.

JSON representation
{
  "productId": string,
  "gtin": string,
  "plu": string,
  "productType": string,
  "productAttributes": {
    string: string,
    ...
  }
}
Fields
productId

string

Product or offer id associated with this line item.

gtin

string

Global Trade Item Number of the product. Useful if offerId is not present in Merchant Center. Optional.

plu

string

Price look-up codes, commonly called PLU codes, PLU numbers, PLUs, produce codes, or produce labels, are a system of numbers that uniquely identify bulk produce sold in grocery stores and supermarkets.

productType

string

Product category defined by the merchant. E.g. "Home > Grocery > Dairy & Eggs > Milk > Whole Milk"

productAttributes

map (key: string, value: string)

Merchant-provided details about the product, e.g. { "allergen": "peanut" }. Useful if offerId is not present in Merchant Center. Optional.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

ReservationItemExtension

Line item contents for reservation orders like restaurant, haircut etc.

JSON representation
{
  "status": enum (ReservationStatus),
  "userVisibleStatusLabel": string,
  "type": enum (ReservationType),
  "reservationTime": {
    object (Time)
  },
  "userAcceptableTimeRange": {
    object (Time)
  },
  "confirmationCode": string,
  "partySize": integer,
  "staffFacilitators": [
    {
      object (StaffFacilitator)
    }
  ],
  "location": {
    object (Location)
  }
}
Fields
status

enum (ReservationStatus)

Required: Reservation status.

userVisibleStatusLabel

string

Required: User visible label/string for the status. Max allowed length is 50 chars.

type

enum (ReservationType)

type of reservation. May be unset if none of the type options is applicable.

reservationTime

object (Time)

time when the service/event is scheduled to occur. Can be a time range, a date, or an exact date time.

userAcceptableTimeRange

object (Time)

time range that is acceptable to the user.

confirmationCode

string

Confirmation code for this reservation.

partySize

integer

The number of people.

staffFacilitators[]

object (StaffFacilitator)

Staff facilitators who will be servicing the reservation. Ex. The hairstylist.

location

object (Location)

Location of the service/event.

ReservationStatus

Status of reservation.

Enums
RESERVATION_STATUS_UNSPECIFIED Unspecified status.
PENDING The reservation is pending.
CONFIRMED The reservation is confirmed.
CANCELLED The reservation is cancelled by the user.
FULFILLED The reservation is fulfilled.
CHANGE_REQUESTED Change of reservation is requested
REJECTED Reservation either expired or rejected by integrator.

ReservationType

type of reservation.

Enums
RESERVATION_TYPE_UNSPECIFIED Unspecified type.
RESTAURANT Reservation for restaurant.
HAIRDRESSER Reservation for hairdresser.

StaffFacilitator

Information about service person.

JSON representation
{
  "name": string,
  "image": {
    object (Image)
  }
}
Fields
name

string

The staff facilitator's name. Ex. "John Smith"

image

object (Image)

Performer's images.

PaymentData

Payment data related to an order.

JSON representation
{
  "paymentResult": {
    object (PaymentResult)
  },
  "paymentInfo": {
    object (PaymentInfo)
  }
}
Fields
paymentResult

object (PaymentResult)

Payment result that's used by integrator for completing a transaction. This field will be populated by actions on Google if the checkout experience is managed by actions-on-Google.

paymentInfo

object (PaymentInfo)

Payment information regarding the order that's useful for user facing interaction.

PaymentResult

Payment result used by integrator for completing a transaction.

JSON representation
{

  // Union field result can be only one of the following:
  "googlePaymentData": string,
  "merchantPaymentMethodId": string
  // End of list of possible types for union field result.
}
Fields
Union field result. Either google payment data or merchant payment method is provided. result can be only one of the following:
googlePaymentData

string

Google provided payment method data. If your payment processor is listed as Google supported payment processor here: https://developers.google.com/pay/api/ Navigate to your payment processor through the link to find out more details. Otherwise, refer to following documentation for payload details. https://developers.google.com/pay/api/payment-data-cryptography

merchantPaymentMethodId

string

Merchant/Action provided payment method chosen by user.

PaymentInfo

Payment information regarding the order being made. This proto captures information that's useful for user facing interaction.

JSON representation
{
  "paymentMethodDisplayInfo": {
    object (PaymentMethodDisplayInfo)
  },
  "paymentMethodProvenance": enum (PaymentMethodProvenance)
}
Fields
paymentMethodDisplayInfo

object (PaymentMethodDisplayInfo)

The display info of the payment method used for the transaction.

paymentMethodProvenance

enum (PaymentMethodProvenance)

Provenance of the payment method used for the transaction. User may have registered the same payment method with both google and merchant.

PaymentMethodDisplayInfo

Payment result used by integrator for completing a transaction.

JSON representation
{
  "paymentType": enum (PaymentType),
  "paymentMethodDisplayName": string,
  "paymentMethodVoiceName": string
}
Fields
paymentType

enum (PaymentType)

The type of the payment.

paymentMethodDisplayName

string

User visible name of the payment method. For example, VISA **** 1234 Checking acct **** 5678

paymentMethodVoiceName

string

Payment method name to be spoken out to the user for voice-only assistant devices. For example, "visa ending in one two three four", or "checking account ending in five six seven eight". Note: This is the voice-optimized string to be used instead of the paymentMethodDisplayName for voice-only assistant devices. If this string is not set, paymentMethodDisplayName will instead be spoken out to the user.

PaymentType

PaymentType indicates the form of payment used for Merchant-provided payment method. Action must also provide a display name for the payment method.

Enums
PAYMENT_TYPE_UNSPECIFIED Unspecified payment type.
PAYMENT_CARD A credit/debit or prepaid card.
BANK Payment method is a bank account.
LOYALTY_PROGRAM Payment method is a loyalty program.
CASH Payment method is cash.
GIFT_CARD Payment method is a gift card.
WALLET Third party wallet, i.e. Paypal

PaymentMethodProvenance

Represents the Payment method provenance used for the transaction.

Enums
PAYMENT_METHOD_PROVENANCE_UNSPECIFIED Provenance is Unspecified.
PAYMENT_METHOD_PROVENANCE_GOOGLE Provenance is Google.
PAYMENT_METHOD_PROVENANCE_MERCHANT Provenance is Merchant.

Promotion

Promotions/Offers that were added to the cart.

JSON representation
{
  "coupon": string
}
Fields
coupon

string

Required: Coupon code applied to this offer.

PurchaseOrderExtension

Order extension for purchase vertical. These properties are applicable to all line items inside order, unless overridden in a line item.

JSON representation
{
  "status": enum (PurchaseStatus),
  "userVisibleStatusLabel": string,
  "type": enum (PurchaseType),
  "returnsInfo": {
    object (PurchaseReturnsInfo)
  },
  "fulfillmentInfo": {
    object (PurchaseFulfillmentInfo)
  },
  "purchaseLocationType": enum (PurchaseLocationType),
  "errors": [
    {
      object (PurchaseError)
    }
  ],
  "extension": {
    "@type": string,
    field1: ...,
    ...
  }
}
Fields
status

enum (PurchaseStatus)

Required: Overall Status for the order.

userVisibleStatusLabel

string

User visible label/string for the status. Max allowed length is 50 chars.

type

enum (PurchaseType)

Required: type of purchase.

returnsInfo

object (PurchaseReturnsInfo)

Return info for the order.

fulfillmentInfo

object (PurchaseFulfillmentInfo)

Fulfillment info for the order.

purchaseLocationType

enum (PurchaseLocationType)

Location of the purchase (in-store / online)

errors[]

object (PurchaseError)

Optional: Errors because of which this order was rejected.

extension
(deprecated)

object

Any extra fields exchanged between merchant and google. Note: Use of this extension is highly discouraged. Based on the use-case/circumstances, consider one of the following: 1. Define fields in the PurchaseOrderExtension if it could be used for other use-cases (ie. generic capability/functionality). 2. Use vertical_extension if it is specific to a custom, non-generic use-case/feature.

An object containing fields of an arbitrary type. An additional field "@type" contains a URI identifying the type. Example: { "id": 1234, "@type": "types.example.com/standard/id" }.

PurchaseLocationType

Location type of the purchase.

Enums
UNSPECIFIED_LOCATION Unknown value.
ONLINE_PURCHASE All purchases bought online.
INSTORE_PURCHASE All instore purchases.

PurchaseError

Errors that a purchase order can be rejected for.

JSON representation
{
  "type": enum (ErrorType),
  "description": string,
  "entityId": string,
  "updatedPrice": {
    object (PriceAttribute)
  },
  "availableQuantity": integer
}
Fields
type

enum (ErrorType)

Required: This represents the granular reason why an order gets rejected by the merchant.

description

string

Additional error description.

entityId

string

Entity Id that corresponds to the error. Example this can correspond to LineItemId / ItemOptionId.

updatedPrice

object (PriceAttribute)

Relevant in case of PRICE_CHANGED / INCORRECT_PRICE error type.

availableQuantity

integer

Available quantity now. Applicable in case of AVAILABILITY_CHANGED.

ErrorType

Possible error types.

Enums
ERROR_TYPE_UNSPECIFIED Unknown error
NOT_FOUND Entity not found, could be Item, FulfillmentOption, Promotion. Entity ID required.
INVALID Entity data not valid. could be Item, FulfillmentOption, Promotion. Entity ID required.
AVAILABILITY_CHANGED Item unavailable, or insufficient items to fulfill the request. Entity ID required.
PRICE_CHANGED Item price different from price in Item entity. Entity ID and updated price required.
INCORRECT_PRICE Price errors in Fees, Total. Entity ID and updated price required.
REQUIREMENTS_NOT_MET Constraints for accepting order not met - minimum basket size etc.,.
TOO_LATE FulfillmentOption expired.
NO_CAPACITY No available service capacity. Use this error code if none of the more fine grained error types are applicable.
NO_COURIER_AVAILABLE No delivery courier could be found. A fine-grained error type that may be categorized as NO_CAPACITY.
INELIGIBLE User in-eligible to place order (blacklisted).
OUT_OF_SERVICE_AREA Unable to deliver to requested address due to border rules etc.
CLOSED Restaurant is closed for business at ordering time.
PROMO_NOT_APPLICABLE Generic error code to catch all cases of failure to apply promo code, if none of the ones below fit. Add promo code as Entity Id.
PROMO_NOT_RECOGNIZED The coupon code was not recognized by partner. Add promo code as Entity Id.
PROMO_EXPIRED Could not apply as promotion expired. Add promo code as Entity Id.
PROMO_USER_INELIGIBLE The current user is not eligible for this coupon. Add promo code as Entity Id.
PROMO_ORDER_INELIGIBLE The current order is not eligible for this coupon. Add promo code as Entity Id.
UNAVAILABLE_SLOT The order ahead slot is unavailable.
FAILED_PRECONDITION Constraints for accepting order not met - minimum basket size etc.
PAYMENT_DECLINED Invalid payment.
MERCHANT_UNREACHABLE Merchant is not reachable. This helps when a partner is an aggregator and could not reach merchant.
ACCOUNT_LINKING_FAILED Merchant tried to link user google account to an account in their system but encountered an error while doing so.

TicketOrderExtension

Order contents for ticket orders like movie, sports etc.

JSON representation
{
  "ticketEvent": {
    object (TicketEvent)
  }
}
Fields
ticketEvent

object (TicketEvent)

The event applied to all line item tickets.

TicketEvent

Represents a single event.

JSON representation
{
  "type": enum (Type),
  "name": string,
  "description": string,
  "url": string,
  "location": {
    object (Location)
  },
  "eventCharacters": [
    {
      object (EventCharacter)
    }
  ],
  "startDate": {
    object (Time)
  },
  "endDate": {
    object (Time)
  },
  "doorTime": {
    object (Time)
  }
}
Fields
type

enum (Type)

Required: type of the ticket event, e.g. movie, concert.

name

string

Required: name of the event. For example, if the event is a movie, this should be the movie name.

description

string

description of the event.

url

string

Url to the event info.

location

object (Location)

The location where the event is happening, or an organization is located.

eventCharacters[]

object (EventCharacter)

The characters related to this event. It can be directors or actors of a movie event, or performers of a concert, etc.

startDate

object (Time)

Start time.

endDate

object (Time)

End time.

doorTime

object (Time)

Entry time, which might be different from the event start time. e.g. the event starts at 9am, but entry time is 8:30am.

Type

The type of the event.

Enums
EVENT_TYPE_UNKNOWN Unknown event type.
MOVIE Movie.
CONCERT Concert.
SPORTS Sports.

EventCharacter

One event character, e.g. organizer, performer etc.

JSON representation
{
  "type": enum (Type),
  "name": string,
  "image": {
    object (Image)
  }
}
Fields
type

enum (Type)

type of the event character, e.g. actor or director.

name

string

name of the character.

image

object (Image)

Character's images.

Type

Character type.

Enums
TYPE_UNKNOWN Unknown type.
ACTOR Actor.
PERFORMER Performer.
DIRECTOR Director.
ORGANIZER Organizer.

UserNotification

Optional user notification to display as part of the Order update.

JSON representation
{
  "title": string,
  "text": string
}
Fields
title

string

The title for the user notification. Max allowed length is 30 chars.

text

string

The contents of the notification. Max allowed length is 100 chars.

Expected

Describes the expectations for the next dialog turn.

JSON representation
{
  "speech": [
    string
  ],
  "languageCode": string
}
Fields
speech[]

string

List of phrases the Action expects from the user's utterance for speech biasing. Up to 1000 phrases are allowed. Note: This field has the same meaning as ExpectedInput.speech_biasing_hints in the v2 API.

languageCode

string

Expected language (in BCP-47 format) of user's next input. For a list of supported languages, see https://developers.google.com/assistant/console/languages-locales