About Orders

This document conforms to the Content API calls for Orders V2.1 and avoids the use of deprecated API calls from Orders V2 (although it is still available). This document covers the Content API Orders processes, which includes:

  • The lifecycle of an order.
  • The order return process.
  • The reserve workflow process.
  • Not delivered order process.
  • Orders API. Their calls, status, summary, and detailed diagrams with accompanying descriptions.

An order contains line items which refer to one or more products and captures information available at the time of purchase, such as:

  • The shipment method selected by the customer.
  • The customer's shipping address.
  • The customer's preferences for receiving emails from the merchant.

Each order has an order status, which indicates the progress towards completion of the order. The order status is frequently derived from the actual line items. For example, if all line items are shipped, the order status is shipped or, if all line items are returned and a refund is granted, the order status is set to returned. For a full description of an order, refer to Orders Resource page.

The following diagrams illustrate the order and return processes:

Order process

Orders are created by customers and processed by merchants using the Google Shopping Content API. These orders are then acquired, acknowledged, processed, and shipped out.

The steps in the order process:

  1. New order placed: A customer places a new order on Google Shopping.

  2. Check order & payment info: Google confirms the order and payment information. When the order is verified for payment, and after the customer has had time to change their mind, the status of the order is changed to pendingShipment. Note that you should not start your order fulfillment process until the order is in pendingShipment status.

  3. Get orders & acknowledge: You receive the new order. At this stage, set the order flag to acknowledged which helps to filter new orders. This step is optional.

  4. Check availability, reserve: You begin fulfillment and verify that the products are available for this order. If you are using the Reserve process, you can verify this as well. Note that if a product is unavailable, notify Google and the entire order or a part of the order is set to canceled.

  5. Ship order and process payment: You ship the complete order, or partial order, within three days of your handling time. Use the API call orders.shiplineitem to mark as shipped. Google then completes the payment steps.

  6. Track shipment: You continue to track the shipment and update the order with tracking information (Google tracks this information for supported carriers).

  7. Shipment update: Google sets the order status as delivered or partiallyDelivered when the complete order or part of the order is delivered, or undeliverable if the order cannot be delivered. Note that this requires using supported carriers and adding valid tracking numbers.

  8. Complete payment: Google completes the payment process and invoice for OrderInvoice whitelisted merchants. When all items are shipped, the order status is set to shipped.

  9. Order received: The customer receives the order. At this point, the customer is permitted to return the delivered order. Refer to the Summary of the return process for more details.

Detailed order process

In the detailed order process, we explore the API calls required to process an order.

The order process begins when a customer places an order. After the customer places an order, Google sends an order confirmation email message that contains the Google order number.

Google continues to the fraud check stage. During the fraud check process, a short time is allowed for the customer to cancel the order. If the order is valid, the order status is set to pendingShipment and you can start order fulfillment by using orders.acknowledge, for example.

You can also fetch actionable orders with a periodic poll using the orders.list API call and using the status field as a filter to get a list of orders with a status of pendingShipment. The polling interval, how often you poll for new orders, should be set based on your anticipated order frequency or order volume.

If the order's products are reserved, then the order process skips the steps that check for availability and the possibility of creating partial orders. In this case, proceed to ship the order by using orders.shiplineitem for the reserved products.

Optionally, use your ID in the send merchant order ID to Google step, using the orders.updatemerchantorderid API call. Google then sets the order status to acknowledge. If you do not use your merchantOrderId, then the order status is set to acknowledge. Essentially, calling any method on a given order other than retrieving its details automatically acknowledges the order.

If you decide not to fulfill this order, cancel it by calling the orders.cancel API passing a reason code for the cancellation. The order status is set to cancel. Refer to the list of valid reason codes in the Orders API resource.

If you expect that your order cannot be shipped on time, you should inform Google of this delay using orders.updatelineitemshippingdetails. This API call lets you set a new shipByDate and deliveryByDate for a lineitemId in the order. If orders aren't shipped within three days of your handling time, they may be canceled automatically. Google will respect this new shipByDate and deliveryByDate in the order's auto-cancellation process, and will inform the customer via email of the new delivery information for their order. Learn more about shipping policies for Shopping Actions.

If you continue to fulfill the order, and none of the items in an order are available, the entire order may be canceled using the orders.cancel API call. If one or more line items are not available, then those line items may be canceled using the orders.cancellineitem API call. The order status for those line items sets to canceled.

Merchant ships the order: The orders.shiplineitem API call is used to ship the entire order, or partial order, based on available line items in the order; and the order status is updated to shipped or partiallyShipped for a partial order. If the order is partially shipped, that implies that there may still be some items in a pendingShipment state. After all line items in an order are in either shipped_or_canceled state, the order status sets to shipped.

An email message is sent to the customer confirming the order details, and the payment processing is completed with the orders.shiplineitem API call. Items not marked as shipped within three days of your handling time are canceled automatically. Refer to our shipping policy for more details.

Optionally, merchants who have been whitelisted can use the orderinvoices.createchargeinvoice API at a line item level for greater flexibility and granularity in generating invoices and calculating taxes. The merchant order payment status is updated to paymentCaptured after using this API for all line items. The line item status is then updated to shipped, and a confirmation email is sent to the customer when fully shipped. If you would like to use this API, contact our US support team or France support team.

Merchants are expected to track each shipment as a best practice. When an order is delivered, use the API call orders.updateshipment, and this updates the shipment status to delivered in the API call (for supported carriers Google updates the status for you). If an order is not delivered, we continue with the Not Delivered process.

The order is complete when:

  • All items for that order are shipped.
  • All partial order shipments have a status of delivered.
  • A confirmation email has been sent to the customer.

Note that a customer can return an order that was delivered. The return process is summarized in the Summary of the return process section and shown in the Detailed return process section.

Not delivered workflow

If the customer does not receive an order, you have to follow a careful process to ensure that the customer is ultimately satisfied with the outcome. This diagram documents that process, as well as the steps Google takes in this case.

The Order Not Delivered sub-process flow continues from the Detailed order process:

If the carrier followed a process to deliver a shipment, but the shipment was still not delivered, then the shipment should be updated to undeliverable.

If the shipment was returned to you as a result of the customer rejecting the order, check to see if the shipment contained 100% of the order. If the shipment contained 100% of the order, use the orders.returnrefundlineitem API, to have the order status changed by Google to returned and trigger a refund email confirmation to the customer by Google.

If the shipment did not contain 100% of the order, then the order status is changed by Google to partiallyReturned and a partial refund confirmation is sent to the customer.

If the shipment was not returned, continue to track the shipment and make a decision to refund. If you decide to issue a refund, use the orders.returnrefundlineitem API call. Optionally, some merchants who have been whitelisted to the orderinvoices API can use the orderinvoices.createchargeinvoice or the orderinvoices.createrefundinvoice API call for greater flexibility and granularity in generating invoices and calculating taxes. If you decide not to refund the item, the customer is still charged for the order.

Reserve workflow

The reserve workflow sub-process is designed to allow merchants to reserve a subset of their product for sale on Google.

In order to use the reserve workflow, you need to know what the inventory is, track it on your system, and use the sell_on_google_quantity attribute to share your inventory information.

This section assumes that you are following the broader Detailed order process and this workflow replaces the first part of that workflow.

The reserve sub-process is followed after a customer orders a product that you have placed on reserve in your inventory. Once the order is placed, Google changes the order status to inProgress and the merchant can fetch new orders using the API call orders.list with a filter for the order status of inProgress.

After you find an order that contains products that you manage through your reserve process, update the order with your OrderId. If you decide to provide your ID by using the orders.updatemerchantorderid API call, Google updates this information and automatically marks the order as acknowledged. If you do not provide your merchant OrderId, you should use orders.acknowledge to mark the order as acknowledged order.

Check for items available in your system to verify that all products are available. You should keep the sell_on_google_quantity attribute updated as a way to share your inventory information. If all products for the order are available, reserve the available inventory for this order. If some reserve products are not available, use the API call orders.cancellineitem to cancel the unavailable products while the order still has a status of inProgress with acknowledged.

If none of the products in the order are available in the reserve inventory, cancel the order by using the orders.cancel API call. After the order has been canceled, Google then cancels the order, informs the customer, and initiates the default invoice process to refund their money.

To complete the processing, return to the order workflow process. Remember that the order is now acknowledged.

Order return process

The following diagram is a summary of the order return process.

The order return process:

  1. Customer requests a return: The customer returns the order directly by using the order menu in our application or by contacting Google's help center. The customer specifies the reason for the return, such as ordering the wrong item or the wrong size.

  2. Google reviews the return request: Google reviews the reason for the return request, and if approved, sends the customer a return package shipping label in PDF format via email.

  3. Send package: The customer prints the shipping label, and ships the package back to Google.

  4. Ship return to merchant: Google sends the package back to you, sometimes through a Google shipping center.

  5. Accept or reject shipped Item: Decide to accept or reject the returned items based on the reason given by the customer. To monitor customer's returns, use the Shopping Content API to poll for returns.

  6. Process Item & Refund: You process the returned order for a refund or partial refund.

  7. Issue Payment for Refund: Google processes the refund or partial refund to be paid back to the customer, and sets the order status to returned or partiallyReturned.

  8. Receive Funds: Customer receives a refund or partial refund.

Detailed order return process

Use this flowchart in the case where the customer has returned the order. We've broken this up into three separate parts to aid in readability:

  1. The customer return process.
  2. Polling for returns via the API.
  3. Accepting or rejecting the package and Google processing the decision.

Customer returns the package

The order return process begins when a customer receives an order and makes a decision to send one or more items back to you. The customer can call Google's Help Center or use the Shopping application interface to create a request to return a partial or complete order.

The return request is received by Google. If the return request is not approved, the customer receives an email notification and can appeal the rejection.

If the return request is approved, Google creates a return request which marks the order as being returned and issues a shipping label to the customer in PDF format to return the package.

Merchant polls for returns

Use the orderreturns.list API to find new returns as they happen in real time. If a return is identified, use the carrier and tracking number provided to anticipate the shipment and inform the staff that a return package is being shipped back to your location. If you decide not to use this API, however, the returned order is still shipped to your location.

Once you receive the package and you review the packing slip and assess the package content to verify that the package was returned for a valid reason, you can then decide to accept the return if the return is valid.

Once you accept the return, determine the amount to refund to the customer, and calculate the total refund. Then, use the API call orders.returnrefundlineitem to issue the return and refund.

Use the orders.returnrefundlineitem API call with the priceAmount.value parameter set to 0 to accept the return of the item without issuing a refund to the customer. Alternatively, if you have been whitelisted by Google for the use of the orderinvoices.createrefundinvoice API call, use this method to issue a more detailed invoice with the return and refund for greater flexibility and calculating taxes.

Somtimes a line item has more than one quantity for a product, be sure to refund the amount as a multiple of the quantity of products in that line item. This process is repeated for each line item in the returned order. For example, if a customer wants to return a product, with a quantity of 2 at a price of say, $10 each, you as the merchant send an orders.returnrefundlineitem API call with a quantity of 2 and the priceAmount.value set to 20, or two times the individual product price of $10.

If you decide to reject the return, call the orders.rejectreturnlineitem API and then send the package back to the customer. Google then sends an email update to the customer.

Google processing the return

Once you have decided to either accept or reject all order line items in the package, Google begins the return process by first checking to see if all line items have returned. Google updates the order status to returned or partiallyReturned. Google sends an email to update the customer and initiate the refund.