Method: accounts.orders.applyOrderUpdate

Processes an update to an order managed by a given store builder for a given merchant account.

HTTP request

POST https://merchantapi.googleapis.com/youtubeshoppingcheckout/v1alpha/{parent=accounts/*/orders/*}:applyOrderUpdate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
parent

string

Required. Path segments consisting of the ids to identify the order. * The account is the Merchant Center Merchant ID the order was placed with. * The order ID identifying the order in the merchant's and store builder's system. The order ID must be unique for the specified merchant and be constructed in the following way: {store_builder}~{orderId} where the store builder is the Merchant Center Merchant ID of the store builder that manages the order in their system and the id for this order. Format: accounts/{account}/orders/{order}

Request body

The request body contains data with the following structure:

JSON representation 
{
  "updateTime": string,
  "orderUpdate": {
    object (OrderUpdate)
  },
  "lineItemUpdates": [
    {
      object (LineItemUpdate)
    }
  ]
}
Fields
updateTime

string (Timestamp format)

Required. Time at which the update occurred at the store builder's system. Can be used to order the updates. Time must be set in the past.
orderUpdate

object (OrderUpdate)

Optional. All update information referring to the full order. Attributes specified in this object are not just related to an individual item but also concerned with the whole order and all items.
lineItemUpdates[]

object (LineItemUpdate)

Optional. The list of line items and their corresponding update information. Attributes specified in this list are only relevant to the corresponding individual item.

Response body

If successful, the response body is empty.

Authorization scopes

Requires the following OAuth scope:

  • https://www.googleapis.com/auth/content

For more information, see the OAuth 2.0 Overview.

OrderUpdate

Update data that is related to the full order. Required combinations of fields can vary based on the scenario.

JSON representation 
{
  "status": enum (OrderStatus),
  "checkoutToken": string,
  "totalAmount": {
    object (Price)
  },
  "shippingFee": {
    object (Price)
  },
  "discount": {
    object (Price)
  },
  "tax": {
    object (Price)
  },
  "totalRefundAmount": {
    object (Price)
  },
  "orderManagementUri": string
}
Fields
status

enum (OrderStatus)

Optional. New status the full order is updated to. For a status directly related to a single line item, the status is specified in the line item update object. Either order status or the line item status is required.
checkoutToken

string

Optional. The checkout token is generated by the merchant and identifies a unique checkout at both YouTube and the merchant system. The token is required for order confirmation updates to correlate the converted order with the corresponding checkout.
totalAmount

object (Price)

Optional. The amount that was paid for this order. Required for order confirmation updates.
shippingFee

object (Price)

Optional. The cost of shipping for this order. Required for order confirmation if there is any shipping cost.
discount

object (Price)

Optional. The total amount of discounts applied for this order. Required for order confirmation if any discounts have been applied.
tax

object (Price)

Optional. The tax part of this order. Required for order confirmation if tax needs to be disclosed.
totalRefundAmount

object (Price)

Optional. The total amount that was refunded. Required for refund updates.
orderManagementUri

string

Optional. URI to the store builder’s or merchant’s page where the order status can be viewed and the order can be managed, for example canceled. If the user clicks on “Manage Order” on the order history, the webpage of this URI is loaded inside YouTube in a full-screen view.

OrderStatus

Defines an enum representing status at order level.

Enums
ORDER_STATUS_UNSPECIFIED Order status is unspecified. Should not be used.
CONFIRMED Order status is confirmed. This will transform the checkout to an order. Specify the checkout token in this update for correlation with the checkout.

LineItemUpdate

Update data that is related to a specific line item in an order.

JSON representation 
{
  "status": enum (LineItemStatus),
  "lineItem": string,
  "product": string,
  "quantity": string,
  "price": {
    object (Price)
  },
  "shippingCarrier": string,
  "shippingTrackingNumber": string,
  "shippingTrackingUri": string,
  "deliveryTime": string,
  "cancellationReason": enum (CancellationReason),
  "cancellationReasonOtherText": string,
  "returnReason": enum (ReturnReason),
  "returnReasonOtherText": string,
  "returnCancellationReason": enum (ReturnCancellationReason),
  "returnRejectionReason": enum (ReturnRejectionReason),
  "exchangeReason": enum (ExchangeReason),
  "exchangeReasonOtherText": string,
  "exchangeCancellationReason": enum (ExchangeCancellationReason),
  "exchangeRejectionReason": enum (ExchangeRejectionReason),
  "refundAmount": {
    object (Price)
  },

  // Union field estimated_delivery_time can be only one of the following:
  "estimatedDeliveryDateTime": string,
  "estimatedDeliveryTimeInterval": {
    object (Interval)
  },
  "estimatedDeliveryDateInterval": {
    object (DateInterval)
  }
  // End of list of possible types for union field estimated_delivery_time.
}
Fields
status

enum (LineItemStatus)

Optional. New status the line item is updated to. Either this status in the line item update, or the status in the order update needs to be specified for the update to be applied successfully.
lineItem

string

Required. A unique identifier provided by the merchant that allows the line item to be identified uniquely inside this order.
product

string

Optional. The identifier for the individual product, assigned by the merchant. Required for order confirmation. Referenced as product id or ID in the Merchant Center. Has to be unique for each variant of a product. For more information, also see the product ID guide.
quantity

string (int64 format)

Optional. Quantity of this line item in this order.
price

object (Price)

Optional. Price the customer paid for a unit of this line item.
shippingCarrier

string

Optional. Unique identifier of the shipping carrier selected for the item shipment, return shipment or exchange shipments.
shippingTrackingNumber

string

Optional. Number the shipping carrier uses to track the package.
shippingTrackingUri

string

Optional. URI the customer can visit to get information about the shipment this line item is a part of.
deliveryTime

string (Timestamp format)

Optional. Point in time when the order was delivered.
cancellationReason

enum (CancellationReason)

Optional. Reason for which the line item gets canceled. For more information, see the article about order updates.
cancellationReasonOtherText

string

Optional. Additional explanation of why the order was canceled in case cancellation reason was set to "OTHER". For more information, see the article about order updates.
returnReason

enum (ReturnReason)

Optional. The reason for which the line item gets returned. For more information, see the article about order updates.
returnReasonOtherText

string

Optional. Additional explanation of why the order was returned in case return reason was set to "OTHER". For more information, see the article about order updates.
returnCancellationReason

enum (ReturnCancellationReason)

Optional. The reason for which the line item return gets canceled. For more information, see the article about order updates.
returnRejectionReason

enum (ReturnRejectionReason)

Optional. The reason for which the line item return gets rejected. For more information, see the article about order updates.
exchangeReason

enum (ExchangeReason)

Optional. The reason for which the line item gets exchanged. For more information, see the article about order updates.
exchangeReasonOtherText

string

Optional. Free text field when the merchant chose the reason OTHER for exchange.
exchangeCancellationReason

enum (ExchangeCancellationReason)

Optional. The reason for which the line item exchange gets canceled. For more information, see the article about order updates.
exchangeRejectionReason

enum (ExchangeRejectionReason)

Optional. The reason for which the line item exchange gets rejected. For more information, see the article about order updates.
refundAmount

object (Price)

Optional. Amount that is getting refunded to the buyer for this item, due to cancellation or return or other events.
Union field estimated_delivery_time. The estimated time or time range of when the line item is expected to be delivered at the destination. estimated_delivery_time can be only one of the following:
estimatedDeliveryDateTime

string (Timestamp format)

Optional. Estimated delivery date and time.
estimatedDeliveryTimeInterval

object (Interval)

Optional. Estimated delivery time interval, where the shipment should not arrive before the start time and not arrive after the end time. Should be used when dates and times are communicated to the consumer. For example, "7th May 10am - 8th May 6pm" or when the days are tied to timezones.
estimatedDeliveryDateInterval

object (DateInterval)

Optional. Estimated delivery date interval, where the shipment should not arrive before the start date and not arrive after the end date. Should be used when full days are communicated to the consumer. For example, "7th May - 9th May".

DateInterval

Represents an interval of time inclusive of both the start date and the end date. If one or both are omitted, then the interval is assumed to extend indefinitely into the past or future.

JSON representation 
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
Fields
startDate

object (Date)

Optional. Start date inclusive
endDate

object (Date)

Optional. End date inclusive

LineItemStatus

Defines an enum representing status at order line item.

Enums
LINE_ITEM_STATUS_UNSPECIFIED Line item status is unspecified. Should not be used.
IN_TRANSIT Line item is dispatched from origin and on its way to the customer.
IN_SHIPMENT_DELAYED Line item shipping takes more time than estimated due to some reason.
OUT_FOR_DELIVERY Line item is in the last leg of the delivery and should arrive on the day of the event.
DELIVERED Line item arrived at the customer's address.
CANCELED Line item is canceled by the customer or by the merchant.
RETURN_REQUESTED A return is requested by the customer. Reason needs to be specified in the return reason field.
RETURN_ACCEPTED The return is accepted by the merchant.
RETURN_REJECTED The return request is rejected by the merchant.
RETURN_PROCESSING The return is getting processed.
RETURN_COMPLETED The item is returned successfully to the merchant.
RETURN_CANCELED The return is canceled.
REFUND_INITIATED A refund process is started.
REFUND_PROCESSING A refund updated occurred after it is started, but it is not completed yet.
REFUND_COMPLETED The customer received the refund amount.
EXCHANGE_REQUESTED An exchange is requested by the customer. Reason for exchange needs to be specified in the exchange reason field.
EXCHANGE_ACCEPTED The exchange is accepted by the merchant.
EXCHANGE_REJECTED The exchange is rejected by the merchant.
EXCHANGE_PROCESSING An exchange updated occurred after it is started, but it is not completed yet.
EXCHANGE_COMPLETED The line item is exchanged successfully.
EXCHANGE_CANCELED The exchange got canceled.

CancellationReason

Defines an enum representing order cancellation reasons.

Enums
CANCELLATION_REASON_UNSPECIFIED Cancellation reason is unspecified. Should not be used.
CANCELED_BY_CUSTOMER Line item is canceled by the customer.
CANCELED_BY_MERCHANT Line item is canceled by the merchant.
PAYMENT_FAILED Line item is canceled as the payment has failed.
OUT_OF_STOCK Line item had to be canceled as it is out of stock and cannot be fulfilled.
SHIPPING_ADDRESS_INVALID Line item had to be canceled as the shipping address is invalid and the shipment cannot be fulfilled.
LATE_DELIVERY Line item is canceled as the delivery is taking too much time.
CHANGE_OF_MIND Line item is canceled as the customer changed their mind about the order.
DUPLICATE_ORDER Line item is canceled as it was ordered multiple times.
FRAUDULENT_ORDER Line item is canceled as it is classified as fraudulent.
INCORRECT_BILLING_INFO Line item is canceled as the related billing information is incorrect.
TECHNICAL_DIFFICULTIES_SHIPPING Line item is canceled as technical difficulties occurred during shipping.
SHIPPING_RESTRICTIONS Line item is canceled as shipping restrictions apply which make it non-viable to ship it.
OTHER Any other reason that is not covered by the alternative reason options. The other text field for the cancellation reason needs to be filled with a descriptive text.

ReturnReason

Defines an enum representing order return reasons.

Enums
RETURN_REASON_UNSPECIFIED Return reason is unspecified. Should not be used.
ITEM_DAMAGED_IN_TRANSIT Return is requested as item was damaged in transit.
INCORRECT_ITEM_RECEIVED Return is requested as wrong item was received by the customer.
MISSING_ITEM Return is requested as some part of the item was missing when it was received by the customer.
WRONG_SIZE Return is requested as the item received by the customer is not the size of the ordered variant.
WRONG_COLOR Return is requested as the item received by the customer is not the color of the ordered variant.
DID_NOT_LIKE_IT Return is requested as the customer does not like the item received.
CHANGE_OF_MIND Return is requested as the customer changed their mind about purchasing the item.
NO_LONGER_NEEDED Return is requested as the customer no longer needs the item.
BETTER_PRICE_FOUND Return is requested as the customer found a better price at a different offer for the item.
ORDERED_BY_MISTAKE Return is requested as the customer placed this order by mistake.
DEFECTIVE_ITEM Return is requested as the customer received a defective item.
ARRIVED_LATE Return is requested as the customer received the item too late.
ORDERED_WRONG_ITEM Return is requested as the customer realized they ordered a wrong item.
WANTS_TO_EXCHANGE Return is requested as the customer would like to exchange the item.
OTHER Any other reason that is not covered by the alternative reason options. The other text field for the return reason needs to be filled with a descriptive text.

ReturnCancellationReason

Defines an enum representing order return cancellation reasons.

Enums
RETURN_CANCELLATION_REASON_UNSPECIFIED Return cancellation reason is unspecified. Should not be used.
RETURN_REQUEST_WITHDRAWN The return is canceled as the return request was withdrawn.
RETURN_REQUEST_CANCELED_BY_MERCHANT The return is canceled by the merchant.
ITEM_ALREADY_SHIPPED_BACK The return is canceled as the item was already shipped back.
REFUND_ALREADY_ISSUED The return is canceled as the refund was already issued.
DUPLICATE_RETURN_REQUEST The return is canceled as the return request for this item was issued multiple times.
ITEM_LOST_IN_TRANSIT The return is canceled as the item got lost in transit.
ITEM_DAMAGED_IN_RETURN_SHIPPING The return is canceled as the item got damaged during the return shipping.
ITEM_NOT_RECEIVED_BY_MERCHANT The return is canceled as the item was never received by the merchant.
CUSTOMER_FAILED_TO_RETURN_ITEM The return is canceled as the customer failed to return the item.
CUSTOMER_FAILED_TO_PROVIDE_SHIPPING_LABEL The return is canceled as the customer failed to provide the shipping label for the return.
RETURN_REQUEST_TIME_LIMIT_EXCEEDED The return is canceled as the time limit for the return exceeded.
RETURN_POLICY_EXCLUSION The return is canceled as the item is excluded from the return policy.
NOT_IN_RESALABLE_CONDITION The return is canceled as the item is not in resalable condition.
NOT_IN_ORIGINAL_PACKAGING The return is canceled as the item is not in its original packaging.
OTHER Any other reason that is not covered by the alternative reason options.

ReturnRejectionReason

Defines an enum representing order return rejection reasons.

Enums
RETURN_REJECTION_REASON_UNSPECIFIED Return rejection reason is unspecified. Should not be used.
RETURN_POLICY_VIOLATION The return is rejected as the return policy is violated.
RETURN_REQUEST_TIME_LIMIT_EXCEEDED The return is rejected as the time limit for returns was already exceeded.
NOT_IN_RESALABLE_CONDITION The return is rejected as the item is not in a resalable condition.
NOT_IN_ORIGINAL_PACKAGING The return is rejected as the item is not in its original packaging.
EXCLUDED_FROM_RETURN_POLICY The return is rejected as the item is excluded from the return policy.
DAMAGED_DURING_RETURN_SHIPPING The return is rejected as the item was damaged during the return shipping.
CUSTOMER_FAILED_TO_RETURN_ITEM The return is rejected as the customer failed to return the item.
CUSTOMER_FAILED_TO_PROVIDE_RETURN_SHIPPING_LABEL The return is rejected as the customer failed to provide the return shipping label.
DUPLICATE_RETURN_REQUEST The return is rejected as there is already a return process for this item.
ITEM_LOST_IN_TRANSIT The return is rejected as the item got lost in transit.
MERCHANT_DECLINED_RETURN_REQUEST The return is rejected as the item got lost in transit.
OTHER Any other reason that is not covered by the alternative reason options.

ExchangeReason

Defines an enum representing order exchange reasons.

Enums
EXCHANGE_REASON_UNSPECIFIED Exchange reason is unspecified. Should not be used.
INCORRECT_ITEM_RECEIVED Exchange is requested as the customer received an incorrect item.
WRONG_SIZE Exchange is requested as the item received by the customer is not the size of the ordered variant.
WRONG_COLOR Exchange is requested as the item received by the customer is not of the color of the ordered variant.
DID_NOT_LIKE_IT Exchange is requested as the customer does not like the item received.
BETTER_VERSION_AVAILABLE Exchange is requested as the customer would like to have a better variant.
ITEM_DAMAGED Exchange is requested as the item the customer received is damaged.
ITEM_DEFECTIVE Exchange is requested as the item the customer received is defective.
ITEM_NOT_AS_DESCRIBED Exchange is requested as the item the customer received is not as described.
ITEM_MISSING_PARTS Exchange is requested as the item the customer received is missing parts.
CUSTOMER_ORDERED_WRONG_ITEM Exchange is requested as customer ordered a wrong item.
CUSTOMER_CHANGED_THEIR_MIND Exchange is requested as customer changed their mind about the purchase.
CUSTOMER_NO_LONGER_NEEDS_ITEM Exchange is requested as customer no longer needs the item.
OTHER Any other reason that is not covered by the alternative reason options. The other text field for the exchange reason needs to be filled with a descriptive text.

ExchangeCancellationReason

Defines an enum representing order exchange cancellation reasons.

Enums
EXCHANGE_CANCELLATION_REASON_UNSPECIFIED Exchange cancellation reason is unspecified. Should not be used.
EXCHANGE_REQUEST_WITHDRAWN The exchange is canceled as the exchange request was withdrawn.
EXCHANGE_REQUEST_CANCELED_BY_MERCHANT The exchange is canceled by the merchant.
ITEM_ALREADY_SHIPPED_BACK The exchange is canceled as the item was already shipped back.
REFUND_ALREADY_ISSUED The exchange is canceled as the refund for the item was already issued.
DUPLICATE_EXCHANGE_REQUEST The exchange is canceled as the exchange request for this item was issued multiple times.
ITEM_LOST_IN_TRANSIT The exchange is canceled as the item got lost in transit.
ITEM_DAMAGED_IN_EXCHANGE_SHIPPING The exchange is canceled as the item got damaged during the exchange shipping.
ITEM_NOT_RECEIVED_BY_MERCHANT The exchange is canceled as the item was never received by the merchant.
CUSTOMER_FAILED_TO_EXCHANGE_ITEM The exchange is canceled as the customer failed to return the item.
CUSTOMER_FAILED_TO_PROVIDE_EXCHANGE_SHIPPING_LABEL The exchange is canceled as the customer failed to provide the shipping label for the exchange.
EXCHANGE_REQUEST_TIME_LIMIT_EXCEEDED The exchange is canceled as the time limit for the exchange exceeded.
EXCHANGE_POLICY_EXCLUSION The exchange is canceled as the item is excluded from the exchange policy.
NOT_IN_RESALABLE_CONDITION The exchange is canceled as the item is not in resalable condition.
NOT_IN_ORIGINAL_PACKAGING The exchange is canceled as the item is not in its original packaging.
OTHER Any other reason that is not covered by the alternative reason options.

ExchangeRejectionReason

Defines an enum representing order exchange rejection reasons.

Enums
EXCHANGE_REJECTION_REASON_UNSPECIFIED Exchange rejection reason is unspecified. Should not be used.
EXCHANGE_POLICY_VIOLATION The exchange is rejected as the exchange policy is violated.
REQUEST_TIME_LIMIT_EXCEEDED The exchange is rejected as the time limit for exchanges was already exceeded.
NOT_IN_RESALABLE_CONDITION The exchange is rejected as the item is not in a resalable condition.
NOT_IN_ORIGINAL_PACKAGING The exchange is rejected as the item is not in its original packaging.
EXCLUDED_FROM_EXCHANGE_POLICY The exchange is rejected as the item is excluded from the exchange policy.
DAMAGED_DURING_EXCHANGE_SHIPPING The exchange is rejected as the item was damaged during the exchange shipping.
CUSTOMER_FAILED_TO_RETURN_ITEM The exchange is rejected as the customer failed to return the item.
CUSTOMER_FAILED_TO_PROVIDE_EXCHANGE_SHIPPING_LABEL The exchange is rejected as the customer failed to provide the exchange shipping label.
DUPLICATE_EXCHANGE_REQUEST The exchange is rejected as there is already an exchange process for this item.
ITEM_LOST_IN_TRANSIT The exchange is rejected as the item got lost in transit.
MERCHANT_DECLINED_EXCHANGE_REQUEST The exchange is rejected as the item got lost in transit.
WANTED_ITEM_NOT_IN_STOCK The exchange is rejected as the item to be exchanged is not in stock.
DEFECTIVE_ITEM The exchange is rejected as the item to be exchanged is defective.
MISSING_PARTS The exchange is rejected as the item to be exchanged is missing parts.
OTHER Any other reason that is not covered by the alternative reason options.