Manage Products

Orders API Overview

Capture itemized details about purchases and link those details to payment information.

The Orders API captures itemization details about purchases in an Order object that can be linked to a Square transaction. Orders can be built from [Catalog](#REPLACE ME) objects to simplify maintenance and reporting, or they can be built from ad-hoc line items defined at the time of Order object creation.

Requirements and Limitations

  • The Orders API does not support the Point of Sale API at this time.
  • Calls to the Orders API with OAuth tokens must have ORDERS_WRITE permissions. OAuth calls that work with Catalog objects must also have the ITEMS_READ permission.
  • The Orders API does not support an explicit shipping object. Shipping costs may be included as an ad-hoc line item or item modifier.
  • The Orders API does not support itemized refunds or returns.
  • The Orders API does not support update operations. To make changes to an order, you must create a new Order object.
  • The Orders API has sandbox support for ad-hoc items only. There is no sandbox support for orders built from Catalog items.

How to use it — the Orders API data model

The Orders API accepts a collection of line items, modifiers, discounts, and taxes to create a single Order object. Order objects have unique IDs that can be referenced in calls to other Square APIs. The key data types for the Orders API are:

  • Order — The top-level container for order information. Order objects include fields for line item details and order summary data like the location ID credited with the order and the total amount of taxes collected. A given Order object can include both ad hoc elements and elements that reference Catalog objects.
  • OrderLineItem — Represents a purchase item. Ad hoc line items include details such as name, price, and any applicable taxes and discounts. Line items built from Catalog objects include the catalog ID for an existing CatalogItemVariation object and an optional price, which will override any price information set in the CatalogItemVariation object.
  • OrderLineItemModifier — A modifier associated with the purchase item (e.g., available sizes for a dog sweater or custom engraving on a leather collar). Ad hoc modifiers include a name and price. Modifiers built from Catalog objects also include the catalog ID for an existing CatalogModifier object.
  • OrderLineItemDiscount — A discount applied to the associated line item. Ad hoc line item discounts include a name and discount amount. Discounts built from Catalog objects also include the catalog ID for an existing CatalogDiscount object.
  • OrderLineItemTax — A tax applied to the associated line item. Ad hoc taxes include a name and tax percentage. Taxes build built from Catalog objects also include the catalog ID for an existing CatalogTax object.

Order request objects versus Order data objects

The structure of a CreateOrder request object differs from the basic Order data object returned by the endpoint. CreateOrder request objects include taxes and discounts defined at the order level (where the price adjustment applies to everything in the order) in addition to taxes and discounts defined for a specific line item (where the price adjustment only applies to that line item). When the CreateOrder endpoint processes the request object, order-level taxes and discounts are converted to item-level price adjustments and distributed to each line item in the order. Converting order-level price adjustments to item-level price adjustments makes calculating the final cost of the order easier when the associated transaction is processed. The scope field in the returned Order object indicates whether a particular discount or tax was originally defined as an order-level or item-level price adjustment.

Additionally, name and price information for line items in the CreateOrder request object that reference a Catalog object ID are auto-populated in the returned Order object. Item name and price information come from the relevant CatalogItemVariation as defined in the product catalog (for the targeted location ID) at the time of order creation.

For example, suppose a customer orders a dog collar and some training treats. The dog collar is on sale and the customer has a discount code that applies to the entire order. The CreateOrder request includes line items for the products (dog collar and treats) and specifies the state tax and discount as order-level price modifiers.

When the CreateOrder endpoint receives the request, the order-level discount code and order-level tax are converted to item-level discounts and item-level taxes then applied it to every line item in the order. The end result is an Order object where order-level price adjustments map to line item adjustments with an order-level scope and item-level price adjustments map to line item adjustments with an item-level scope.

Data model diagram

Data limitations

A single Order request object may have up to 500 distinct references (including items, modifiers, taxes, and discounts) in accordance with the following limits. A single OrderRequest object may have:

  • Up to 100 discrete line items.
    • A single line item can have up to 25 Catalog item modifier references.
    • A single line item can have up to 25 taxes defined (ad-hoc or Catalog object ID).
    • A single line item can have up to 100 discounts defined (ad-hoc or Catalog object ID).
  • Up to 25 taxes defined at the order level (ad-hoc or Catalog reference).
  • Up to 25 discounts defined at the order level assigned (ad-hoc or Catalog reference).

Limits on price adjustments (taxes and discounts) apply to the CreateOrder request object, not the Order object returned by the CreateOrder endpoint. As a result, order-level adjustment limits do not impact item-level adjustment limits when CreateOrder converts the price adjustments during order creation.

For example: a CreateOrder request object can have 25 taxes defined on a single line item and another 25 order-level taxes even though it results in a total of 50 item-level taxes in the final Order object returned by CreateOrder.

Ad-hoc line items versus catalog items

The Orders API offers two options for defining line items:

  • Defining ad hoc items at the time of order creation.
  • Referencing an existing Catalog object ID.

Referencing Catalog object IDs

While referencing Catalog objects in orders might require extra work to get started, it simplifies long term maintenance and reporting. Square can use Catalog object IDs to track items across multiple orders and aggregate order information for reporting. Square can also report on inventory counts when track_inventory is enabled on the relevant CatalogItemVariation.

Referencing Catalog object IDs is best for:

  • Product catalogs with many unique item variations. If the service or product variant list is long, or includes multiple modifiers, creating a Square Catalog will ease long-term maintenance and management.
  • Multi-location and omnichannel business models. Aggregating information for businesses that have multiple locations (mobile, pop-up, different branches) or a storefront and an online store is easier with a shared product catalog.

Ad-hoc line items

While defining ad hoc order elements can make getting started easier, it can also make maintenance and reporting more challenging. Every unique string used to define an ad hoc element is considered a unique object. For example, "Red Dog collar - Leather", "Red Dog Collar - Leather", and "Red Dog collar Leather" are all considered different items because the strings use different punctuation, whitespace, and capitalization. The potential to create accidental duplicate products makes it difficult to report on product statistics for ad hoc orders.

To make the best use of Square's reporting with ad hoc items, which do not include inventory tracking, be consistent and explicit when naming items (e.g., "Red Dog Collar - Leather, customized").

Defining ad hoc objects is best for:

  • Applications that work with a product catalog already defined in a third-party application. The Orders API only supports Square's production Catalog. Ad hoc items may be the only choice if migrating to Square Catalog is not an option.
  • Integrations that require a quick solution. Using ad hoc items sacrifices the full functionality of Square's platform, but requires less work to set up.
Ad hoc diagram

Shipping

The Orders API does not have an explicit data type for shipping at this time. We recommend adding a standard line item to represent shipping costs, but note that including shipping costs as a line item subjects it to order-level taxes and discounts like any other line item.

Orders that include shipping fees can be constructed so that they avoid applying discounts or taxes to shipping costs in unexpected way. For example:

  • A CreateOrder request can define all taxes and discounts as item-level price modifiers and explicitly apply them to everything but the shipping cost line item.
  • A CreateOrder request can define an ad hoc discount that subtracts the expected value of the order-level tax from the shipping line item.

How it works — the Orders API process flow

High level process overview

In general, manually creating an order and linking it to a transaction involves the following steps:

  1. The application backend gathers order details and builds an CreateOrder request object.
  2. The application backend sends the CreateOrder request object to the CreateOrder endpoint.
  3. The CreateOrder endpoint creates an Order object and calculates a final purchase price based on the order details.
  4. Square returns the Order object to the application backend.
  5. The application backend extracts the order ID and creates a Transaction request object using the order ID.

alt_text

Order details are viewable in the Square Dashboard and through the BatchRetrieveOrders endpoint.

How totals are calculated

The Order API calculates, and applies, all discounts and taxes as line item price adjustments. Price adjustments defined as the item-level are applied directly to the applicable line item and order-level price adjustments are distributed across all line item subtotals.

The final purchase amount is calculated as follows:

  1. Calculate a starting gross price for each line item from the base price and quantity.
  2. Apply item-level percent discounts to the applicable line item totals.
  3. Convert and apply order-level percent discounts to all line item totals.
  4. Apply item-level fixed-amount discounts to the applicable line item totals.
  5. Convert and distribute order-level, fixed-amount discounts to all line item totals. The amount distributed to each line item is relative to that item's contribution to the order subtotal.
  6. Apply item-level and order-level taxes to all line item totals.

As an example, consider an online order at Raphael's Puppy-Care Emporium for 2 packages of Tendon pinwheel, 1 handmade sweater, and 3 packages of Chewy trainers, which includes the following discounts:

  • A item-level, percent discount on the Tendon pinwheels: "7% OFF — Discontinued item".
  • A item-level, fixed amount discount on the Tendon pinwheels: "$3.00 OFF — Customer Loyalty Discount".
  • A item-level, fixed amount discount on the Handmade sweater: "$11.00 OFF — Customer Loyalty Discount".
  • An order-level, percent discount: "12% OFF — National Puppy Day Sale".
  • An order-level, fixed amount discount: "$55 OFF — Global Sale".

And the following taxes:

  • A line item, percent tax on sweaters: "Fair Trade Tax: 5%".
  • An order-level, percent tax: "State Sales Tax: 8.5%"

Step 1: Calculate line item gross totals

The Orders API calculates the gross totals for each line item according to the item's base price and quantity.

Quantity Description Base Price Starting Item Total
(Quantity * Base Price)
2 Chicken Treats — Tendon pinwheel 15.00 USD 30.00 USD
1 Handmade sweater — Blue 50.00 USD 50.00 USD
3 Chicken Treats — Chewy trainers 12.00 USD 36.00 USD
ORDER SUBTOTAL $116.00

Step 2 : Apply item-level percent discounts

The Orders API applies item-level percent discounts to the applicable line items. Note that the Tendon pinwheel line item is the only item to receive 7% off.

Item Item Amount Final Amount
Chicken Treats — Tendon pinwheel 30.00 USD
7% OFF — Discontinued item (-2.10 USD) $27.90
Tendon pinwheel subtotal 27.90 USD
Handmade sweater — Blue 50.00 USD
Handmade sweater subtotal 50.00 USD
Chicken Treats — Chewy trainers 36.00 USD
Chewy trainers subtotal 36.00 USD
ORDER SUBTOTAL 113.90 USD

Step 3: Convert and apply order-level percent discounts

The Orders API applies order-level percent discounts to each individual line item. In this example that means every line item takes 12% off for a National Puppy Day sale.

Item Item Amount Final Amount
Chicken Treats — Tendon pinwheel 30.00 USD
7% OFF — Discontinued item (2.10 USD) 27.90 USD
12% OFF — National Puppy Day Sale (3.35 USD) 24.55 USD
Tendon pinwheel subtotal 24.55 USD
Handmade sweater — Blue 50.00 USD
12% OFF — National Puppy Day Sale (-6.00 USD) 44.00 USD
Handmade sweater subtotal 44.00 USD
Chicken Treats — Chewy trainers 36.00 USD
12% OFF — National Puppy Day Sale (-4.32 USD) 31.68 USD
Chicken treats subtotal 31.68 USD
ORDER SUBTOTAL 100.23 USD

Step 4: Apply item-level fixed-amount discounts

The Orders API applies item-level fixed-amount item discounts to the applicable line items. In this example, that means the Tendon pinwheels and the Chewy trainers receive a fixed amount discount.

Item Item Amount Final Amount
Chicken Treats — Tendon pinwheel 30.00 USD
7% OFF — Discontinued item (2.10 USD) 27.90 USD
12% OFF — National Puppy Day Sale (3.35 USD) 24.55 USD
$3.00 OFF — Customer Loyalty Discount (3.00 USD) 21.55 USD
Chicken Treats subtotal 21.55 USD
Handmade sweater — Blue 50.00 USD
12% OFF — National Puppy Day Sale (-6.00 USD) 44.00 USD
Handmade sweater subtotal 44.00 USD
Chicken Treats — Chewy trainers 36.00 USD
12% OFF — National Puppy Day Sale (-4.32 USD) 31.68 USD
$11.00 OFF — Customer Loyalty Discount (-11.00 USD) 20.68 USD
Chewy trainers subtotal 20.68 USD
ORDER SUBTOTAL 86.23 USD

Step 5: Convert and apply order-level fixed-amount discounts

Fixed-amount order-level discounts are converted to the equivalent item-level discount based on the relative portion the line item contributes to the most recent subtotal using the following formula:

`("Current Item Subtotal" / "Current Order Subtotal") xx "Order-Level Fixed Discount" = "Applicable Line Item Discount"`

In this example, the order-level, fixed discount is 55.00 USD and distributed across three line items based on a subtotal of 86.23 USD:

Item Item Amount Final Amount
Printed T-Shirt $21.55
Step 5: 55% OFF - Global Sales `("$21.55" / "$124.95" xx "55" = "-$9.49")` $12.06
Printed T-Shirt Subtotal $12.06
Chicken Treats — Tendon pinwheel

21.55 USD

55% OFF — Global Sales

((21.55 / 86.23) × 55.00 = -13.75)

13.75 USD

Tendon pinwheel subtotal

7.80 USD

Handmade sweater — Blue

44.00 USD

55% OFF — Global Sales

((44.00 / 86.23) × 55.00 = -28.06)

28.06 USD

Handmade sweater subtotal

15.94 USD

Chicken Treats — Chewy trainers

20.68 USD

55% OFF — Global Sales

((20.68 / 86.23) × 55.00 = - 13.19)

13.19 USD

Chewy trainers subtotal

7.49 USD

ORDER SUBTOTAL

31.23 USD

STEP 6: Apply order- and item-level taxes

The last step is to apply all the applicable taxes. Item-level taxes are applied first, then order-level taxes are distributed to each line item in the order.

Item

Item Amount

 </td>
 <td><p style="text-align: right">

Final Amount

 </td>
</tr>
<tr>
 <td>Chicken Treats — Tendon pinwheel
 </td>
 <td><p style="text-align: right">

7.80 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td>State Sales Tax: 8.5%

(7.80 × 0.085 = 0.66)

8.46 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td colspan="2" ><p style="text-align: right">

Tendon pinwheel subtotal

 </td>
 <td><p style="text-align: right">

8.46 USD

 </td>
</tr>
<tr>
 <td>Handmade sweater — Blue
 </td>
 <td><p style="text-align: right">

15.94 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td>State Sales Tax: 8.5%

(15.94 × 0.085 = 1.35)

17.29

 </td>
 <td>
 </td>
</tr>
<tr>
 <td colspan="2" ><p style="text-align: right">

Handmade sweater subtotal

 </td>
 <td><p style="text-align: right">

17.29 USD

 </td>
</tr>
<tr>
 <td>Chicken Treats — Chewy trainers
 </td>
 <td><p style="text-align: right">

7.49 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td>Fair Trade Tax: 5%

(7.49 × 0.05 = 0.37)

7.86 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td>State Sales Tax: 8.5%

(7.49 × 0.085 = 0.64)

8.50 USD

 </td>
 <td>
 </td>
</tr>
<tr>
 <td colspan="2" ><p style="text-align: right">

Chewy trainers subtotal

 </td>
 <td><p style="text-align: right">

8.50 USD

 </td>
</tr>
<tr>
 <td colspan="2" ><p style="text-align: right">

ORDER TOTAL

 </td>
 <td><p style="text-align: right">

34.25 USD

 </td>
</tr>
Prev
< Catalog API Overview
Next
Orders Setup Guide >

Ask for help on Stack Overflow or join our Slack channel