Manage Order Fulfillments

A seller may add fulfillment information to an order when it's created or when it's 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)
Link to section

Multiple-fulfillment orders

A seller may 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 may 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 delivery 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.

Note

If your application retrieves a DELIVERY fulfillment order, it cannot access fulfillment delivery_details unless you are a Square partner developer and have signed up for the closed DELIVERY Beta. For more information, see DELIVERY type fulfillment.

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.

Link to section

SHIPMENT type fulfillment

The following Order fragment shows a SHIPMENT Fulfillment:

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.

Link to section

Fulfillment state changes

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
Link to section

PICKUP type fulfillment

This Order fragment shows a PICKUP Fulfillment:

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, pick_up_at is required.
    • If set to ASAP, prep_time_duration 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.
Link to section

Fulfillment state changes

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

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

DELIVERY type fulfillment

Note

This is a restricted (closed) Beta. Request Beta access by completing the participation survey.

Beta access to the DELIVERY fulfillment type is for use cases other than performing deliveries on behalf of sellers. Developers seeking to perform deliveries on behalf of sellers need a formal partnership agreement. To become an app partner, submit a partnership request.

This Order fragment shows a DELIVERY fulfillment:

Note the following about delivery_details:

Link to section

Requred delivery fields

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.
Link to section

Optional delivery fields

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).
Link to section

Third-party managed 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.
Link to section

Fulfillment state changes

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 - state changes to RESERVED
  • delivery_details.ready_at - state changes to PREPARED
  • delivery_details.canceled_at - state changes to CANCELED
  • delivery_details.rejected_at - state changes to FAILED
  • delivery_details.completed_at - state changes to COMPLETED.
Link to section

Create a fulfillment

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

Link to section

Example 1: Create an order with 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.

Create order

The following is an example response fragment:

Link to section

Example 2: Create an order and update the order to add fulfillment

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

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

    Update order

Note

To view the fulfillments for an existing order, call RetrieveOrder. The fulfillments appear in the Order.fulfillments object of the RetrieveOrder response.

Link to section

Update a fulfillment

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:

Update order

The following is an example response fragment:

Link to section

Best practices for updating a DELIVERY type fulfillment

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 completes successfully:

    • 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.
    • 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.
  • The seller or delivery service cancels the fulfillment:

    • 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.

  • A 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.

      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.

Link to section

Cancel a fulfillment

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

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.
Link to section

Split fulfillments

A seller may 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.

Link to section

Limitations of the API

  • 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.