Retrieve sales data from an order
Merchants need accurate order data throughout the Shopify ecosystem so they can report on sales, reconcile accounts, and comply with tax laws. The GraphQL Admin API allows you to access sales data for detailed itemizations of sales-related changes on an order that you can use for auditing purposes.
This tutorial does the following:
- Introduces the concepts behind how Shopify manages sales data for orders.
- Shows how to accomplish some common tasks for querying sales data.
Sales agreements and sales
A sales agreement is a contract between a merchant and a customer to do business. Shopify creates a sales agreement whenever an order is placed, edited, or refunded. A sales agreement has one or more sales records, which provide itemized details about the initial agreement or subsequent changes made to the order.
For example, when a customer places an order, Shopify creates the order and generates a sales agreement and records a sale for each line item purchased in the order. A sale record is specific to a type of order line. Order lines can represent different things such as a purchased product, a tip added by a customer, shipping costs collected at checkout, and more.
The following are the sales agreements that can be returned:
The following are the sales types that can be returned:
One of the possible order line types for a sale is an adjustment. Sales adjustments occur when a refund is issued for a line item that is either more or less than the total value of the line item. Examples are restocking fees and goodwill payments.
When this happens, Shopify produces a sales agreement with sale records for each line item that is returned or refunded and an additional sale record for the adjustment (for example, a restocking fee).
The sales records for the returned or refunded items represent the reversal of the original line item sale value. The additional adjustment sale record represents the difference between the original total value of all line items that were refunded, and the actual amount refunded.
Every money value in the an order's sales data is represented to the currency's smallest unit.
When dividing certain amounts across multiple line items, such as taxes or order discounts, the amounts might not divide evenly across all of the line items on the order.
To address this, the remaining currency units that could not be divided evenly are allocated one at a time, starting with the first line item, until they are all accounted for. In aggregate, the values sum up correctly. In isolation, one line item might have a different tax or discount amount than another line item of the same price (before taxes and discounts) because the amount could not be divided evenly across the items.
The allocation of currency units across line items is immutable. After they are allocated, currency units are never reallocated or redistributed among the line items.
- You've created a development store.
- You've completed our Getting started with the GraphQL Admin and REST Admin APIs guide and you're authenticated with the API.
- You've created orders in your store.
- Your app has requested the
read_ordersaccess scope, which allows the app to read Shopify orders.
The following example shows all the available fields for querying the order history data:
1. Retrieve sales agreements for an order
To retrieve sales agreements for an order, you can query the
order field and request the
agreements field on the order.
The following example shows how to retrieve the first 10 sales agreements for an order. To learn about selecting which set of results to retrieve, refer to Paginating results with GraphQL.
The response body returns the initial sales agreement for the order and three corresponding sale records. Two records are for
ProductSale, which represents the line items for specific product sales. One record is for
ShippingLineSale, which represents the line item for a shipping fee.
2. Retrieve sales agreements for order edits
The following example retrieves the sales agreement for an order edit, where one product purchased is returned in exchange for a product variant at the same price.
The response includes the newly-added sales agreement for the edits to the order. The response includes two unique sale records. The product returned is indicated by
"quantity": -1. The second line represents the product variant ordered in exchange.
3. Retrieve a sales adjustment
You can retrieve sales adjustments for an order in instances where the amount of a refund might not match the original sale amount of the items returned.
In the following example, a product is returned and the merchant charges a restocking fee of 1 USD. After the refund is processed, a new sales agreement is generated, in addition to the three from the previous examples, with new two sale records. The first order line represents the return of the product at the original price, and the second represents the cost of the restocking fee.