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, delivery_details, or in_store_details.

The Orders API supports fulfillments of these types:

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

• One fulfillment limit - Developers can add only one fulfillment to an order using the Orders API, either during or after creation.
• No fulfillment splitting - All items for an order created with the Orders API must be fulfilled at the same location.
• Limited delivery fulfillment support - Any order you create with the DELIVERY fulfillment type is not available to a seller and not shown in the Square Point of Sale unless you have a formal partnership agreement with Square. Please reach out to your Square Partner Manager to request Beta access. To become an app partner, submit a partnership request.
• Limited in-store fulfillment support - The IN_STORE fulfillment type is available as a restricted (closed) Beta. If your application isn't enrolled in the Beta, requests that include an IN_STORE fulfillment return an error. Reach out to your Square Partner Manager to request Beta access. To become an app partner, submit a partnership request.
• Only paid orders are visible - Orders with fulfillments appear on Square products (such as the Square 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).
  • delivery_details fields, such as the deliver_at or dropoff_notes field.
  • in_store_details fields, such as the note field.
  • 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.

A seller can create orders using your application or through Square products like Square Online. Orders retrieved by your application may have multiple fulfillments, which track the fulfillment of order line items across different seller locations.

For information about how a seller can create a multiple-fulfillment order using Square, see Manage cross location orders with Square for Retail.

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 scheduled for delivery ASAP but with a 30 minute prep time. Note the pickup_at time is 30 minutes after the order is created:

{
"order": {
  "id": "sfADX2Xqb8F4uZaFuAp3xlShefbZY",
  "location_id": "S8GWD5R9QB376",
  "line_items": [
…
  ],
    "fulfillments": [
        {
            "type": "PICKUP",
            "state": "PROPOSED",
            "uid": "pickup1",
            "pickup_details": {
                "schedule_type": "ASAP",
                "prep_time_duration": "PT30M15S",
                "recipient": {
                    "customer_id": "{{customer_id}}"
                }
            }
        }
    ],
}
}

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 SCHEDULED order becomes active immediately — behaving the same as an ASAP order — rather than waiting until the scheduled pickup time.

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 is a restricted (closed) Beta. You need to be a Square partner developer and have signed up for the closed DELIVERY Beta. Please reach out to your Square Partner Manager to request Beta access. To become an app partner, submit a partnership request.

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