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.

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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"
        }
      ]
    }
  }'
    Try in API Explorer

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:

    Create Order
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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"
          }
        }
      ]
    }
  }'
    Try in API Explorer

    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 command creates a pickup order for a small coffee:

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
  • 36
  • 37
  • 38
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2021-02-26' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -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"
          }
        }
      ]
    }
  }'
Try in API Explorer

View orders in the Seller Dashboard Permalink Get a link to this section

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