We will sunset v2 of the Content API on March 29th, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible. For more information, see Migrating to v2.1.

REST Resource: orders

Resource: Order

Order. Production access (all methods) requires the order manager role. Sandbox access does not.

JSON representation
{
  "id": string,
  "merchantId": string,
  "merchantOrderId": string,
  "kind": string,
  "lineItems": [
    {
      object (OrderLineItem)
    }
  ],
  "status": string,
  "paymentStatus": string,
  "acknowledged": boolean,
  "shippingOption": string,
  "placedDate": string,
  "deliveryDetails": {
    object (OrderDeliveryDetails)
  },
  "customer": {
    object (OrderCustomer)
  },
  "paymentMethod": {
    object (OrderPaymentMethod)
  },
  "shippingCost": {
    object (Price)
  },
  "shippingCostTax": {
    object (Price)
  },
  "netAmount": {
    object (Price)
  },
  "refunds": [
    {
      object (OrderRefund)
    }
  ],
  "shipments": [
    {
      object (OrderShipment)
    }
  ],
  "promotions": [
    {
      object (OrderLegacyPromotion)
    }
  ],
  "channelType": string,
  "taxCollector": string,
  "pickupDetails": {
    object (OrderPickupDetails)
  }
}
Fields
id

string

The REST ID of the order. Globally unique.

merchantId

string

merchantOrderId

string

Merchant-provided ID of the order.

kind

string

Identifies what kind of resource this is. Value: the fixed string "content#order"

lineItems[]

object (OrderLineItem)

Line items that are ordered.

status

string

The status of the order.

Acceptable values are:

  • "canceled"
  • "delivered"
  • "inProgress"
  • "partiallyDelivered"
  • "partiallyReturned"
  • "partiallyShipped"
  • "pendingShipment"
  • "returned"
  • "shipped"

paymentStatus

string

The status of the payment.

Acceptable values are:

  • "paymentCaptured"
  • "paymentRejected"
  • "paymentSecured"
  • "pendingAuthorization"

acknowledged

boolean

Whether the order was acknowledged.

shippingOption

string

Deprecated. Shipping details are provided with line items instead.

Acceptable values are:

  • "economy"
  • "expedited"
  • "oneDay"
  • "sameDay"
  • "standard"
  • "twoDay"

placedDate

string

The date when the order was placed, in ISO 8601 format.

deliveryDetails

object (OrderDeliveryDetails)

Delivery details for shipments of type delivery.

customer

object (OrderCustomer)

The details of the customer who placed the order.

paymentMethod

object (OrderPaymentMethod)

The details of the payment method.

shippingCost

object (Price)

The total cost of shipping for all items.

shippingCostTax

object (Price)

The tax for the total shipping cost.

netAmount

object (Price)

The net amount for the order. For example, if an order was originally for a grand total of $100 and a refund was issued for $20, the net amount will be $80.

refunds[]

object (OrderRefund)

Refunds for the order.

shipments[]

object (OrderShipment)

Shipments of the order.

promotions[]

object (OrderLegacyPromotion)

The details of the merchant provided promotions applied to the order.

To determine which promotions apply to which products, check the Promotions[].Benefits[].OfferIds field against the LineItems[].Product.OfferId field for each promotion. If a promotion is applied to more than 1 offerId, divide the discount value by the number of affected offers to determine how much discount to apply to each offerId.

Examples:

  1. To calculate the line item level discount for a single specific item: For each promotion, subtract the Promotions[].Benefits[].Discount.value amount from the LineItems[].Price.value.
  2. To calculate the line item level discount for multiple quantity of a specific item: For each promotion, divide the Promotions[].Benefits[].Discount.value by the quantity of products and substract it from LineItems[].Product.Price.value for each quantity item.


Only 1 promotion can be applied to an offerId in a given order. To refund an item which had a promotion applied to it, make sure to refund the amount after first subtracting the promotion discount from the item price.

More details about the program are here.

channelType

string

Deprecated.

Acceptable values are:

  • "googleExpress"
  • "purchasesOnGoogle"

taxCollector

string

The party responsible for collecting and remitting taxes.

Acceptable values are:

  • "marketplaceFacilitator"
  • "merchant"

pickupDetails

object (OrderPickupDetails)

Pickup details for shipments of type pickup.

OrderLineItem

JSON representation
{
  "id": string,
  "quantityOrdered": integer,
  "quantityPending": integer,
  "quantityShipped": integer,
  "quantityDelivered": integer,
  "quantityReturned": integer,
  "quantityCanceled": integer,
  "price": {
    object (Price)
  },
  "tax": {
    object (Price)
  },
  "shippingDetails": {
    object (OrderLineItemShippingDetails)
  },
  "returnInfo": {
    object (OrderLineItemReturnInfo)
  },
  "product": {
    object (OrderLineItemProduct)
  },
  "returns": [
    {
      object (OrderReturn)
    }
  ],
  "cancellations": [
    {
      object (OrderCancellation)
    }
  ],
  "annotations": [
    {
      object (OrderMerchantProvidedAnnotation)
    }
  ],
  "quantityReadyForPickup": integer
}
Fields
id

string

The ID of the line item.

quantityOrdered

integer (uint32 format)

Number of items ordered.

quantityPending

integer (uint32 format)

Number of items pending.

quantityShipped

integer (uint32 format)

Number of items shipped.

quantityDelivered

integer (uint32 format)

Number of items delivered.

quantityReturned

integer (uint32 format)

Number of items returned.

quantityCanceled

integer (uint32 format)

Number of items canceled.

price

object (Price)

Total price for the line item. For example, if two items for $10 are purchased, the total price will be $20.

tax

object (Price)

Total tax amount for the line item. For example, if two items are purchased, and each have a cost tax of $2, the total tax amount will be $4.

shippingDetails

object (OrderLineItemShippingDetails)

Details of the requested shipping for the line item.

returnInfo

object (OrderLineItemReturnInfo)

Details of the return policy for the line item.

product

object (OrderLineItemProduct)

Product data as seen by customer from the time of the order placement. Note that certain attributes values (e.g. title or gtin) might be reformatted and no longer match values submitted via product feed.

returns[]

object (OrderReturn)

Returns of the line item.

cancellations[]

object (OrderCancellation)

Cancellations of the line item.

annotations[]

object (OrderMerchantProvidedAnnotation)

Annotations that are attached to the line item.

quantityReadyForPickup

integer (uint32 format)

Number of items ready for pickup.

OrderLineItemShippingDetails

JSON representation
{
  "method": {
    object (OrderLineItemShippingDetailsMethod)
  },
  "shipByDate": string,
  "deliverByDate": string,
  "type": string
}
Fields
method

object (OrderLineItemShippingDetailsMethod)

Required. Details of the shipping method.

shipByDate

string

Required. The ship by date, in ISO 8601 format.

deliverByDate

string

Required. The delivery by date, in ISO 8601 format.

type

string

Type of shipment. Indicates whether deliveryDetails or pickupDetails is applicable for this shipment.

Acceptable values are:

  • "delivery"
  • "pickup"

OrderLineItemShippingDetailsMethod

JSON representation
{
  "methodName": string,
  "carrier": string,
  "minDaysInTransit": integer,
  "maxDaysInTransit": integer
}
Fields
methodName

string

Required. The name of the shipping method.

carrier

string

The carrier for the shipping. Optional. See shipments[].carrier for a list of acceptable values.

minDaysInTransit

integer (uint32 format)

Required. Minimum transit time.

maxDaysInTransit

integer (uint32 format)

Required. Maximum transit time.

OrderLineItemReturnInfo

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

boolean

Required. Whether the item is returnable.

daysToReturn

integer

Required. How many days later the item can be returned.

policyUrl

string

Required. URL of the item return policy.

OrderReturn

JSON representation
{
  "creationDate": string,
  "actor": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string
}
Fields
creationDate

string

Date on which the item has been created, in ISO 8601 format.

actor

string

The actor that created the refund.

Acceptable values are:

  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googlePayments"
  • "googleSabre"
  • "merchant"

quantity

integer (uint32 format)

Quantity that is returned.

reason

string

The reason for the return.

Acceptable values are:

  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredTooLate"
  • "expiredItem"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "qualityNotAsExpected"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"

reasonText

string

The explanation of the reason.

OrderCancellation

JSON representation
{
  "creationDate": string,
  "actor": string,
  "quantity": integer,
  "reason": string,
  "reasonText": string
}
Fields
creationDate

string

Date on which the cancellation has been created, in ISO 8601 format.

actor

string

The actor that created the cancellation.

Acceptable values are:

  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googlePayments"
  • "googleSabre"
  • "merchant"

quantity

integer (uint32 format)

The quantity that was canceled.

reason

string

The reason for the cancellation. Orders that are canceled with a noInventory reason will lead to the removal of the product from Shopping Actions until you make an update to that product. This will not affect your Shopping ads.

Acceptable values are:

  • "autoPostInternal"
  • "autoPostInvalidBillingAddress"
  • "autoPostNoInventory"
  • "autoPostPriceError"
  • "autoPostUndeliverableShippingAddress"
  • "couponAbuse"
  • "customerCanceled"
  • "customerInitiatedCancel"
  • "customerSupportRequested"
  • "failToPushOrderGoogleError"
  • "failToPushOrderMerchantError"
  • "failToPushOrderMerchantFulfillmentError"
  • "failToPushOrderToMerchant"
  • "failToPushOrderToMerchantOutOfStock"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "merchantDidNotShipOnTime"
  • "noInventory"
  • "orderTimeout"
  • "other"
  • "paymentAbuse"
  • "paymentDeclined"
  • "priceError"
  • "returnRefundAbuse"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"

reasonText

string

The explanation of the reason.

OrderMerchantProvidedAnnotation

JSON representation
{
  "key": string,
  "value": string
}
Fields
key

string

Key for additional merchant provided (as key-value pairs) annotation about the line item.

value

string

Value for additional merchant provided (as key-value pairs) annotation about the line item.

OrderDeliveryDetails

JSON representation
{
  "address": {
    object (OrderAddress)
  },
  "phoneNumber": string
}
Fields
address

object (OrderAddress)

The delivery address

phoneNumber

string

The phone number of the person receiving the delivery.

OrderAddress

JSON representation
{
  "recipientName": string,
  "streetAddress": [
    string
  ],
  "locality": string,
  "region": string,
  "country": string,
  "postalCode": string,
  "isPostOfficeBox": boolean,
  "fullAddress": [
    string
  ]
}
Fields
recipientName

string

Name of the recipient.

streetAddress[]

string

Street-level part of the address.

locality

string

City, town or commune. May also include dependent localities or sublocalities (e.g. neighborhoods or suburbs).

region

string

Top-level administrative subdivision of the country. For example, a state like California ("CA") or a province like Quebec ("QC").

country

string

CLDR country code (e.g. "US").

postalCode

string

Postal Code or ZIP (e.g. "94043").

isPostOfficeBox

boolean

Whether the address is a post office box.

fullAddress[]

string

Strings representing the lines of the printed label for mailing the order, for example:

John Smith
1600 Amphitheatre Parkway
Mountain View, CA, 94043
United States

OrderCustomer

JSON representation
{
  "fullName": string,
  "email": string,
  "explicitMarketingPreference": boolean,
  "marketingRightsInfo": {
    object (OrderCustomerMarketingRightsInfo)
  },
  "invoiceReceivingEmail": string
}
Fields
fullName

string

Full name of the customer.

email

string

Deprecated.

explicitMarketingPreference

boolean

Deprecated. Please use marketingRightsInfo instead.

marketingRightsInfo

object (OrderCustomerMarketingRightsInfo)

Customer's marketing preferences. Contains the marketing opt-in information that is current at the time that the merchant call. User preference selections can change from one order to the next so preferences must be checked with every order.

invoiceReceivingEmail

string

Email address for the merchant to send value-added tax or invoice documentation of the order. Only the last document sent is made available to the customer. For more information, see About automated VAT invoicing for Shopping Actions.

OrderCustomerMarketingRightsInfo

JSON representation
{
  "marketingEmailAddress": string,
  "explicitMarketingPreference": string,
  "lastUpdatedTimestamp": string
}
Fields
marketingEmailAddress

string

Email address that can be used for marketing purposes. The field may be empty even if explicitMarketingPreference is 'granted'. This happens when retrieving an old order from the customer who deleted their account.

explicitMarketingPreference

string

Last known customer selection regarding marketing preferences. In certain cases this selection might not be known, so this field would be empty. If a customer selected granted in their most recent order, they can be subscribed to marketing emails. Customers who have chosen denied must not be subscribed, or must be unsubscribed if already opted-in.

Acceptable values are:

  • "denied"
  • "granted"

lastUpdatedTimestamp

string

Timestamp when last time marketing preference was updated. Could be empty, if user wasn't offered a selection yet.

OrderPaymentMethod

JSON representation
{
  "type": string,
  "lastFourDigits": string,
  "billingAddress": {
    object (OrderAddress)
  },
  "expirationMonth": integer,
  "expirationYear": integer,
  "phoneNumber": string
}
Fields
type

string

The type of instrument.

Acceptable values are:

  • "AMEX"
  • "DISCOVER"
  • "JCB"
  • "MASTERCARD"
  • "UNIONPAY"
  • "VISA"
  • "``"

lastFourDigits

string

The last four digits of the card number.

billingAddress

object (OrderAddress)

The billing address.

expirationMonth

integer

The card expiration month (January = 1, February = 2 etc.).

expirationYear

integer

The card expiration year (4-digit, e.g. 2015).

phoneNumber

string

The billing phone number.

OrderRefund

JSON representation
{
  "creationDate": string,
  "actor": string,
  "amount": {
    object (Price)
  },
  "reason": string,
  "reasonText": string
}
Fields
creationDate

string

Date on which the item has been created, in ISO 8601 format.

actor

string

The actor that created the refund.

Acceptable values are:

  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googlePayments"
  • "googleSabre"
  • "merchant"

amount

object (Price)

The amount that is refunded.

reason

string

The reason for the refund.

Acceptable values are:

  • "adjustment"
  • "autoPostInternal"
  • "autoPostInvalidBillingAddress"
  • "autoPostNoInventory"
  • "autoPostPriceError"
  • "autoPostUndeliverableShippingAddress"
  • "couponAbuse"
  • "courtesyAdjustment"
  • "customerCanceled"
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "customerSupportRequested"
  • "deliveredLateByCarrier"
  • "deliveredTooLate"
  • "expiredItem"
  • "failToPushOrderGoogleError"
  • "failToPushOrderMerchantError"
  • "failToPushOrderMerchantFulfillmentError"
  • "failToPushOrderToMerchant"
  • "failToPushOrderToMerchantOutOfStock"
  • "feeAdjustment"
  • "invalidCoupon"
  • "lateShipmentCredit"
  • "malformedShippingAddress"
  • "merchantDidNotShipOnTime"
  • "noInventory"
  • "orderTimeout"
  • "other"
  • "paymentAbuse"
  • "paymentDeclined"
  • "priceAdjustment"
  • "priceError"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "promoReallocation"
  • "qualityNotAsExpected"
  • "returnRefundAbuse"
  • "shippingCostAdjustment"
  • "shippingPriceError"
  • "taxAdjustment"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"

reasonText

string

The explanation of the reason.

OrderShipment

JSON representation
{
  "id": string,
  "creationDate": string,
  "lineItems": [
    {
      object (OrderShipmentLineItemShipment)
    }
  ],
  "status": string,
  "carrier": string,
  "trackingId": string,
  "deliveryDate": string,
  "scheduledDeliveryDetails": {
    object (OrderShipmentScheduledDeliveryDetails)
  }
}
Fields
id

string

The ID of the shipment.

creationDate

string

Date on which the shipment has been created, in ISO 8601 format.

lineItems[]

object (OrderShipmentLineItemShipment)

The line items that are shipped.

status

string

The status of the shipment.

Acceptable values are:

  • "delivered"
  • "readyForPickup"
  • "shipped"
  • "undeliverable"

carrier

string

The carrier handling the shipment.

For supported carriers, Google includes the carrier name and tracking URL in emails to customers. For select supported carriers, Google also automatically updates the shipment status based on the provided shipment ID.


Supported carriers for US are:
  • "ups" (United Parcel Service) automatic status updates
  • "usps" (United States Postal Service) automatic status updates
  • "fedex" (FedEx) automatic status updates
  • "dhl" (DHL eCommerce) automatic status updates (US only)
  • "ontrac" (OnTrac) automatic status updates
  • "dhl express" (DHL Express)
  • "deliv" (Deliv)
  • "dynamex" (TForce)
  • "lasership" (LaserShip)
  • "mpx" (Military Parcel Xpress)
  • "uds" (United Delivery Service)
  • "efw" (Estes Forwarding Worldwide)
  • "jd logistics" (JD Logistics)
  • "yunexpress" (YunExpress)
  • "china post" (China Post)
  • "china ems" (China Post Express Mail Service)
  • "singapore post" (Singapore Post)
  • "pos malaysia" (Pos Malaysia)
  • "postnl" (PostNL)
  • "ptt" (PTT Turkish Post)
  • "eub" (ePacket)
  • "chukou1" (Chukou1 Logistics)
  • "bestex" (Best Express)
  • "canada post" (Canada Post)
  • "purolator" (Purolator)
  • "canpar" (Canpar)
  • "india post" (India Post)
  • "blue dart" (Blue Dart)
  • "delhivery" (Delhivery)
  • "dtdc" (DTDC)
  • "tpc india" (TPC India)

Supported carriers for FR are:
  • "la poste" (La Poste) automatic status updates
  • "colissimo" (Colissimo by La Poste) automatic status updates
  • "ups" (United Parcel Service) automatic status updates
  • "chronopost" (Chronopost by La Poste)
  • "gls" (General Logistics Systems France)
  • "dpd" (DPD Group by GeoPost)
  • "bpost" (Belgian Post Group)
  • "colis prive" (Colis Privé)
  • "boxtal" (Boxtal)
  • "geodis" (GEODIS)
  • "tnt" (TNT)
  • "db schenker" (DB Schenker)
  • "aramex" (Aramex)

trackingId

string

The tracking ID for the shipment.

deliveryDate

string

Date on which the shipment has been delivered, in ISO 8601 format. Present only if status is delivered

scheduledDeliveryDetails

object (OrderShipmentScheduledDeliveryDetails)

Delivery details of the shipment if scheduling is needed.

OrderShipmentLineItemShipment

JSON representation
{
  "lineItemId": string,
  "quantity": integer,
  "productId": string
}
Fields
lineItemId

string

The ID of the line item that is shipped. This value is assigned by Google when an order is created. Either lineItemId or productId is required.

quantity

integer (uint32 format)

The quantity that is shipped.

productId

string

The ID of the product to ship. This is the REST ID used in the products service. Either lineItemId or productId is required.

OrderShipmentScheduledDeliveryDetails

JSON representation
{
  "scheduledDate": string,
  "carrierPhoneNumber": string
}
Fields
scheduledDate

string

The date a shipment is scheduled for delivery, in ISO 8601 format.

carrierPhoneNumber

string

The phone number of the carrier fulfilling the delivery. The phone number is formatted as the international notation in ITU-T Recommendation E.123 (e.g., "+41 44 668 1800").

OrderLegacyPromotion

JSON representation
{
  "id": string,
  "productApplicability": string,
  "longTitle": string,
  "effectiveDates": string,
  "redemptionChannel": string,
  "genericRedemptionCode": string,
  "benefits": [
    {
      object (OrderLegacyPromotionBenefit)
    }
  ]
}
Fields
id

string

The unique ID of the promotion.

productApplicability

string

Whether the promotion is applicable to all products or only specific products.

Acceptable values are:

  • "allProducts"
  • "specificProducts"

longTitle

string

The full title of the promotion.

effectiveDates

string

The date and time frame when the promotion is active and ready for validation review. Note that the promotion live time may be delayed for a few hours due to the validation review.
Start date and end date are separated by a forward slash (/). The start date is specified by the format (YYYY-MM-DD), followed by the letter ?T?, the time of the day when the sale starts (in Greenwich Mean Time, GMT), followed by an expression of the time zone for the sale. The end date is in the same format.

redemptionChannel

string

Indicates that the promotion is valid online.

Acceptable values are:

  • "online"

genericRedemptionCode

string

Optional. The text code that corresponds to the promotion when applied on the retailer?s website.

benefits[]

object (OrderLegacyPromotionBenefit)

OrderLegacyPromotionBenefit

JSON representation
{
  "offerIds": [
    string
  ],
  "type": string,
  "subType": string,
  "discount": {
    object (Price)
  },
  "taxImpact": {
    object (Price)
  }
}
Fields
offerIds[]

string

The OfferId(s) that were purchased in this order and map to this specific benefit of the promotion.

type

string

Describes whether the promotion applies to products (e.g. 20% off) or to shipping (e.g. Free Shipping).

Acceptable values are:

  • "product"
  • "shipping"

subType

string

Further describes the benefit of the promotion. Note that we will expand on this enumeration as we support new promotion sub-types.

Acceptable values are:

  • "buyMGetMoneyOff"
  • "buyMGetNMoneyOff"
  • "buyMGetNPercentOff"
  • "buyMGetPercentOff"
  • "freeGift"
  • "freeGiftWithItemId"
  • "freeGiftWithValue"
  • "freeOvernightShipping"
  • "freeShipping"
  • "freeTwoDayShipping"
  • "moneyOff"
  • "percentageOff"
  • "rewardPoints"
  • "salePrice"

discount

object (Price)

The discount in the order price when the promotion is applied.

taxImpact

object (Price)

The impact on tax when the promotion is applied.

OrderPickupDetails

JSON representation
{
  "locationId": string,
  "address": {
    object (OrderAddress)
  },
  "collectors": [
    {
      object (OrderPickupDetailsCollector)
    }
  ]
}
Fields
locationId

string

ID of the pickup location.

address

object (OrderAddress)

Address of the pickup location where the shipment should be sent. Note that recipientName in the address is the name of the business at the pickup location.

collectors[]

object (OrderPickupDetailsCollector)

Collectors authorized to pick up shipment from the pickup location.

OrderPickupDetailsCollector

JSON representation
{
  "name": string,
  "phoneNumber": string
}
Fields
name

string

Name of the person picking up the shipment.

phoneNumber

string

Phone number of the person picking up the shipment.

Methods

acknowledge

Marks an order as acknowledged.

advancetestorder

Sandbox only.

cancel

Cancels all line items in an order, making a full refund.

cancellineitem

Cancels a line item, making a full refund.

canceltestorderbycustomer

Sandbox only.

createtestorder

Sandbox only.

createtestreturn

Sandbox only.

custombatch

Retrieves or modifies multiple orders in a single request.

get

Retrieves an order from your Merchant Center account.

getbymerchantorderid

Retrieves an order using merchant order ID.

gettestordertemplate

Sandbox only.

instorerefundlineitem

Deprecated.

list

Lists the orders in your Merchant Center account.

refund

Deprecated, please use returnRefundLineItem instead.

rejectreturnlineitem

Rejects return on an line item.

returnlineitem

Returns a line item.

returnrefundlineitem

Returns and refunds a line item.

setlineitemmetadata

Sets (or overrides if it already exists) merchant provided annotations in the form of key-value pairs.

shiplineitems

Marks line item(s) as shipped.

updatelineitemshippingdetails

Updates ship by and delivery by dates for a line item.

updatemerchantorderid

Updates the merchant order ID for a given order.

updateshipment

Updates a shipment's status, carrier, and/or tracking ID.