Orders API

How It Works

A deeper look at the Orders API.

Web
Backend
Orders API

Orders objects and data types
Permalink Get a link to this section

Orders
Permalink Get a link to this section

The entire Orders API is built around the Order object. Line items, taxes, discounts, and fulfillments are all defined at the order level.

{
        "idempotency_key": "UNIQUE_REQUEST_KEY",
        "reference_id": "my-coffee-order-001",
        "line_items": [
          {
            "name": "Coffee",
            "quantity": "1",
            "base_price_money": {
              "amount": 200,
              "currency": "USD"
            }
          }
        ],
          "fulfillments": [
          {
            "type": "PICKUP",
            "state": "PROPOSED",
            "pickup_details": {
              "recipient": {
                "display_name": "Amelia Earhart",
                "email_address": "Amelia.Earhart@example.com",
                "phone_number": "1-212-555-4240"
              },
              "expires_at": "2019-02-14T20:21:54.859Z",
              "auto_complete_duration": "P0DT1H0S",
              "schedule_type": "SCHEDULED",
              "pickup_at": "2019-02-14T19:21:54.859Z",
              "pickup_window_duration": "PT1H0S",
              "prep_time_duration": "PT20M",
              "note": "Pour over coffee"
            }
          }
        ]
      }'

Line items
Permalink Get a link to this section

Line items can be built in two ways:

  • By referencing a catalog item ID

  • By defining the line item ad hoc

You can define line items by simply referencing a catalog item by its catalog_object_id. Referencing the catalog_object_id will automatically pull details about the catalog item into your order. And it will automatically update your inventory when the order is closed or charged.

You can also create a line item ad-hoc, for example if you don’t have a catalog_id to reference. You would need to define line item details such as name, price. Note that this does not create a catalog item.

Using existing catalog items means that you can track inventory and more easily manage your catalog. It is worth it to start by setting up your catalog.

Fulfillments
Permalink Get a link to this section

Fulfillment orders are a type of order that can track additional fulfillment details required to close the order. Currently, we support two types of fulfillment orders:

  • Shipment Order that can track a customer’s address where the order should be shipped.

  • Pickup Order is a type of fulfillment order that can track delivery details and can track the status of whether the order has been picked up. Etc.

Fulfillment orders appear in the Square Point of Sale once they are charged. Note that fulfillment orders must have delay_capture set to true.

Taxes and discounts
Permalink Get a link to this section

Taxes and discounts are price modifiers that you can use to modify the total cost of an order or a line item. You have two options for creating line items for your orders:

  • Referencing catalog object IDs

  • Defining line items ad hoc.

You can specify whether the price modifier is a percentage of the total or a sum of money subtracted from the total. You can apply a discount or tax with an order scopeat the order level, where it will apply to the entire order total, or with a line item scopeat the line item level, where it will apply to the individual line item’s price.

Versions
Permalink Get a link to this section

Each Order object has a version number to track which is the most recent version of this Order. Orders will begin with a version value of 1 and each time an Order is updated, the version number will gain +1. When issuing an update request, the version is required, and it needs to match the latest version number.

This will help protect you from operating on a stale version of an order.

UIDs
Permalink Get a link to this section

Each object within the Order object has ID fields to uniquely identify them and to provide a key for specifying one message in a list.

IDs on objects can be specified as part of any CreateOrder or UpdateOrder request. If left unset, they will be generated by the server and included in the response. Any update to an existing field must include the ID on request.

ID field are limited to a length of 60 characters and are limited to letters, numbers, hyphens, underscores, and periods.

The Orders API process flow
Permalink Get a link to this section

In general, manually creating an order and linking it to a payment 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 Payment request object using the order ID.

diagram-orders-4@2x

Important

Managing order state is critical to ensure customers are properly charged. When an Order object is created, Square takes a snapshot of the state of the objects included and uses that snapshot to process the transaction. Even if the price of the item changes before the transaction completes, the Orders API will use that original price to calculate the total.

We strongly recommend you create Order objects immediately before processing the transaction. Otherwise, you will need to create a new Order object to capture any changes that occur.

How totals are calculated
Permalink Get a link to this section

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 the amount that item contributes 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 Chewy trainers: "$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%"

Rounding
Permalink Get a link to this section

The Orders API uses "round half to even" rules, known as bankers rounding, to calculate taxes and discounts. Under normal rounding rules, half-values round to the next closest integer. For example:

0.505 becomes 0.51 0.715 becomes 0.72 0.085 becomes 0.09

But under bankers rounding rules, half-values round to the closest even integer, which has the effect of "pulling" even numbers down while leaving odd numbers unchanged. For example:

0.505 becomes 0.50 (pulled down from 0.51) 0.715 becomes 0.72 (unchanged from normal rounding) 0.085 becomes 0.08 (pulled down from 0.09)

Learn more about rounding at Square.

Step 1: Calculate line item gross totals
Permalink Get a link to this section

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

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
Permalink Get a link to this section

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

(30.00 x 0.07 = −2.10 USD)

27.90 USD
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
Permalink Get a link to this section

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 27.90 USD
12% OFF — National Puppy Day Sale

(27.90 x 0.12 = −3.35 USD)

24.55 USD
Tendon pinwheel subtotal 24.55 USD
Handmade sweater — Blue 50.00 USD
12% OFF — National Puppy Day Sale

(50.00 x 0.12 = −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

(36.00 x 0.12 = −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
Permalink Get a link to this section

The Orders API applies item-level fixed-amount 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 24.55 USD
$3.00 OFF — Customer Loyalty Discount (−3.00 USD) 21.55 USD
Chicken Treats subtotal 21.55 USD
Handmade sweater — Blue 44.00 USD
Handmade sweater subtotal 44.00 USD
Chicken Treats — Chewy trainers 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
Permalink Get a link to this section

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

$$\displaystyle{\left(\frac{\text{Current Item Subtotal}}{\text{Current Order Subtotal}}\right)}\times\text{Order-Level Fixed Discount}=\text{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
Chicken Treats — Tendon pinwheel 21.55 USD
$55 OFF — Global Sales

$$\displaystyle{\left(\frac{21.55}{{86.23}}\right)}\times{55.00}=-{13.75}$$

7.80 USD
Tendon pinwheel subtotal 7.80 USD
Handmade sweater — Blue 44.00 USD
$55 OFF — Global Sales

$$\displaystyle{\left(\frac{44.00}{{86.23}}\right)}\times{55.00}=-{28.06}$$

15.94 USD
Handmade sweater subtotal 15.94 USD
Chicken Treats — Chewy trainers 20.68 USD
$55 OFF — Global Sales

$$\displaystyle{\left(\frac{20.68}{{86.23}}\right)}\times{55.00}=-{13.19}$$

7.49 USD
Chewy trainers subtotal 7.49 USD
ORDER SUBTOTAL 31.23 USD

Step 6: Apply order- and item-level taxes
Permalink Get a link to this section

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 Final Amount
Chicken Treats — Tendon pinwheel 7.80 USD
State Sales Tax: 8.5%

$$\displaystyle{\left({7.80}\times{0.085}\right)}=+{0.66}$$

8.46 USD
Tendon pinwheel subtotal 8.46 USD
Handmade sweater — Blue 15.94 USD
State Sales Tax: 8.5%

$$\displaystyle{\left({15.94}\times{0.085}\right)}=+{1.35}$$

17.29
Handmade sweater subtotal 17.29 USD
Chicken Treats — Chewy trainers 7.49 USD
Fair Trade Tax: 5%

$$\displaystyle{\left({7.49}\times{0.05}\right)}=+{0.37}$$

7.86 USD
State Sales Tax: 8.5%

$$\displaystyle{\left({7.49}\times{0.085}\right)}=+{0.64}$$

8.50 USD
Chewy trainers subtotal 8.50 USD
ORDER SUBTOTAL 34.25 USD

Calculating order-level taxes and discounts
Permalink Get a link to this section

How order-level taxes and discounts are calculated:

  1. Add up the total cost of all order items.

  2. Calculate the tax or discount for that item total.

  3. Distribute the tax or discount proportionally to each item.

If the tax or discount for the total cost of the group turns out to be an odd number, the remainder will be applied to one of the items in the group. This way, the total cost of the entire order remains accurate.

Tax example
Permalink Get a link to this section

For example, suppose we apply a 9.25% sales tax to 3 dog collars that cost 3.50 USD each.

  • Red Dog Collar — 3.50 USD with 9.25% sales tax

  • Blue Dog Collar — 3.50 USD with 9.25% sales tax

  • Yellow Dog Collar — 3.50 USD with 9.25% sales tax

First, we add up the total cost of the items:

3.50 USD + 3.50 USD + 3.50 USD = 10.50 USD

Next, calculate the total tax for the combined cost and use bankers rounding to round to the nearest even amount:

10.50 USD * 0.0925 = 0.97125 USD

0.97125 USD rounds to 0.97 USD

Finally, distribute the tax proportionally to each individual item. Since the total tax amount does not divide evenly by the total number of items, apply the remainder (0.01 USD) to one of the items:

  • Red Dog Collar — 3.50 USD + 0.32 USD = 3.82 USD

  • Blue Dog Collar — 3.50 USD + 0.32 USD = 3.82 USD

  • Yellow Dog Collar — 3.50 USD + 0.33 USD = 3.83 USD

Discount example
Permalink Get a link to this section

Suppose we want to calculate a 15% discount for 3 dog treats that cost 4.50 USD each.

  • Dog Cookie — 4.50 USD with 15% Discount

  • Dog Bone — 4.50 USD with 15% Discount

  • Dog Banana — 4.50 USD with 15% Discount

First, we add up the total cost of the items:

4.50 USD + 4.50 USD + 4.50 USD = 13.50 USD

Next, calculate the total discount for the combined cost and use bankers rounding to round to the nearest even amount:

13.50 USD * -0.15 = -2.025 USD

-2.025 USD rounds to-2.02 USD

Finally, distribute the discount proportionally to each individual item. Since the total discount amount does not divide evenly by the total number of items, apply the remainder (-0.01 USD) to one of the items:

  • Dog Cookie — 4.50 USD - 0.67 USD = 3.83 USD

  • Dog Bone — 4.50 USD - 0.67 USD = 3.83 USD

  • Dog Banana — 4.50 USD - 0.68 USD = 3.84 USD

Reporting on orders
Permalink Get a link to this section

All order details are available through the BatchRetrieveOrders and SearchOrders endpoints.

Fulfillment orders only appear in the Square Dashboard once they are charged. Note that fulfillment orders must have delay_capture set to true.

Next Steps

Use the build guides below to integrate with the Orders API