This document conforms to the Content API calls for Orders v2.1 and avoids the use of deprecated API calls from Orders v2.
This document covers the Content API Orders processes, which includes:
- The lifecycle of an order.
- The order return process.
- The order refund-without-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, return, and refund-without-return processes:
- Summary of the order process: High-level overview of the order process.
- Detailed order process: Detailed order process with API calls and order status.
- Reserve process: Sub-process for orders with API calls and order status for merchants who want to reserve a subset of their product.
- Not Delivered process: Sub-process for orders with API calls and order status for orders that are not delivered to the customer.
- Summary of the return process: High-level overview of the order return process.
- Detailed return process: Detailed return process with API calls and order status.
- Summary of the refund-without-return process: High-level overview of the order refund-without-return 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:
New order placed: A customer places a new order on Google Shopping.
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
Get orders & acknowledge: You receive the new order. At this stage, set the order flag to
acknowledgedwhich helps to filter new orders. This step is optional.
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
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.shiplineitemto mark as shipped. Google then completes the payment steps.
Track shipment: You continue to track the shipment and update the order with tracking information (Google tracks this information for supported carriers).
Shipment update: Google sets the order status as
partiallyDeliveredwhen the complete order or part of the order is delivered, or
undeliverableif the order cannot be delivered. Note that this requires using supported carriers and adding valid tracking numbers.
Complete payment: Google completes the payment process and invoice for
OrderInvoiceenabled merchants. When all items are shipped, the order status is set to
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
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
Optionally, use your ID in the send merchant order ID to Google step, using
orders.updatemerchantorderid API call. Google then sets the order status
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
This API call lets you set a new
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
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
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
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
shipped_or_canceled state, the order status sets to
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 enabled 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
and a confirmation email is sent to the customer when fully shipped. If you
would like to use this API, contact our US support
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
- A confirmation email has been sent to the customer.
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
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
enabled for the orderinvoices
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.
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
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
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
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
Order return process
The following diagram is a summary of the order return process.
The order return process:
Customer requests a return: The customer returns the order directly by using the order menu in the Google Shopping 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.
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.
Send package: The customer prints the shipping label and ships the package back to Google.
Ship return to merchant: Google sends the package back to you, sometimes through a Google shipping center.
Retrieve return: You continuously check for new returns via the OrderReturns service
Process return: You decide to accept or reject the return package, via
orderreturns.process. If a return is not found in step 5, use the legacy API
orders.rejectreturnlineitemto process the return.
Issue payment for refund: Google processes the refund and updates the corresponding order data. The order status will be updated to
Receive funds: Customer receives a refund notification. The money will be refunded to customer in a few days.
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:
- The customer return process.
- Polling for returns via the API.
- 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 to initiate a request for returnable items. Note that there are several factors determing whether an item is returnable, such as whether item return date has passed and whether theitem has already been returned.
Once the return request is received, Google creates a shipping label and sends the return started email to the customer with return instructions.
Merchant polls for returns
orderreturns.list method to find new returns in real time. If a return
is identified, use the carrier and tracking number provided to anticipate the
shipment and inform staff that a return package is being shipped back to your
location. Note that returns will still be shipped to your location, even if you
do not use this method to check for new returns.
Once you receive the package, use the
orderreturns.get method to retrieve the
return, review the packing slip and assess the package content to verify
that the package was returned for a valid reason. You can then decide whether to
accept the return.
If the return can be retrieved from Google, you can call
to either issue the refund or reject the return. For a refund, the retrieved
return data provides refundable price information to help you decide the refund
amount for each item.
If the return cannot be retrieved, the customer shipped the returned items
directly, without initiating a return with Google (this is rare).
In this case, you can call
orders.returnrefundlineitem to issue the refund
orders.rejectreturnlineitem to reject the return.
orders.returnrefundlineitem, setting the
priceAmount.value parameter to
0 indicates that you are accepting the return
of the item without issuing a refund to the customer. Sometimes one line item
has more than one quantity for a product, so 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 $10 each, call
orders.returnrefundlineitem with a
quantity of 2 and the
set to $20, or two times the product price of $10.
Google return processing
Once the return processing API call is received, Google starts the corresponding operations, such as issuing the refund, updating states and sending a notification to the customer.
Order refund-without-return process
The following diagram illustrates the process for issuing refunds that do not involve product returns.
Customer requests a refund: The customer requests a refund by contacting Google or the merchant directly. The customer specifies the reason they want a refund, such as a damaged good or an incorrect pricing charge.
Merchant Decides to Issue Refund
Accept or reject refund request: The merchant decides to accept or reject the refund request, based on the reason given by the customer. Refunds can be given for specific items or for the entire order.
Offer a Courtesy Refund: The merchant decides to offer a courtesy refund to the customer, without the customer requesting it. Refunds can be given for any reason, such as a price/tax adjustment.
Process Refund: The merchant processes the order for a refund. If the merchant wants to refund specific items or shipping, use
orders.refunditem, if the item level breakdown of the refund is not known use
orders.refundorder. Both methods accept partial and full refunds.
Issue Payment for Refund: Google processes the request and issues the refund or partial refund to the customer. Google then sets the
refundsattribute on the
Receive Funds: The customer receives a full refund or partial refund.