This guide conforms to v2.1 of the Google Content API for Shopping and doesn't provide information on deprecated calls from v2.
This guide covers the following Orders processes:
- Lifecycle of an order
- Order return process
- Order refund-without-return process
- Reserve workflow process
- Not-delivered order process
Overview
An order
contains
line items that refer to one or more products and captures the following
information available at the time of purchase:
- Shipment method selected by the customer
- Customer's shipping address
- Customer's email preferences
Each order has an order status that indicates the progress towards completion
of the order. The order status is usually derived from the line items.
For example, if all the line items are shipped, the order status is
shipped
. If all the line items are returned and a refund is granted,
the order status is returned
. For the full description of an order,
see the orders resource
page.
Orders
Orders are created by customers and processed by merchants using the Google Content API for Shopping. These orders are then acquired, acknowledged, processed, and shipped out.
Summary of order process
Here are the steps in the order process:
- Customer places an order
- A customer places a new order on Google Shopping.
- Google checks the order and payment info
- Google confirms the order and
payment information. When the order is verified for payment, and after the
customer has time to change their mind, the status of the order changes to
pendingShipment
. Note that you shouldn't start your order fulfillment process until the order is inpendingShipment
status. - Merchant acknowledges the order
- Set the order flag to
acknowledged
, which helps you filter new orders. - Merchant checks item availability and reserves the ordered products
- Begin fulfillment and verify that the products are available for this order.
If you are using the Reserve process, verify this as well.
If a product is unavailable, notify Google and the entire order or a part of
the order is set to
canceled
. - Merchant charges the customer (optional)
- When you're ready to ship the
first item in the order, call
captureOrder
to charge the customer. If the charge succeeds, proceed to ship the item. If the charge fails, cancel the order. - Merchant ships the order and process the payment
- Ship the complete or
partial order within three days of your handling time. Use the API call
orders.shiplineitem
to mark the order as shipped. Google then completes the payment steps. - Merchant tracks the shipment
- Continue to track the shipment and update the order with tracking information. Google tracks this information for supported carriers.
- Google provides a shipment update
- Google sets the order status as
delivered
orpartiallyDelivered
when the complete order or partial order is delivered, or asundeliverable
if the order can't be delivered. Google requires you to use supported carriers and add valid tracking numbers to do this. - Google completes the payment
- Google completes the payment process and
invoice for
OrderInvoice
enabled merchants. When all the items in the order are shipped, the order status is set toshipped
. - Customer receives the order
- The customer receives the order and has the option to return it.
Detailed order process
Here is a more detailed look at the order process:
- Receive order
- The order process begins when a customer places an order. After the customer places an order, Google sends an order confirmation email that contains the Google order number.
- Check order and payment info
- 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 usingorders.acknowledge
. - Poll for new orders
- You can also fetch actionable orders with a periodic poll using the
orders.list
method withpendingShipment
as the filter for the status field. The polling interval (how often you poll for new orders) should be based on your anticipated order frequency or volume. - Reserved products and partial orders
- If the order's products are reserved, 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 using
orders.shiplineitem
for the reserved products. - Set merchant order ID
- Optionally, use
orders.updatemerchantorderid
to set your ID in the send merchant order ID to Google step. Google then sets the order status toacknowledge
. Calling any method on a given order other than retrieving its details automatically acknowledges the order. - Delays and cancellations
If you decide not to fulfill the order, cancel it by calling the
orders.cancel
method and passing a reason code for the cancellation. The order status is set tocancel
. Refer to the list of valid reason codes in the Orders resource.If you expect that your order can't be shipped on time, you should inform Google of the delay using
orders.updatelineitemshippingdetails
. This API call lets you set a newshipByDate
anddeliveryByDate
for alineitemId
in the order. If orders aren't shipped within three days of your handling time, they may be canceled automatically. Google respects the newshipByDate
anddeliveryByDate
in the order's auto-cancellation process, and informs the customer through email of the new delivery information for their order. Learn more about shipping policies for Buy on Google.If none of the items in the order are available, cancel the order using the
orders.cancel
method. If one or more line items are not available, cancel those line items individually using theorders.cancellineitem
method. The order status for those line items then changes tocanceled
.- Ship order
Next the merchant ships the order. Use
orders.shiplineitem
to ship the entire or partial order based on availability of the items in the order. The order status is updated toshipped
orpartiallyShipped
. If the order is partially shipped, there may still be some items in apendingShipment
state. After all the line items in an order are eithershipped
orcanceled
, the order status isshipped
.Google sends an email to the customer confirming the order details, and completes payment processing 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.- Create invoice
Optionally, enabled merchants can use the
orderinvoices.createchargeinvoice
API at a line item level for greater flexibility and granularity in generating invoices and calculating taxes. This updates the merchant order payment status topaymentCaptured
after being used for all line items. The line item status is then updated toshipped
, and a confirmation email is sent to the customer when the order is fully shipped. If you would like to use this resource, contact ourUS support team or France support team.- Update shipment status
Merchants are expected to track each shipment as a best practice. When an order is delivered, call
orders.updateshipment
to update the shipment status todelivered
(for supported carriers Google updates the status for you). If an order is not delivered, we continue with the not-delivered process.
Order completion
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 discussed below.
Not-delivered process
If the customer did not receive an order, you have to follow a well thought out 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
.
In addition, there are several different reasons that a customer may not receive
an order. For the following cases, call orderreturns.createorderreturn
to
initiate the return and then orderreturns.process
to process the return and
issue a refund:
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
orderreturns.process
, to have the order status changed by Google toreturned
and trigger a refund email confirmation to the customer by Google.If the shipment did not contain 100% of the order, use
orderreturns.process
to have the order status changed by Google topartiallyReturned
and have 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
orderreturns.process
. If you decide not to refund the item, the customer is still charged for the order.
Reserve process
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.
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
.
Returns
Customers can return an order in the following ways:
- Through the Google Shopping portal
- By contacting Google Customer Service
- In store
Merchants can use the orderreturns
service to
process their returns and issue refunds.
An Order
only assumes the returned
or partiallyReturned
status if the
following criteria are met:
- The merchant accepts the return
- The merchant calls
orderreturns.process
orordereturns.createorderreturn
The following diagram is a summary of the order return process.
Summary of process
The order return process:
Customer requests return: The customer returns the order directly through the order menu in the Google Shopping application, or by contacting Google's help center. The customer specifies the reason for the return, for example ordering the wrong item or the wrong size.
Google or the merchant reviews request:
Google reviews the return request: Google reviews the reason for the return request, and if approved, emails the customer a return shipping label as a PDF.
Merchant reviews the return request: If the merchant manages their own return policy, they upload the return shipping label for the customer. Once it's uploaded, the return is set to
new
return status.
Customer sends package: The customer prints the shipping label and ships the package. The package is shipped to the return address configured in Merchant Center.
Retrieve returns: The merchant continuously checks for new returns using the
OrderReturns
get
orlist
methods.Create return: If there are no returns found, the merchant can use
createorderreturn
to initiate a return.Process return: Merchant decides to accept or reject the return package with
process
.Google issues refund: Google processes the refund and updates the corresponding order data. The order status is updated to
returned
orpartiallyReturned
.Customer receives refund: Customer receives a refund notification. The money is refunded to their account 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 through 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 determining whether an item is returnable, such as whether item return date has passed and whether the item has already been returned.
If you choose to manage your own returns process in Merchant Center, the return status is set to
pending
when the return is created. After you upload the shipping label to the Merchant Center, the return status is updated tonew
. If you choose to use Google to manage the return process, Google creates the shipping labels and sends them to customers for your order returns. Order return statuses start asnew
for Google-managed returns.- Merchant polls for returns
Use the
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
orderreturns.process
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 or callorders.rejectreturnlineitem
to reject the return.- Google processes returns
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.
Refund-without-returns
The following diagram illustrates the process for issuing refunds that do not involve product returns.
Customer requests 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 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 useorders.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
refunds
attribute on theorders
resource.Receive funds: The customer receives a full or partial refund.