Learn how to create and manage order fulfillment using the Square Orders API.
Orders API

Manage Order Fulfillments

A seller can optionally add fulfillment information to an order when it is created or after it is created. Sellers can use Square first-party products or custom applications using the Orders API to manage fulfillments.

Applications can use the Orders API to add fulfillments of the following types:

  • PICKUP type fulfillment. For example, suppose a customer in a gardening store buys flowers and a large bag of dirt. The customer takes the flowers immediately but chooses to pick up the dirt later in the day. In this case, the seller creates two fulfillments of the PICKUP type.

  • SHIPMENT type fulfillment. For example, suppose a customer orders a shirt and two pairs of shoes (red shoes and white shoes). The seller might create one fulfillment to ship all items in a single shipment. Suppose the red shoes are not in stock. The seller then chooses to ship the red shoes at a later date. The order then has two fulfillments.

The Order object stores fulfillment information in the Order.fulfillments field, which is an OrderFulfillment object.

  • Orderfulfillment.type indicates the fulfillment type (PICKUP or SHIPMENT).

  • Depending on the fulfillment type, the Orderfulfillment.pickup_details or Orderfulfillment.shipment_details field stores the relevant information. For example:

    • Orderfulfillment.pickup_details includes information such as the recipient (customer ID, phone number, and email address), the pickup time, and whether it is a curbside pickup.

    • Orderfulfillment.shipment_details includes information such as the shipping carrier, the time when the shipment is expected to be delivered to the shipping carrier, and recipient information.

  • Orders with fulfillment appear on Square first-party products (such as the Seller Dashboard and Point of Sale application) only after they are paid for. Sellers can then manage fulfillments for these orders using these first-party products.

  • Applications can add only one fulfillment to an order using the Orders API, either during or after creation. The Orders API does not support splitting a fulfillment.

    A seller can optionally split the fulfillment using first-party products and applications can view these split fulfillments. For example, the Order.fulfillments object includes two fields (entries and line_item_application) that applications can use to determine which line items belong to which fulfillment.

  • Applications can use the Orders API to apply limited fulfillment updates such as:

    • The fulfillment state (if the order is being managed through a developer's application rather than Square Order Manager).

    • Pickup details such as the pickup_at or note field.

    • Recipient details such as address or phone.

    • Shipment details such as tracking_number ortracking_url.

    You can also apply other fulfillment updates but, in the current implementation, these updates might not reflect the Order Manager in Square first-party products. Therefore, sellers should use first-party products to perform other fulfillment updates.

  • Applications can use the Orders API to create a fulfillment of the PICKUP and SHIPMENT types.

    Currently, only Square Online supports creating fulfillments of the DELIVERY type; other first-party products (such as the Point of Sale application and Seller Dashboard) do not. When applications retrieve an order using the API, they see the DELIVERY type fulfillment but they do not see other delivery details of the fulfillment.

  • When a seller splits a fulfillment, both fulfillments are of the same type. All fulfillments in an order are the same type. To change the fulfillment type, you must first move the fulfillment to the CANCELED state and then add another fulfillment of the type you want.

Applications can create an order with fulfillment or first create an order and later update the order to include fulfillment.

This example CreateOrder request creates an order for four sandwiches. The order includes fulfillment details (the order type is PICKUP and the customer John Doe has selected curbside pickup at a specific time).

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
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "name": "Sandwich",
          "note": "adhoc item",
          "base_price_money": {
            "amount": 1500,
            "currency": "USD"
          },
          "quantity": "4"
        }
      ],
      "fulfillments": [
        {
          "pickup_details": {
            "is_curbside_pickup": true,
            "pickup_at": "2022-02-12T23:00:00.000Z",
            "recipient": {
              "display_name": "John Doe",
              "phone_number": "111-111-1111"
            }
          },
          "type": "PICKUP"
        }
      ]
    }
  }'

The following is an example response fragment:

  • 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
{
  "order": {
    "id": "sfADX2Xqb8F4uZaFuAp3xlShefbZY",
    "location_id": "S8GWD5R9QB376",
    "line_items": [
      {
        "uid": "U0PzEdJgoOPWE7AxvCRldC",
        "quantity": "4",
        "name": "Sandwich",
        "base_price_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "note": "adhoc item",
        "gross_sales_money": {
          "amount": 6000,
          "currency": "USD"
        },
    …
    ],
    "fulfillments": [
      {
        "uid": "VnDwb1Yu42mMjrPEWHLYW",
        "type": "PICKUP",
        "state": "PROPOSED",
        "pickup_details": {
          "pickup_at": "2022-02-12T23:00:00.000Z",
          "recipient": {
            "display_name": "John Doe",
            "phone_number": "111-111-1111"
          },
          "is_curbside_pickup": true
        }
      }
    ],
 …
  }
}

In this example, you first create an order and then update the order to add fulfillment.

  1. Call CreateOrder to create an order without fulfillment.

    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: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "line_items": [
            {
              "name": "Sandwich",
              "note": "adhoc item",
              "base_price_money": {
                "amount": 1500,
                "currency": "USD"
              },
              "quantity": "4"
            }
          ]
        }
      }'
  2. Call UpdateOrder to update the order and add fulfillment details.

    Update 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
    curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
      -X PUT \
      -H 'Square-Version: 2022-09-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "order": {
          "location_id": "{LOCATION_ID}",
          "fulfillments": [
            {
              "type": "PICKUP",
              "pickup_details": {
                "is_curbside_pickup": true,
                "pickup_at": "2022-02-12T23:00:00.000Z",
                "recipient": {
                  "phone_number": "111-111-1111",
                  "display_name": "John Doe"
                }
              }
            }
          ],
          "version": 1
        }
      }'

In the current implementation, there are limitations to updating fulfillments using the API. For more information, see Guidelines and Limitations.

Suppose you created an order for an ad hoc item. The following example UpdateOrder command updates the fulfillment state, recipient display name, pickup detail note, and recipient display name:

Update Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
curl https://connect.squareupsandbox.com/v2/orders/{order_id} \
  -X PUT \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "fulfillments": [
        {
          "state": "PREPARED",
          "pickup_details": {
            "note": "updated note",
            "recipient": {
              "display_name": "Jane Doe"
            }
          },
          "uid": "VnDwb1Yu42mMjrPEWHLYW"
        }
      ],
      "version": 1
    }
  }'

The following is an example response fragment:

  • 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
{
  "order": {
    "id": "sfADX2Xqb8F4uZaFuAp3xlShefbZY",
    "location_id": "S8GWD5R9QB376",
    "line_items": [
      {
        …
      }
    ],
    "fulfillments": [
      {
        "uid": "VnDwb1Yu42mMjrPEWHLYW",
        "type": "PICKUP",
        "state": "PREPARED",
        "pickup_details": {
          "pickup_at": "2022-02-12T23:00:00.000Z",
          "note": "updated note",
          "accepted_at": "2022-02-26T00:24:07.316Z",
          "ready_at": "2022-02-26T00:24:07.316Z",
          "recipient": {
            "display_name": "Jane Doe",
            "phone_number": "111-111-1111"
          },
          "is_curbside_pickup": true
        }
      }
    ],
    …
    "version": 2,
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.