Orders

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

Resource representations

{
  "kind": "content#order",
  "id": string,
  "merchantId": unsigned long,
  "merchantOrderId": string,
  "channelType": 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
      },
      "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,
        "channel": string,
        "contentLanguage": string,
        "price": {
          "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
        }
      ]
    }
  ],
  "status": string,
  "paymentStatus": string,
  "acknowledged": boolean,
  "shippingOption": string,
  "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,
    "email": string,
    "explicitMarketingPreference": boolean
  },
  "paymentMethod": {
    "type": string,
    "lastFourDigits": string,
    "billingAddress": {
      "recipientName": string,
      "streetAddress": [
        string
      ],
      "locality": string,
      "region": string,
      "country": string,
      "postalCode": string,
      "isPostOfficeBox": boolean,
      "fullAddress": [
        string
      ]
    },
    "phoneNumber": string,
    "expirationMonth": integer,
    "expirationYear": integer
  },
  "shippingCost": {
    "value": string,
    "currency": string
  },
  "shippingCostTax": {
    "value": string,
    "currency": string
  },
  "netAmount": {
    "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,
          "quantity": unsigned integer
        }
      ],
      "status": string,
      "carrier": string,
      "trackingId": string,
      "deliveryDate": string
    }
  ],
  "promotions": [
    {
      "id": string,
      "productApplicability": string,
      "longTitle": string,
      "effectiveDates": string,
      "redemptionChannel": string,
      "genericRedemptionCode": string,
      "benefits": [
        {
          "offerIds": [
            string
          ],
          "type": string,
          "subType": string,
          "discount": {
            "value": string,
            "currency": string
          },
          "taxImpact": {
            "value": string,
            "currency": string
          }
        }
      ]
    }
  ]
}
Property name Value Description Notes
acknowledged boolean Whether the order was acknowledged.
channelType string The channel type of the order: "purchaseOnGoogle" or "googleExpress".

Acceptable values are:
  • "googleExpress"
  • "purchasesOnGoogle"
customer nested object The details of the customer who placed the order.
customer.email string Email address of the customer.
customer.explicitMarketingPreference boolean If set, this indicates the user explicitly chose to opt in or out of providing marketing rights to the merchant. If unset, this indicates the user has already made this choice in a previous purchase, and was thus not shown the marketing right opt in/out checkbox during the checkout flow.
customer.fullName string Full name of the customer.
deliveryDetails nested object The details for the delivery.
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 (e.g. "CA").
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[].cancellations[] list Cancellations of the line item.
lineItems[].cancellations[].actor string The actor that created the cancellation.

Acceptable values are:
  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "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 POG until you make an update to that product. This will not affect your Shopping ads.

Acceptable values are:
  • "autoPostInternal"
  • "autoPostInvalidBillingAddress"
  • "autoPostNoInventory"
  • "autoPostPriceError"
  • "autoPostUndeliverableShippingAddress"
  • "customerCanceled"
  • "customerInitiatedCancel"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "noInventory"
  • "orderTimeout"
  • "other"
  • "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 from the time of the order placement.
lineItems[].product.brand string Brand of the item.
lineItems[].product.channel string The item's channel (online or local).

Acceptable values are:
  • "local"
  • "online"
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.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"
  • "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"
  • "invalidCoupon"
  • "malformedShippingAddress"
  • "other"
  • "productArrivedDamaged"
  • "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.
netAmount nested object 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.
netAmount.currency string The currency of the price. writable
netAmount.value string The price represented as a number. writable
paymentMethod nested object The details of the payment method.
paymentMethod.billingAddress nested object The billing address.
paymentMethod.billingAddress.country string CLDR country code (e.g. "US").
paymentMethod.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

paymentMethod.billingAddress.isPostOfficeBox boolean Whether the address is a post office box.
paymentMethod.billingAddress.locality string City, town or commune. May also include dependent localities or sublocalities (e.g. neighborhoods or suburbs).
paymentMethod.billingAddress.postalCode string Postal Code or ZIP (e.g. "94043").
paymentMethod.billingAddress.recipientName string Name of the recipient.
paymentMethod.billingAddress.region string Top-level administrative subdivision of the country (e.g. "CA").
paymentMethod.billingAddress.streetAddress[] list Street-level part of the address.
paymentMethod.expirationMonth integer The card expiration month (January = 1, February = 2 etc.).
paymentMethod.expirationYear integer The card expiration year (4-digit, e.g. 2015).
paymentMethod.lastFourDigits string The last four digits of the card number.
paymentMethod.phoneNumber string The billing phone number.
paymentMethod.type string The type of instrument.

Acceptable values are:
  • "AMEX"
  • "DISCOVER"
  • "JCB"
  • "MASTERCARD"
  • "UNIONPAY"
  • "VISA"
  • ""
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 The details of the merchant provided promotions applied to the order. More details about the program are here.
promotions[].benefits[] list
promotions[].benefits[].discount nested object The discount in the order price when the promotion is applied.
promotions[].benefits[].discount.currency string The currency of the price. writable
promotions[].benefits[].discount.value string The price represented as a number. writable
promotions[].benefits[].offerIds[] list The OfferId(s) that were purchased in this order and map to this specific benefit of the promotion.
promotions[].benefits[].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:
  • "freeOvernightShipping"
  • "freeShipping"
  • "freeTwoDayShipping"
  • "moneyOff"
  • "percentageOff"
promotions[].benefits[].taxImpact nested object The impact on tax when the promotion is applied.
promotions[].benefits[].taxImpact.currency string The currency of the price. writable
promotions[].benefits[].taxImpact.value string The price represented as a number. writable
promotions[].benefits[].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"
promotions[].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.
promotions[].genericRedemptionCode string Optional. The text code that corresponds to the promotion when applied on the retailer?s website.
promotions[].id string The unique ID of the promotion.
promotions[].longTitle string The full title of the promotion.
promotions[].productApplicability string Whether the promotion is applicable to all products or only specific products.

Acceptable values are:
  • "allProducts"
  • "specificProducts"
promotions[].redemptionChannel string Indicates that the promotion is valid online.

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

Acceptable values are:
  • "customer"
  • "googleBot"
  • "googleCustomerService"
  • "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"
  • "courtesyAdjustment"
  • "customerCanceled"
  • "customerDiscretionaryReturn"
  • "customerInitiatedMerchantCancel"
  • "deliveredLateByCarrier"
  • "feeAdjustment"
  • "invalidCoupon"
  • "lateShipmentCredit"
  • "malformedShippingAddress"
  • "noInventory"
  • "orderTimeout"
  • "other"
  • "paymentDeclined"
  • "priceAdjustment"
  • "priceError"
  • "productArrivedDamaged"
  • "productNotAsDescribed"
  • "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 are:
  • "gsx"
  • "ups"
  • "united parcel service"
  • "usps"
  • "united states postal service"
  • "fedex"
  • "dhl"
  • "ecourier"
  • "cxt"
  • "google"
  • "on trac"
  • "ontrac"
  • "on-trac"
  • "on_trac"
  • "delvic"
  • "dynamex"
  • "lasership"
  • "smartpost"
  • "fedex smartpost"
  • "mpx"
  • "uds"
  • "united delivery service"
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 delievered
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.
shipments[].lineItems[].quantity unsigned integer The quantity that is shipped.
shipments[].status string The status of the shipment.

Acceptable values are:
  • "delivered"
  • "shipped"
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
shippingOption string The requested shipping option.

Acceptable values are:
  • "economy"
  • "expedited"
  • "oneDay"
  • "sameDay"
  • "standard"
  • "twoDay"
status string The status of the order.

Acceptable values are:
  • "canceled"
  • "delivered"
  • "inProgress"
  • "partiallyDelivered"
  • "partiallyReturned"
  • "partiallyShipped"
  • "pendingShipment"
  • "returned"
  • "shipped"

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.
createtestorder
Sandbox only. Creates a test order.
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. Retrieves an order template that can be used to quickly create a new order in sandbox.
list
Lists the orders in your Merchant Center account.
refund
Initiates a full or partial reversal on the payment instrument.
returnlineitem
Returns a line item.
shiplineitems
Marks line item(s) as shipped.
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