Orders

For a list of methods for this resource, see the end of this page.

Resource representations

Order. All methods require the order manager role.

{
  "kind": "content#order",
  "id": string,
  "merchantId": unsigned long,
  "merchantOrderId": string,
  "lineItems": [
    {
      "id": string,
      "quantityOrdered": unsigned integer,
      "quantityPending": unsigned integer,
      "quantityShipped": unsigned integer,
      "quantityDelivered": unsigned integer,
      "quantityReturned": unsigned integer,
      "quantityCanceled": unsigned integer,
      "price": {
        "value": string,
        "currency": string
      },
      "tax": {
        "value": string,
        "currency": string
      },
      "adjustments": [
        {
          "type": string,
          "priceAdjustment": {
            "value": string,
            "currency": string
          },
          "taxAdjustment": {
            "value": string,
            "currency": string
          }
        }
      ],
      "shippingDetails": {
        "method": {
          "methodName": string,
          "carrier": string,
          "minDaysInTransit": unsigned integer,
          "maxDaysInTransit": unsigned integer
        },
        "shipByDate": string,
        "deliverByDate": string
      },
      "returnInfo": {
        "isReturnable": boolean,
        "daysToReturn": integer,
        "policyUrl": string
      },
      "product": {
        "id": string,
        "offerId": string,
        "targetCountry": string,
        "contentLanguage": string,
        "price": {
          "value": string,
          "currency": string
        },
        "fees": [
          {
            "name": string,
            "amount": {
              "value": string,
              "currency": string
            }
          }
        ],
        "title": string,
        "gtin": string,
        "brand": string,
        "mpn": string,
        "condition": string,
        "itemGroupId": string,
        "imageLink": string,
        "shownImage": string,
        "variantAttributes": [
          {
            "dimension": string,
            "value": string
          }
        ]
      },
      "returns": [
        {
          "creationDate": string,
          "actor": string,
          "quantity": unsigned integer,
          "reason": string,
          "reasonText": string
        }
      ],
      "cancellations": [
        {
          "creationDate": string,
          "actor": string,
          "quantity": unsigned integer,
          "reason": string,
          "reasonText": string
        }
      ],
      "annotations": [
        {
          "key": string,
          "value": string
        }
      ]
    }
  ],
  "status": string,
  "paymentStatus": string,
  "acknowledged": boolean,
  "placedDate": string,
  "deliveryDetails": {
    "address": {
      "recipientName": string,
      "streetAddress": [
        string
      ],
      "locality": string,
      "region": string,
      "country": string,
      "postalCode": string,
      "isPostOfficeBox": boolean,
      "fullAddress": [
        string
      ]
    },
    "phoneNumber": string
  },
  "customer": {
    "fullName": string,
    "marketingRightsInfo": {
      "marketingEmailAddress": string,
      "explicitMarketingPreference": string,
      "lastUpdatedTimestamp": string
    }
  },
  "billingAddress": {
    "recipientName": string,
    "streetAddress": [
      string
    ],
    "locality": string,
    "region": string,
    "country": string,
    "postalCode": string,
    "isPostOfficeBox": boolean,
    "fullAddress": [
      string
    ]
  },
  "shippingCost": {
    "value": string,
    "currency": string
  },
  "shippingCostTax": {
    "value": string,
    "currency": string
  },
  "netPriceAmount": {
    "value": string,
    "currency": string
  },
  "netTaxAmount": {
    "value": string,
    "currency": string
  },
  "refunds": [
    {
      "creationDate": string,
      "actor": string,
      "amount": {
        "value": string,
        "currency": string
      },
      "reason": string,
      "reasonText": string
    }
  ],
  "shipments": [
    {
      "id": string,
      "creationDate": string,
      "lineItems": [
        {
          "lineItemId": string,
          "productId": string,
          "quantity": unsigned integer
        }
      ],
      "status": string,
      "carrier": string,
      "trackingId": string,
      "deliveryDate": string
    }
  ],
  "promotions": [
    {
      "merchantPromotionId": string,
      "type": string,
      "subtype": string,
      "funder": string,
      "title": string,
      "shortTitle": string,
      "priceValue": {
        "value": string,
        "currency": string
      },
      "taxValue": {
        "value": string,
        "currency": string
      },
      "applicableItems": [
        {
          "lineItemId": string,
          "productId": string,
          "quantity": integer
        }
      ],
      "appliedItems": [
        {
          "lineItemId": string,
          "productId": string,
          "quantity": integer
        }
      ]
    }
  ],
  "taxCollector": string
}
Property name Value Description Notes
acknowledged boolean Whether the order was acknowledged.
billingAddress nested object The billing address.
billingAddress.country string CLDR country code (e.g. "US").
billingAddress.fullAddress[] list 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

billingAddress.isPostOfficeBox boolean Whether the address is a post office box.
billingAddress.locality string City, town or commune. May also include dependent localities or sublocalities (e.g. neighborhoods or suburbs).
billingAddress.postalCode string Postal Code or ZIP (e.g. "94043").
billingAddress.recipientName string Name of the recipient.
billingAddress.region string Top-level administrative subdivision of the country. For example, a state like California ("CA") or a province like Quebec ("QC").
billingAddress.streetAddress[] list Street-level part of the address.
customer nested object The details of the customer who placed the order.
customer.fullName string Full name of the customer.
customer.marketingRightsInfo nested object 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.
customer.marketingRightsInfo.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"
customer.marketingRightsInfo.lastUpdatedTimestamp string Timestamp when last time marketing preference was updated. Could be empty, if user wasn't offered a selection yet.
customer.marketingRightsInfo.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.
deliveryDetails nested object Delivery details for shipments.
deliveryDetails.address nested object The delivery address
deliveryDetails.address.country string CLDR country code (e.g. "US").
deliveryDetails.address.fullAddress[] list 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

deliveryDetails.address.isPostOfficeBox boolean Whether the address is a post office box.
deliveryDetails.address.locality string City, town or commune. May also include dependent localities or sublocalities (e.g. neighborhoods or suburbs).
deliveryDetails.address.postalCode string Postal Code or ZIP (e.g. "94043").
deliveryDetails.address.recipientName string Name of the recipient.
deliveryDetails.address.region string Top-level administrative subdivision of the country. For example, a state like California ("CA") or a province like Quebec ("QC").
deliveryDetails.address.streetAddress[] list Street-level part of the address.
deliveryDetails.phoneNumber string The phone number of the person receiving the delivery.
id string The REST ID of the order. Globally unique.
kind string Identifies what kind of resource this is. Value: the fixed string "content#order".
lineItems[] list Line items that are ordered.
lineItems[].adjustments[] list Price and tax adjustments applied on the line item.
lineItems[].adjustments[].priceAdjustment nested object Adjustment for total price of the line item.
lineItems[].adjustments[].priceAdjustment.currency string The currency of the price. writable
lineItems[].adjustments[].priceAdjustment.value string The price represented as a number. writable
lineItems[].adjustments[].taxAdjustment nested object Adjustment for total tax of the line item.
lineItems[].adjustments[].taxAdjustment.currency string The currency of the price. writable
lineItems[].adjustments[].taxAdjustment.value string The price represented as a number. writable
lineItems[].adjustments[].type string Type of this adjustment.

Acceptable values are:
  • "promotion"
lineItems[].annotations[] list Annotations that are attached to the line item.
lineItems[].annotations[].key string Key for additional merchant provided (as key-value pairs) annotation about the line item.
lineItems[].annotations[].value string Value for additional merchant provided (as key-value pairs) annotation about the line item.
lineItems[].cancellations[] list Cancellations of the line item.
lineItems[].cancellations[].actor string The actor that created the cancellation.

Acceptable values are:
  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googleSabre"
  • "merchant"
lineItems[].cancellations[].creationDate string Date on which the cancellation has been created, in ISO 8601 format.
lineItems[].cancellations[].quantity unsigned integer The quantity that was canceled.
lineItems[].cancellations[].reason string The reason for the cancellation. Orders that are cancelled 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"
  • "shippingPriceError"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
lineItems[].cancellations[].reasonText string The explanation of the reason.
lineItems[].id string The ID of the line item.
lineItems[].price nested object Total price for the line item. For example, if two items for $10 are purchased, the total price will be $20.
lineItems[].price.currency string The currency of the price. writable
lineItems[].price.value string The price represented as a number. writable
lineItems[].product nested object 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.
lineItems[].product.brand string Brand of the item.
lineItems[].product.condition string Condition or state of the item.

Acceptable values are:
  • "new"
  • "refurbished"
  • "used"
lineItems[].product.contentLanguage string The two-letter ISO 639-1 language code for the item.
lineItems[].product.fees[] list Associated fees at order creation time.
lineItems[].product.fees[].amount nested object Amount of the fee.
lineItems[].product.fees[].amount.currency string The currency of the price. writable
lineItems[].product.fees[].amount.value string The price represented as a number. writable
lineItems[].product.fees[].name string Name of the fee.
lineItems[].product.gtin string Global Trade Item Number (GTIN) of the item.
lineItems[].product.id string The REST ID of the product.
lineItems[].product.itemGroupId string Shared identifier for all variants of the same product.
lineItems[].product.mpn string Manufacturer Part Number (MPN) of the item.
lineItems[].product.offerId string An identifier of the item.
lineItems[].product.price nested object Price of the item.
lineItems[].product.price.currency string The currency of the price. writable
lineItems[].product.price.value string The price represented as a number. writable
lineItems[].product.shownImage string URL to the cached image shown to the user when order was placed.
lineItems[].product.targetCountry string The CLDR territory code of the target country of the product.
lineItems[].product.title string The title of the product.
lineItems[].product.variantAttributes[] list 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.
lineItems[].product.variantAttributes[].dimension string The dimension of the variant.
lineItems[].product.variantAttributes[].value string The value for the dimension.
lineItems[].quantityCanceled unsigned integer Number of items canceled.
lineItems[].quantityDelivered unsigned integer Number of items delivered.
lineItems[].quantityOrdered unsigned integer Number of items ordered.
lineItems[].quantityPending unsigned integer Number of items pending.
lineItems[].quantityReturned unsigned integer Number of items returned.
lineItems[].quantityShipped unsigned integer Number of items shipped.
lineItems[].returnInfo nested object Details of the return policy for the line item.
lineItems[].returnInfo.daysToReturn integer How many days later the item can be returned.
lineItems[].returnInfo.isReturnable boolean Whether the item is returnable.
lineItems[].returnInfo.policyUrl string URL of the item return policy.
lineItems[].returns[] list Returns of the line item.
lineItems[].returns[].actor string The actor that created the refund.

Acceptable values are:
  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googleSabre"
  • "merchant"
lineItems[].returns[].creationDate string Date on which the item has been created, in ISO 8601 format.
lineItems[].returns[].quantity unsigned integer Quantity that is returned.
lineItems[].returns[].reason string The reason for the return.

Acceptable values are:
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredTooLate"
  • "expiredItem"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "qualityNotAsExpected"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"
lineItems[].returns[].reasonText string The explanation of the reason.
lineItems[].shippingDetails nested object Details of the requested shipping for the line item.
lineItems[].shippingDetails.deliverByDate string The delivery by date, in ISO 8601 format.
lineItems[].shippingDetails.method nested object Details of the shipping method.
lineItems[].shippingDetails.method.carrier string The carrier for the shipping. Optional. See shipments[].carrier for a list of acceptable values.
lineItems[].shippingDetails.method.maxDaysInTransit unsigned integer Maximum transit time.
lineItems[].shippingDetails.method.methodName string The name of the shipping method.
lineItems[].shippingDetails.method.minDaysInTransit unsigned integer Minimum transit time.
lineItems[].shippingDetails.shipByDate string The ship by date, in ISO 8601 format.
lineItems[].tax nested object 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.
lineItems[].tax.currency string The currency of the price. writable
lineItems[].tax.value string The price represented as a number. writable
merchantId unsigned long
merchantOrderId string Merchant-provided ID of the order.
netPriceAmount nested object 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.
netPriceAmount.currency string The currency of the price. writable
netPriceAmount.value string The price represented as a number. writable
netTaxAmount nested object 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.
netTaxAmount.currency string The currency of the price. writable
netTaxAmount.value string The price represented as a number. writable
paymentStatus string The status of the payment.

Acceptable values are:
  • "paymentCaptured"
  • "paymentRejected"
  • "paymentSecured"
  • "pendingAuthorization"
placedDate string The date when the order was placed, in ISO 8601 format.
promotions[] list Promotions associated with the order.
promotions[].applicableItems[] list Items which this promotion may be applied to. If empty, there are no restrictions on applicable items and quantity.
promotions[].applicableItems[].lineItemId string
promotions[].applicableItems[].productId string
promotions[].applicableItems[].quantity integer The quantity of the associated product.
promotions[].appliedItems[] list Items which this promotion have been applied to.
promotions[].appliedItems[].lineItemId string
promotions[].appliedItems[].productId string
promotions[].appliedItems[].quantity integer The quantity of the associated product.
promotions[].funder string The party funding the promotion.

Acceptable values are:
  • "google"
  • "merchant"
promotions[].merchantPromotionId string This field is used to identify promotions within merchants' own systems.
promotions[].priceValue nested object Estimated discount applied to price. Amount is pre-tax or post-tax depending on location of order.
promotions[].priceValue.currency string The currency of the price. writable
promotions[].priceValue.value string The price represented as a number. writable
promotions[].shortTitle string A short title of the promotion to be shown on the checkout page.
promotions[].subtype string The category of the promotion.

Acceptable values are:
  • "buyMGetMoneyOff"
  • "buyMGetNMoneyOff"
  • "buyMGetNPercentOff"
  • "buyMGetPercentOff"
  • "freeGift"
  • "freeGiftWithItemId"
  • "freeGiftWithValue"
  • "freeShippingOvernight"
  • "freeShippingStandard"
  • "freeShippingTwoDay"
  • "moneyOff"
  • "percentOff"
  • "rewardPoints"
  • "salePrice"
promotions[].taxValue nested object Estimated discount applied to tax (if allowed by law).
promotions[].taxValue.currency string The currency of the price. writable
promotions[].taxValue.value string The price represented as a number. writable
promotions[].title string The title of the promotion.
promotions[].type string The scope of the promotion.

Acceptable values are:
  • "product"
  • "shipping"
refunds[] list Refunds for the order.
refunds[].actor string The actor that created the refund.

Acceptable values are:
  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "googleSabre"
  • "merchant"
refunds[].amount nested object The amount that is refunded.
refunds[].amount.currency string The currency of the price. writable
refunds[].amount.value string The price represented as a number. writable
refunds[].creationDate string Date on which the item has been created, in ISO 8601 format.
refunds[].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"
  • "shippingCostAdjustment"
  • "shippingPriceError"
  • "taxAdjustment"
  • "taxError"
  • "undeliverableShippingAddress"
  • "unsupportedPoBoxAddress"
  • "wrongProductShipped"
refunds[].reasonText string The explanation of the reason.
shipments[] list Shipments of the order.
shipments[].carrier string The carrier handling the shipment.

Acceptable values for US are:
  • "gsx"
  • "ups"
  • "usps"
  • "fedex"
  • "dhl"
  • "ecourier"
  • "cxt"
  • "google"
  • "ontrac"
  • "emsy"
  • "ont"
  • "deliv"
  • "dynamex"
  • "lasership"
  • "mpx"
  • "uds"
  • "efw"


Acceptable values for FR are:
  • "colissimo"
  • "chronopost"
  • "gls"
  • "dpd"
  • "bpost"
shipments[].creationDate string Date on which the shipment has been created, in ISO 8601 format.
shipments[].deliveryDate string Date on which the shipment has been delivered, in ISO 8601 format. Present only if status is delivered
shipments[].id string The ID of the shipment.
shipments[].lineItems[] list The line items that are shipped.
shipments[].lineItems[].lineItemId string The ID of the line item that is shipped. Either lineItemId or productId is required.
shipments[].lineItems[].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.
shipments[].lineItems[].quantity unsigned integer The quantity that is shipped.
shipments[].status string The status of the shipment.

Acceptable values are:
  • "delivered"
  • "shipped"
  • "undeliverable"
shipments[].trackingId string The tracking ID for the shipment.
shippingCost nested object The total cost of shipping for all items.
shippingCost.currency string The currency of the price. writable
shippingCost.value string The price represented as a number. writable
shippingCostTax nested object The tax for the total shipping cost.
shippingCostTax.currency string The currency of the price. writable
shippingCostTax.value string The price represented as a number. writable
status string The status of the order.

Acceptable values are:
  • "canceled"
  • "delivered"
  • "inProgress"
  • "partiallyDelivered"
  • "partiallyReturned"
  • "partiallyShipped"
  • "pendingShipment"
  • "returned"
  • "shipped"
taxCollector string The party responsible for collecting and remitting taxes.

Acceptable values are:
  • "marketplaceFacilitator"
  • "merchant"

Methods

acknowledge
Marks an order as acknowledged.
advancetestorder
Sandbox only. Moves a test order from state "inProgress" to state "pendingShipment".
cancel
Cancels all line items in an order, making a full refund.
cancellineitem
Cancels a line item, making a full refund.
canceltestorderbycustomer
Sandbox only. Cancels a test order for customer-initiated cancellation.
createtestorder
Sandbox only. Creates a test order.
createtestreturn
Sandbox only. Creates a test return.
get
Retrieves an order from your Merchant Center account.
getbymerchantorderid
Retrieves an order using merchant order ID.
gettestordertemplate
Sandbox only. Retrieves an order template that can be used to quickly create a new order in sandbox.
instorerefundlineitem
Notifies that item return and refund was handled directly by merchant outside of Google payments processing (e.g. cash refund done in store).
Note: We recommend calling the returnrefundlineitem method to refund in-store returns. We will issue the refund directly to the customer. This helps to prevent possible differences arising between merchant and Google transaction records. We also recommend having the point of sale system communicate with Google to ensure that customers do not receive a double refund by first refunding via Google then via an in-store return.
list
Lists the orders in your Merchant Center account.
rejectreturnlineitem
Rejects return on an line item.
returnrefundlineitem
Returns and refunds a line item. Note that this method can only be called on fully shipped orders.
setlineitemmetadata
Sets (or overrides if it already exists) merchant provided annotations in the form of key-value pairs. A common use case would be to supply us with additional structured information about a line item that cannot be provided via other methods. Submitted key-value pairs can be retrieved as part of the orders resource.
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.

Send feedback about...

Content API for Shopping