Orders API

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

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

The following sample cURL command creates an order using catalog items:

  1. Replace COFFEE_ITEM_ID with your catalog item ID and 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).

    For more information about line items, see the Orders API Technical Reference.

    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":{
              "location_id":"LOCATION_ID",
              "line_items":[
                 {
                    "catalog_object_id":"COFFEE_ITEM_ID",
                    "modifiers":[
                       {
                          "catalog_object_id":"SMALL_MODIFIER_ID"
                       }
                    ],
                    "quantity":"1"
                 }
              ]
           }
        }' \
    'https://connect.squareup.com/v2/orders'
    

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

The following sample cURL command creates an order with a line item:

  1. Replace name and quantity.

  2. Set base_price_money with a money object representing your cost. For more information, see Working With Monetary Amounts.

  3. Generate a unique string for your idempotency key.

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

    The following shows 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": {
        "location_id":"X9XWRESTK1CZ1",
        "line_items": [
          {
            "name": "Small Coffee",
            "quantity": "1",
            "base_price_money": {
              "amount": 500,
              "currency": "USD"
            }
          }
        ]
      }
    }' \
    'https://connect.squareup.com/v2/orders'
    

    For more information about line items, see the Orders API Technical Reference.

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": {
       "location_id":"X9XWRESTK1CZ1",
        "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/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 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 Permalink Get a link to this section

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

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.

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

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 -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": {
        "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"
        }]
    }
}' \
'https://connect.squareup.com/v2/orders'
LINE ITEM taxes and discounts Permalink Get a link to this section

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.

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.

The following example shows a 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": {
        "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"
        }]
    }
}' \
'https://connect.squareup.com/v2/orders'

Set the pricing option for automatically applying rule-based discounts Permalink Get a link to this section

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.

Related topics Permalink Get a link to this section