Orders API

Create Orders

Backend
Orders API

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

Create line items
Permalink Get a link to this section

You have two options for making line items.

  • You can make Orders using catalog_ids (Strongly recommended).

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

Option 1: Get the catalog_object_id for your line item
Permalink Get a link to this section

Here is a sample curl command that creates an order using catalog items.

  1. Replace the COFFEE_ITEM_ID with your catalog item ID and the SMALL_MODIFIER_ID with your catalog item variation ID.

  2. Generate a unique string for your idempotency key.

  3. Send a POST request to the CreateOrder endpoint ( /v2/orders).

See the Orders API Technical Reference for more details on line items.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "UNIQUE_STRING",
    "order": {
        "line_items": [{
            "catalog_object_id": "COFFEE_ITEM_ID",
            "modifiers": [{
                "catalog_object_id": "SMALL_MODIFIER_ID"
            }],
            "quantity": "1"
        }]
    }
}' \
'https://connect.squareup.com/v2/locations/{location_id}/orders'

Option 2: Define a line item ad hoc
Permalink Get a link to this section

Here is a sample curl command that creates an order with a line item for a

  1. Replace the name and quantity.

  2. Set the base_price_money with a money object representing your cost. See more about working with monetary amounts.

  3. Generate a unique string for your idempotency key.

  4. Send a POST request to the CreateOrder endpoint ( /v2/locations/{location_id}/orders).

Here is a sample JSON body for a curl command that creates an order using an ad-hoc line item.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
  "idempotency_key": "8193148c-9586-11e6-99f9-28cfe92138cf",
  "order": {
    "line_items": [
      {
        "name": "Small Coffee",
        "quantity": "1",
        "base_price_money": {
          "amount": 500,
          "currency": "USD"
        }
      }
    ]
  }
}' \
'https://connect.squareup.com/v2/locations/{location_id}/orders'

See the Orders API Technical Reference for more details on line items.

Add fulfillment details
Permalink Get a link to this section

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

This sample curl command creates a Pickup order for a small coffee.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "RANDOM_STRING",
    "order": {
        "line_items": [{
            "catalog_object_id": "COFFEE_ITEM_ID",
            "modifiers": [{
                "catalog_object_id": "SMALL_MODIFIER_ID"
            }],
            "quantity": "1"
        }],
        "fulfillments": [{
            "type": "PICKUP",
            "state": "PROPOSED",
            "pickup_details": {
                "recipient": {
                    "display_name": "Jaiden Urie"
                },
                "expires_at": "2019-02-14T20:21:54.859Z",
                "auto_complete_duration": "P0DT1H0S",
                "schedule_type": "SCHEDULED",
                "pickup_at": "2019-02-14T19:21:54.859Z",
                "note": "Pour over coffee"
            }
        }]

    }
}' \
'https://connect.squareup.com/v2/locations/{location_id}/orders'

Apply taxes and discounts
Permalink Get a link to this section

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

To apply a tax or discount, you need to:

  1. Define the tax or discount.

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

Step 1: Define the tax or discount
Permalink Get a link to this section

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

Here is a tax that references a catalog object ID:

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

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

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

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

  • ORDER scoped taxes and discounts will 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 will throw an error.

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "UNIQUE_STRING",
    "order": {
        "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"
        }]
    }
}' \
'https://connect.squareup.com/v2/locations/{location_id}/orders'

LINE ITEM taxes and discounts
Permalink Get a link to this section

A LINE_ITEM tax or discount will apply 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.

Did you know?

You can create LINE_ITEM taxes and discounts ahead of time without referencing them from any line items. Later, when you are ready for the tax or discount to come into effect, you can update the order to reference the tax or discount from the line item level.

Here is an example of an LINE_ITEM tax that applies to only one line item in the order:

curl -X POST \
-H 'Accept: application/json' \
-H 'Authorization: Bearer SELLER_ACCESS_TOKEN' \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-d '{
    "idempotency_key": "UNIQUE_STRING",
    "order": {
        "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"
        }]
    }
}' \
'https://connect.squareup.com/v2/locations/{location_id}/orders'

Next Steps

Learn to pay for or manage existing orders with the Orders API.