REST Resource: orders

{
  "id": string,
  "merchantId": string,
  "merchantOrderId": string,
  "kind": string,
  "lineItems": [
    {
      object (OrderLineItem)
    }
  ],
  "status": string,
  "paymentStatus": string,
  "acknowledged": boolean,
  "placedDate": string,
  "deliveryDetails": {
    object (OrderDeliveryDetails)
  },
  "customer": {
    object (OrderCustomer)
  },
  "shippingCost": {
    object (Price)
  },
  "shippingCostTax": {
    object (Price)
  },
  "refunds": [
    {
      object (OrderRefund)
    }
  ],
  "shipments": [
    {
      object (OrderShipment)
    }
  ],
  "billingAddress": {
    object (OrderAddress)
  },
  "promotions": [
    {
      object (OrderPromotion)
    }
  ],
  "taxCollector": string,
  "netPriceAmount": {
    object (Price)
  },
  "netTaxAmount": {
    object (Price)
  },
  "pickupDetails": {
    object (OrderPickupDetails)
  },
  "annotations": [
    {
      object (OrderOrderAnnotation)
    }
  ]
}

string

The REST ID of the order. Globally unique.

string

string

Merchant-provided ID of the order.

string

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

object (OrderLineItem)

Line items that are ordered.

string

The status of the order.

Acceptable values are:

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

string

The status of the payment.

Acceptable values are:

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

boolean

Whether the order was acknowledged.

string

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

object (OrderDeliveryDetails)

Delivery details for shipments of type delivery.

object (OrderCustomer)

The details of the customer who placed the order.

object (Price)

The total cost of shipping for all items.

object (Price)

The tax for the total shipping cost.

object (OrderRefund)

Refunds for the order.

object (OrderShipment)

Shipments of the order.

object (OrderAddress)

The billing address.

object (OrderPromotion)

Promotions associated with the order.

To determine which promotions apply to which products, check the Promotions[].appliedItems[].lineItemId field against the LineItems[].id 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 price paid by the customer for a single line item including the discount: For each promotion, subtract the LineItems[].adjustments[].priceAdjustment.value amount from the LineItems[].Price.value.
2. To calculate price paid by the customer for a single line item including the discount in case of multiple quantity: For each promotion, divide the LineItems[].adjustments[].priceAdjustment.value by the quantity of products then subtract the resulting value from the 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.

string

The party responsible for collecting and remitting taxes.

Acceptable values are:

• "marketplaceFacilitator"
• "merchant"

object (Price)

The net amount for the order (price part). For example, if an order was originally for $100 and a refund was issued for $20, the net amount will be $80.

object (Price)

The net amount for the order (tax part). Note that in certain cases due to taxable base adjustment netTaxAmount might not match to a sum of tax field across all lineItems and refunds.

object (OrderPickupDetails)

Pickup details for shipments of type pickup.

object (OrderOrderAnnotation)

accounts.list of key-value pairs that are attached to a given order.

{
  "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)
    }
  ],
  "adjustments": [
    {
      object (OrderLineItemAdjustment)
    }
  ],
  "quantityUndeliverable": integer,
  "quantityReadyForPickup": integer
}

string

The ID of the line item.

integer (uint32 format)

Number of items ordered.

integer (uint32 format)

Number of items pending.

integer (uint32 format)

Number of items shipped.

integer (uint32 format)

Number of items delivered.

integer (uint32 format)

Number of items returned.

integer (uint32 format)

Number of items canceled.

object (Price)

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

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.

object (OrderLineItemShippingDetails)

Details of the requested shipping for the line item.

object (OrderLineItemReturnInfo)

Details of the return policy for the line item.

object (OrderLineItemProduct)

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

object (OrderReturn)

Returns of the line item.

object (OrderCancellation)

Cancellations of the line item.

object (OrderMerchantProvidedAnnotation)

Annotations that are attached to the line item.

object (OrderLineItemAdjustment)

Price and tax adjustments applied on the line item.

integer (uint32 format)

Number of items undeliverable.

integer (uint32 format)

Number of items ready for pickup.

{
  "method": {
    object (OrderLineItemShippingDetailsMethod)
  },
  "shipByDate": string,
  "deliverByDate": string,
  "type": string,
  "pickupPromiseInMinutes": integer
}

object (OrderLineItemShippingDetailsMethod)

Required. Details of the shipping method.

string

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

string

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

string

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

Acceptable values are:

• "delivery"
• "pickup"

integer (uint32 format)

The promised time in minutes in which the order will be ready for pickup. This only applies to buy-online-pickup-in-store same-day order.

{
  "methodName": string,
  "carrier": string,
  "minDaysInTransit": integer,
  "maxDaysInTransit": integer
}

string

Required. The name of the shipping method.

string

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

integer (uint32 format)

Required. Minimum transit time.

integer (uint32 format)

Required. Maximum transit time.

{
  "isReturnable": boolean,
  "daysToReturn": integer,
  "policyUrl": string
}

boolean

Required. Whether the item is returnable.

integer

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

string

Required. URL of the item return policy.

{
  "id": string,
  "offerId": string,
  "targetCountry": string,
  "contentLanguage": string,
  "price": {
    object (Price)
  },
  "title": string,
  "gtin": string,
  "brand": string,
  "mpn": string,
  "condition": string,
  "itemGroupId": string,
  "imageLink": string,
  "shownImage": string,
  "variantAttributes": [
    {
      object (OrderLineItemProductVariantAttribute)
    }
  ],
  "fees": [
    {
      object (OrderLineItemProductFee)
    }
  ]
}

string

The REST ID of the product.

string

An identifier of the item.

string

The CLDR territory code of the target country of the product.

string

The two-letter ISO 639-1 language code for the item.

object (Price)

Price of the item.

string

The title of the product.

string

Global Trade Item Number (GTIN) of the item.

string

Brand of the item.

string

Manufacturer Part Number (MPN) of the item.

string

Condition or state of the item.

Acceptable values are:

• "new"
• "refurbished"
• "used"

string

Shared identifier for all variants of the same product.

string

URL of an image of the item.

string

URL to the cached image shown to the user when order was placed.

object (OrderLineItemProductVariantAttribute)

Variant attributes for the item. These are dimensions of the product, such as color, gender, material, pattern, and size. You can find a comprehensive list of variant attributes here.

object (OrderLineItemProductFee)

Associated fees at order creation time.

{
  "dimension": string,
  "value": string
}

string

The dimension of the variant.

string

The value for the dimension.

{
  "name": string,
  "amount": {
    object (Price)
  }
}

string

Name of the fee.

object (Price)

Amount of the fee.

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

string

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

string

The actor that created the refund.

Acceptable values are:

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

integer (uint32 format)

Quantity that is returned.

string

The reason for the return.

Acceptable values are:

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

string

The explanation of the reason.

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

string

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

string

The actor that created the cancellation.

Acceptable values are:

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

integer (uint32 format)

The quantity that was canceled.

string

The reason for the cancellation. Orders that are canceled with a noInventory reason will lead to the removal of the product from Buy on Google until you make an update to that product. This won't 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"
• "failedToCaptureFunds"

string

The explanation of the reason.

{
  "key": string,
  "value": string
}

string

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

string

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

{
  "type": string,
  "priceAdjustment": {
    object (Price)
  },
  "taxAdjustment": {
    object (Price)
  }
}

string

Type of this adjustment.

Acceptable values are:

• "promotion"

object (Price)

Adjustment for total price of the line item.

object (Price)

Adjustment for total tax of the line item.

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

object (OrderAddress)

The delivery address

string

The phone number of the person receiving the delivery.

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

string

Name of the recipient.

string

Street-level part of the address. Use \n to add a second line.

string

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

string

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

string

CLDR country code (for example, "US").

string

Postal Code or ZIP (for example, "94043").

boolean

Whether the address is a post office box.

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

{
  "fullName": string,
  "marketingRightsInfo": {
    object (OrderCustomerMarketingRightsInfo)
  },
  "loyaltyInfo": {
    object (OrderCustomerLoyaltyInfo)
  },
  "invoiceReceivingEmail": string
}

string

Full name of the customer.

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.

object (OrderCustomerLoyaltyInfo)

Loyalty program information.

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 Buy on Google.

{
  "marketingEmailAddress": string,
  "explicitMarketingPreference": string,
  "lastUpdatedTimestamp": string
}

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.

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"

string

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

{
  "name": string,
  "loyaltyNumber": string
}

string

Name of card/membership holder, this field will be populated when

string

The loyalty card/membership number.

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

string

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

string

The actor that created the refund.

Acceptable values are:

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

object (Price)

The amount that is refunded.

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"

string

The explanation of the reason.

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

string

The ID of the shipment.

string

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

object (OrderShipmentLineItemShipment)

The line items that are shipped.

string

The status of the shipment.

Acceptable values are:

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

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)
• "lso" (Lone Star Overnight)
• "tww" (Team Worldwide)
• "deliver-it" (Deliver-IT)
• "cdl last mile" (CDL Last Mile)

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)

string

The tracking ID for the shipment.

string

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

string

The shipment group ID of the shipment. This is set in shiplineitems request.

object (OrderShipmentScheduledDeliveryDetails)

Delivery details of the shipment if scheduling is needed.

{
  "lineItemId": string,
  "quantity": integer,
  "productId": string
}

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.

integer (uint32 format)

The quantity that is shipped.

string

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

{
  "scheduledDate": string,
  "carrierPhoneNumber": string
}

string

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

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 (for example, "+41 44 668 1800").

{
  "merchantPromotionId": string,
  "type": string,
  "subtype": string,
  "funder": string,
  "title": string,
  "shortTitle": string,
  "priceValue": {
    object (Price)
  },
  "taxValue": {
    object (Price)
  },
  "applicableItems": [
    {
      object (OrderPromotionItem)
    }
  ],
  "appliedItems": [
    {
      object (OrderPromotionItem)
    }
  ],
  "startTime": string,
  "endTime": string
}

string

Required. This field is used to identify promotions within merchants' own systems.

string

Required. The scope of the promotion. Only product is supported for orders.createtestorder.

Acceptable values are:

• "product"
• "shipping"

string

Required. The category of the promotion. Only moneyOff is supported for orders.createtestorder.

Acceptable values are:

• "buyMGetMoneyOff"
• "buyMGetNMoneyOff"
• "buyMGetNPercentOff"
• "buyMGetPercentOff"
• "freeGift"
• "freeGiftWithItemId"
• "freeGiftWithValue"
• "freeShippingOvernight"
• "freeShippingStandard"
• "freeShippingTwoDay"
• "moneyOff"
• "percentOff"
• "rewardPoints"
• "salePrice"

string

Required. The party funding the promotion. Only merchant is supported for orders.createtestorder.

Acceptable values are:

• "google"
• "merchant"

string

Required. The title of the promotion.

string

A short title of the promotion to be shown on the checkout page. Do not provide for orders.createtestorder.

object (Price)

Estimated discount applied to price. Amount is pre-tax or post-tax depending on location of order.

object (Price)

Estimated discount applied to tax (if allowed by law). Do not provide for orders.createtestorder.

object (OrderPromotionItem)

Items that this promotion may be applied to. If empty, there are no restrictions on applicable items and quantity. This field will also be empty for shipping promotions because shipping is not tied to any specific item.

object (OrderPromotionItem)

Items that this promotion have been applied to. Do not provide for orders.createtestorder. This field will be empty for shipping promotions because shipping is not tied to any specific item.

string

Promotion start time in ISO 8601 format. Date, time, and offset required, for example, "2020-01-02T09:00:00+01:00" or "2020-01-02T09:00:00Z".

string

Promotion end time in ISO 8601 format. Date, time, and offset required, for example, "2020-01-02T09:00:00+01:00" or "2020-01-02T09:00:00Z".

{
  "lineItemId": string,
  "productId": string,
  "quantity": integer,
  "offerId": string
}

string

The line item ID of a product. Do not provide for orders.createtestorder.

string

orders.createtestorder.

integer

The quantity of the associated product. Do not provide for orders.createtestorder.

string

Required. Offer ID of a product. Only for orders.createtestorder.

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

string

ID of the pickup location.

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.

object (OrderPickupDetailsCollector)

Collectors authorized to pick up shipment from the pickup location.

string

The pickup type of this order.

Acceptable values are:

• "merchantStore"
• "merchantStoreCurbside"
• "merchantStoreLocker"
• "thirdPartyPickupPoint"
• "thirdPartyLocker"

{
  "name": string,
  "phoneNumber": string
}

string

Name of the person picking up the shipment.

string

Phone number of the person picking up the shipment.

{
  "key": string,
  "value": string
}

string

Key for additional google provided (as key-value pairs) annotation.

string

Value for additional google provided (as key-value pairs) annotation.