Conversational Actions will be deprecated on June 13, 2023. For more information, see Conversational Actions sunset.

Method: orders.patch

Update Order from 3p to AOG. Returns INVALID_ARGUMENT if the id of the order is empty or does not equal to an existing order.

HTTP request

PATCH https://actions.googleapis.com/v3/orders/{orderUpdate.order.merchantOrderId}

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
orderUpdate.order.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 64 chars.

Request body

The request body contains data with the following structure:

JSON representation
{
  "header": {
    object (OrderRequestHeader)
  },
  "orderUpdate": {
    "type": enum (Type),
    "order": {
      "googleOrderId": 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.
    },
    "updateMask": string,
    "userNotification": {
      object (UserNotification)
    },
    "reason": string
  }
}
Fields
header

object (OrderRequestHeader)

Header for the update order request.

orderUpdate.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.

orderUpdate.order.googleOrderId

string

Google assigned order id.

orderUpdate.order.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.

orderUpdate.order.userVisibleStateLabel
(deprecated)

string

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

orderUpdate.order.buyerInfo

object (UserInfo)

Info about the buyer.

orderUpdate.order.image

object (Image)

Image associated with the order.

orderUpdate.order.createTime

string (Timestamp format)

Required: Date and time the order was created.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

orderUpdate.order.lastUpdateTime

string (Timestamp format)

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

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

orderUpdate.order.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.

orderUpdate.order.contents

object (Contents)

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

orderUpdate.order.priceAttributes[]

object (PriceAttribute)

Price, discounts, taxes and so on.

orderUpdate.order.followUpActions[]

object (Action)

Follow up actions at order level.

orderUpdate.order.paymentData

object (PaymentData)

Payment related data for the order.

orderUpdate.order.termsOfServiceUrl

string

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

orderUpdate.order.note

string

Notes attached to an order.

orderUpdate.order.promotions[]

object (Promotion)

All promotions that are associated with this order.

orderUpdate.order.disclosures[]

object (Disclosure)

Disclosures associated with this order.

orderUpdate.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" }.

orderUpdate.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".

orderUpdate.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.

orderUpdate.reason

string

Reason for the change/update.

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:
orderUpdate.order.purchase

object (PurchaseOrderExtension)

Purchase order

orderUpdate.order.ticket

object (TicketOrderExtension)

Ticket order

Response body

If successful, the response body contains an instance of Order.

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.

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.