Create Orders

You can create Order objects by calling the CreateOrder endpoint. Orders objects can be created with any combination of line items, fulfillment objects, taxes, and discounts. They can also be created empty and updated with elements over time.

Create line items

You have two options for making line items:

• You can make orders using catalog_ids, which is strongly recommended.

• You can create line items ad hoc without referencing existing catalog items.

Option 1: Get the catalog_object_id for your line item

Option 2: Define a line item ad hoc

Add fulfillment details

To create a pickup order, you need to configure an OrderFulfillment object and set it in your order.

Apply taxes and discounts

You can apply taxes and discounts by referencing a catalog_object_id or by defining one ad hoc. Orders automatically pull in details about the price modifier and calculate the order total using the discount or tax.

To have a tax or discount applied to an order, you have two choices to make when creating or updating an order:

• Set the tax or discount on a order explicitly:

  1. Define the tax or discount.

  2. Set the scope to ORDER or LINE_ITEM. For LINE_ITEM-scoped taxes or discounts, reference the tax or discount at the line item level.

• Have rule-based discounts applied automatically to an order:

  1. Configure a pricing rule to set up the desired discounts.

  2. Enable the auto_apply_discounts option of OrderPricingOptions on an order for the rule-based discounts automatically applied to the order.

Configure and apply taxes or discounts explicitly

Complete the following steps to configure and apply taxes or discounts to an order explicitly.

Step 1: Define the tax or discount

You can define a tax or discount by referencing a catalog object ID or by defining the tax or discount ad hoc.

The following example shows a tax that references a catalog object ID:

 "taxes": [
    {
      "uid": "STATE_SALES_TAX_UID",
      "catalog_object_id": "STATE_SALES_TAX_CATALOG_ID",
      "scope": "ORDER"
    }
  ]

The following example shows a discount that is defined ad hoc:

 "discounts": [
     {
       "uid": "ADHOC_DISCOUNT_UID",
       "name": "Sale - $1.00 off",
       "amount_money": {
         "amount": 100,
         "currency": "USD"
       },
       "scope": "ORDER"
     }
   ]

Step 2: Set the scope for manually applying taxes and discounts

You need to set the scope field in your tax or discount to ORDER or LINE_ITEM. The scope you choose determines which line items it applies to:

• LINE_ITEM-scoped taxes and discounts apply to any line item that references the tax or discount UID.

• ORDER-scoped taxes and discounts apply to every line item in the order.

The following example call applies an order-scoped tax to every line item in the order. If your request references an order-level tax or discount from a line item, the endpoint throws an error.

curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UNIQUE_STRING",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "line_items": [
        {
          "catalog_object_id": "COFFEE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "SMALL_MODIFIER_ID"
            }
          ]
        },
        {
          "catalog_object_id": "COOKIE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "CHOCOLATE_MODIFIER_ID"
            }
          ]
        }
      ],
      "taxes": [
        {
          "uid": "STATE_SALES_TAX_UID",
          "catalog_object_id": "STATE_SALES_TAX_CATALOG_ID",
          "scope": "ORDER"
        }
      ]
    }
  }'

LINE ITEM taxes and discounts

A LINE_ITEM tax or discount applies only to line items that reference it. You can reference a tax or discount by setting the tax or discount UID in the line item's applied_taxes or applied_discounts field.

The following example shows a LINE_ITEM tax that applies to only one line item in the order:

curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2020-11-18' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "UNIQUE_STRING",
    "order": {
      "location_id": "X9XWRESTK1CZ1",
      "line_items": [
        {
          "catalog_object_id": "COFFEE_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "SMALL_MODIFIER_ID"
            }
          ]
        },
        {
          "catalog_object_id": "SODA_ITEM_ID",
          "modifiers": [
            {
              "catalog_object_id": "CHERRY_MODIFIER_ID"
            }
          ],
          "applied_taxes": [
            {
              "uid": "SODA_TAX",
              "discount_uid": "SODA_TAX_UID"
            }
          ]
        }
      ],
      "taxes": [
        {
          "uid": "SODA_TAX_UID",
          "catalog_object_id": "SODA_TAX_CATALOG_ID",
          "scope": "LINE_ITEM"
        }
      ]
    }
  }'

Set the pricing option for automatically applying rule-based discounts

If you have configured pricing rules, using either the Catalog API or Square Seller Dashboard, and want to apply rule-based discounts to an order, you must enable the auto_apply_discounts of PricingOptions in the order. The preconfigured pricing rule is triggered to apply the discounts automatically whenever an order is placed or modified.

View orders in the Seller Dashboard

An order appears in the Seller Dashboard if the following conditions are true:

• The order includes fulfillment.

• The order is paid.

If you are testing in the Square Sandbox, the order appears in the Seller Dashboard in Sandbox mode, but not in Production mode. For more information, see Sandbox Seller Dashboard.

Related topics

• Pay for Orders

• Manage Orders