How It Works

Take a deeper look at the Orders API.

Link to section

Orders objects and data types

Link to section

Orders

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"
            }
          }
        ]
      }'

Link to section

Line items

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 automatically pulls details about the catalog item into your order and automatically updates your inventory when the order is closed or charged.

You can also create a line item ad hoc (for example, if you do not have a catalog_id to reference). You need to define line item details, such as the name and price. Note that this does not create a catalog item.

Using existing catalog items means that you can track your inventory and more easily manage your catalog. You should start by setting up your catalog.

Link to section

Fulfillments

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

• A shipment order, which can track a customer's address where the order should be shipped.

• A pickup order, which can track delivery details, whether the order has been picked up, and other related details.

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

Link to section

Taxes and discounts

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 subtracted from the total. You can apply a discount or tax with an order scope at the order level, where it applies to the entire order total, or with a line item scope at the line item level, where it applies to the individual line item's price.

Link to section

Versions

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

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

Link to section

UIDs

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

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

ID fields are limited to 60 characters and are limited to letters, numbers, hyphens, underscores, and periods.

Link to section

Orders API process flow

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

Link to section

How totals are calculated

The Orders 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:

As an example, consider an online order at Raphael's Puppy-Care Emporium for two packages of Tendon pinwheel, one handmade sweater, and three 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".

The following taxes apply:

• A line-item percent tax on sweaters: "Fair Trade Tax: 5%".

• An order-level percent tax: "State Sales Tax: 8.5%"

Link to section

Rounding

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

However, 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)

For more information about rounding at Square, see Understanding Fee Rounding.

Link to section

Step 1: Calculate line-item gross totals

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

Link to section

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.

Link to section

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.

Link to section

Step 4: 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 that the line item contributes to the most recent subtotal using the following formula:

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:

Link to section

Step 5: Apply item-level fixed-amount discounts

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.

Link to section

Step 6: Apply order-level and item-level taxes

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

Link to section

Calculating order-level taxes and discounts

To calculate order-level taxes and discounts:

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

Link to section

Tax example

For example, suppose you apply a 9.25% sales tax to three dog collars that cost 3.50 USD each:

• Red Dog Collar: 3.50 USD with a 9.25% sales tax

• Blue Dog Collar: 3.50 USD with a 9.25% sales tax

• Yellow Dog Collar: 3.50 USD with a 9.25% sales tax

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

• 3.50 USD + 3.50 USD + 3.50 USD = 10.50 USD

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

• 10.50 USD x 0.0925 = 0.97125 USD

• 0.97125 USD rounds to 0.97 USD

Finally, distribute the tax proportionally to each individual item. Because 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

Link to section

Discount example

Suppose you want to calculate a 15% discount for three dog treats that cost 4.50 USD each:

• Dog Cookie: 4.50 USD with a 15% Discount

• Dog Bone: 4.50 USD with a 15% Discount

• Dog Banana: 4.50 USD with a 15% Discount

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

• 4.50 USD + 4.50 USD + 4.50 USD = 13.50 USD

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

• 13.50 USD x –0.15 = –2.025 USD

• –2.025 USD rounds to –2.02 USD

Finally, distribute the discount proportionally to each individual item. Because 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

Link to section

Reporting on orders

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

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

Link to section

Related topics

• Create Orders

• Pay for Orders

• Manage Orders