Manage Order Fulfillments

Applies to: Orders API

Learn how to create, update, cancel, and split an order fulfillment.

A seller might add fulfillment information to an order when it's created or updated. They can use Square products or your Orders API-integrated application to manage their fulfillments.

The Orders API stores fulfillment information in the Order.fulfillments field (an array of Fulfillment objects). Each Fulfillment includes the following:

• uid - A Square-assigned unique identifier.
• type - The type of fulfillment.
• state - Initially, the fulfillment state is PROPOSED.
• Fulfillment details - Depending on the type, fulfillment details are stored in pickup_details, shipment_details, or delivery_details.

The Orders API supports fulfillments of these types:

• DELIVERY (Beta)
• PICKUP
• SHIPMENT (Beta)

A seller might create orders using your application but can also create orders with Square products such as Square Online. In that case, orders that your application retrieves might have multiple fulfillments, as described in the following example scenario:

A buyer uses a quick service restaurant's Square Online store to order a taco combo and four carnitas burrito meals. Their office is on the same street as the restaurant so they walk down the block to pick up their order. While in the restaurant, they add a few more items to the order. The restaurant will deliver these new items to the office later. In this case, the order has two fulfillments: A PICKUP fulfillment for the taco combo and burrito meals and a DELIVERY fulfillment for the new items.

If your application lets sellers see the state of any order fulfillments in their Square account, then it should handle cases where the Order.fulfillments array contains multiple items. While your application can only create single-fulfillment orders, it has access to fulfillment orders created by Square applications.

The following Order fragment shows a SHIPMENT Fulfillment:

{
  "order": {
    "id": "uuVIIBP9Nl8L7xq6MJQayNuo8LdZY",
    "location_id": "S8GWD5R9QB376",
    "line_items": [
…
    ],
    "fulfillments": [
      {
        "type": "SHIPMENT",
        "shipment_details": {
          "recipient": {
            "display_name": "John Doe"
          }
        }
      }
    ]
  }
}

The recipient.display_name is the only shipment_details field required when a fulfillment is created. Other shipment_details fields are optional: carrier, shipping_note, shipping_type, tracking_number, and tracking_url.

As a SHIPMENT fulfillment order moves through stages, the fulfillment state is updated and corresponding timestamps are set:

• in_progress_at - state changes to RESERVED
• packaged_at - state changes to PREPARED
• shipped_at - state changes to COMPLETED
• canceled_at - state changes to CANCELED
• failed_at - state changes to FAILED

This Order fragment shows a PICKUP Fulfillment:

{
  "order": {
    "id": "sfADX2Xqb8F4uZaFuAp3xlShefbZY",
    "location_id": "S8GWD5R9QB376",
    "line_items": [
…        
    ],
  "fulfillments": [
    {
      "uid": "Beryz5QiHAwIfvFzBpYQ",
      "type": "PICKUP",
      "state": "PROPOSED",
      "pickup_details": {
        "pickup_at": "2016-05-21T23:59:33.123Z",
        "recipient": {
          "display_name": "John Doe"
        }
      }
    }
  ],
  }
}

The pickup_at and recipient.display_name fields are the only pickup_details fields required when creating a fulfillment. The following apply for the other pickup_details fields:

• The schedule_type value determines the following:
  • If set to SCHEDULED, pickup_at is required.
  • If set to ASAP, prep_time_duration or pickup_at is required.
• These fields can only be set while the order fulfillment state is PROPOSED: expires_at, auto_complete_duration, prep_time_duration, and schedule_type.

A scheduled order does not move to the 'Active' tab in Order Manager (and show up on a KDS or print from kitchen printers) until pickup time minus prep time. Although prep_time_duration is not required for the SCHEDULED type, Square recommends that your application sets the value. If a prep time is not provided, a seller using a KDS or kitchen printer might not know a SCHEDULED pickup is actionable until the time the buyer is supposed to arrive to pick up the order.

If the schedule_type is ASAP and the prep_time_duration is set then Square sets the pickup_at time to now plus prep_time_duration. If your application sets pickup_at for an ASAP pickup, prep_time_duration is ignored even if you've set that value too.

As a PICKUP fulfillment order moves through stages, the fulfillment state is updated and corresponding timestamps are set:

• accepted_at - The state changes to RESERVED
• ready_at - The state changes to PREPARED
• pick_up_at - The state changes to COMPLETED.
• canceled_at - The state changes to CANCELED
• rejected_at - The state changes to FAILED

This Order fragment shows a DELIVERY fulfillment:

{
   "order":{
      "id":"MgVVrx8GhOy4K7LO7LtYwgM3RUaZY",
      "location_id":"7WQ0KXC8ZSD90",
      "line_items":[
         {
         }
      ],
      "fulfillments":[
         {
            "uid":"uYJmomsp8OjA2iY8PZR2IC",
            "type":"DELIVERY",
            "state":"PROPOSED",
            "delivery_details":{
               "recipient":{
                  "display_name":"John Doe",
                  "phone_number":"2065129261",
                  "address":{
                     "address_line_1":"111 Maple",
                     "locality":"Seattle"
                  }
               },
               "deliver_at":"2022-05-25T20:59:33.123Z"
            }
         }
      ]
      "state":"OPEN",
      "version":1,
   }
}

Note the following about delivery_details:

The following information is required when creating a delivery fulfillment:

• recipient details - The display_name, address, and phone_number are required if there's no third-party managing delivery (managed_delivery is set to false).
• schedule_type - It can be set to SCHEDULED (default) or ASAP.
• deliver_at - If schedule_type is set to ASAP, this field is automatically set to the time the order is created plus the prep_time_duration. This field is required when schedule_type is set to SCHEDULED.

Applications can provide optional delivery_detail information, such as:

• prep_time_duration. The time it takes to prepare and deliver the fulfillment.
• A combination of deliver_at and delivery_window_duration identifying the order delivery window.
• Courier information (such as courier_provider_name, courier_support_phone_number, and the combination of courier_pickup_at and courier_pickup_window_duration identifying the courier pickup window).
• Other information (such as optional drop-off notes and whether the delivery is a no-contact delivery).

For a delivery managed by a third party:

• Set the managed_delivery field to true. This makes the recipient information optional, such as display_name and address.
• The courier_provider_name and courier_support_phone_number fields are required.

As an order moves through stages of fulfillment, the state of the fulfillment is updated and corresponding timestamps are set:

• delivery_details.in_progress_at - The state changes to RESERVED
• delivery_details.ready_at - The state changes to PREPARED
• delivery_details.canceled_at - The state changes to CANCELED
• delivery_details.rejected_at - The state changes to FAILED
• delivery_details.completed_at - The state changes to COMPLETED.

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

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

The following is an example response fragment:

{
  "order": {
    "id": "sfADX2Xqb8F4uZaFuAp3xlShefbZY",
    "location_id": "S8GWD5R9QB376",
    "line_items": [
      {
        "uid": "U0PzEdJgoOPWE7AxvCRldC",
        "quantity": "4",
        "name": "Sandwich",
        "base_price_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "note": "ad hoc 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 create an order and then update the order to add fulfillment. Note that you cannot add a fulfillment if the order state is COMPLETED.

1. Call CreateOrder to create an order without a fulfillment.

   Create order

   cURL

2. Call UpdateOrder to update the order and add fulfillment details. The example adds the PICKUP type fulfillment to the order.

   Update order

   cURL

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

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

The following is an example response fragment:

{
  "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,
  }
}

A DELIVERY type fulfillment completes when the items are delivered to the buyer. However, there are times when a seller (or deliver service) cancels the fulfillment or the fulfillment fails to complete. The following are the suggested best practices for an application to update an order as the DELIVERY type fulfillment progresses:

Fulfillment item is delivered

Before attempting to set a fulfillment.state to COMPLETED, the order must be paid for.

• If the fulfillment.state isn't COMPLETED:
  • Set FulfillmentDeliveryDetails.delivered_at to the timestamp when delivery occurred.
  • Set fulfillment.state to COMPLETED.
  • Set order.state to COMPLETED if no other fulfillments are pending and all payments on the order have been completed.
• If the fulfillment.state is COMPLETED (this can happen if a seller marks it as COMPLETED after they hand off the goods to the delivery service but before the delivery is completed):
  • The application can update delivered_at after a fulfillment is marked as COMPLETED but before the order state is COMPLETED. If deliver_at cannot be updated, the application might save the delivered_at timestamp as a note in the order.fulfillments.delivery_details.note field.
  • Set order.state to COMPLETED if no other fulfillments are pending and all payments on the order have been completed.

Fulfillment is canceled by the seller or delivery service

• Specify the cancellation reason in the FulfillmentDeliveryDetails.notes field.

• Set order.state to COMPLETED if no other fulfillments are pending.

• Set order.state to COMPLETED or CANCELED. Note that you cannot set order.state to CANCELED if:

  • A completed payment exists on the order.
  • The order contains a completed fulfillment. The seller needs to perform a refund in Square Point of Sale if necessary after the order is COMPLETED.

  Note that order.state cannot be set to CANCELED if the order contains a completed fulfillment. The seller needs to perform a refund in Square Point of Sale if necessary after the order is COMPLETED.

Fulfillment fails to complete

• Specify a reason why the fulfillment failed in the FulfillmentDeliveryDetails.notes field.

• Set fulfillment.state to FAILED.

• Set order.state to COMPLETED if all payments on the order have been completed.

  Note that order.state cannot be set to CANCELED if the order contains a completed fulfillment. The seller needs to perform a refund in Square Point of Sale if necessary after the order is COMPLETED.

You cannot delete a fulfillment from an order. You can only cancel a fulfillment using the UpdateOrder endpoint as shown:

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": {
      "version": 2,
         "fulfillments": [
      {
        "uid": "{FULFILLMENT_UID}",
        "state": "CANCELED"
       }
    ]
    }
  }'

In the request, you provide the Order object with the following information in the request body:

• The version of the order.
• The fulfillments array identifying the specific fulfillment. You provide the fulfillment UID being updated and specify the value of the state field as CANCELED.

A seller might split a fulfillment using Square products. The Orders API can retrieve 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.

• One fulfillment limit - Developers can add only one fulfillment to an order using the Orders API, either during or after creation.
• No fulfillment splitting - The Orders API doesn't support splitting a fulfillment.
• No Delivery Fulfillments - The Orders API does not support creating an order with the DELIVERY fulfillment type unless you have a formal partnership agreement with Square.
• Only paid orders are visible - Orders with fulfillments appear on Square products (such as the Seller Dashboard and Point of Sale application) only after they're paid for. Sellers can then manage fulfillments for these orders using these Square products.
• Immutable fields - Most fulfillment fields are immutable based on the fulfillment state. Editable fields include:
  • state (if the order is being managed through a developer's application).
  • pickup_details fields, such as the pickup_at or note field.
  • recipient field, such as address or phone_number.
  • shipment_details fields, such as tracking_number or tracking_url.