Introducing Curbside Pickup in the Orders API

In these unprecedented times, sellers must react to the rapidly changing business environment to survive and even thrive. This means enabling new fulfillment types, including those that reduce in-person interaction. That’s why today, we’re announcing the beta for a new “curbside” fulfillment option in our Orders API.

You might have already used the Orders API to create order-ahead apps with PICKUP or SHIPMENT fulfillment options. With curbside, you can extend order-ahead capabilities to offer no-contact pickup by adding fields to the existing PICKUP fulfillment type. When the customer arrives curbside, you (the buyer-facing app) send an update to the order and Square will send a notification right into the seller’s Square Point of Sale.

Create an Order with Curbside Fulfillment

The order must be created with the beta is_curbside_pickup boolean set to TRUE to distinguish it from a regular in-store pickup order. You can set curbside_details on the curbside pickup, such as, the courier or customer vehicle's make/model/year, license plate number, or perhaps a parking spot number.

Here’s an example of a fulfillment object within the order:

"fulfillments": [{
  "type": "PICKUP",
  "status": "PROPOSED",
  "pickup_details": {
    "recipient": {
      "display_name": "Super Man",
      "email_address": "[email protected]",
      "phone_number": "4045555555"
    },
    "pickup_at": "2020-04-23T13:45:00-04:00",
    "note": "I will fly by",
    "is_curbside_pickup": true,
    "curbside_pickup_details": {
      "curbside_details": "Honda Civic"
    }
  }
}],

The response will provide a UID for the fulfillment.

// This only shows the fulfillment section of the response
"fulfillments": [{
  "uid": "XpMGXCPHnQF64DeMudAE1C",
  "type": "PICKUP",
  "state": "PROPOSED",
  "pickup_details": {
    "pickup_at": "2020-04-23T17:45:00.000Z",
    "note": "I will fly by",
    "recipient": {
      "display_name": "Super Man",
      "email_address": "[email protected]",
      "phone_number": "4045555555"
    },
    "is_curbside_pickup": true,
    "curbside_pickup_details": {
      "curbside_details": "Honda Civic"
    }
  },
  "status": "PROPOSED"
}],
"created_at": "2020-04-23T11:49:38.775Z",
"updated_at": "2020-04-23T11:49:38.775Z",
"state": "OPEN",

When the order is created and paid for, the Square seller will see an order for curbside fulfillment in the Active order view. They can also filter by the fulfillment type:

NOTE: The order must be paid and have a valid fulfillment for it to appear on Order Manager.

Opening the order will reveal additional details on the order and pickup details.

When the Customer Arrives

When the customer arrives to pick up their order, you can send an update via Update Order with the arrival time and a notification will be sent to the seller’s Point of Sale notifying them of the customer’s arrival.

{
  "idempotency_key": "{{$guid}}",
  "order": {
    "version": 4,
    "fulfillments": [{
      "uid": "bO0Dqh0yU3nVSDnEDZBWdD",
      "pickup_details": {
        "curbside_pickup_details": {
          "buyer_arrived_at": "2020-04-23T19:07:00+00:00"
        }
      }
    }]
  }
}

If the seller has turned on their order alerts (Settings>Alerts>On), then the seller will get an alert in the POS showing who has arrived and the curbsides_pickup_details.

When the seller reviews the order details, they will also see a banner indicating that the seller has arrived:

We look forward to hearing from you as you use this new feature and continuing to iterate on it. We can’t wait to see what you build with this timely feature.

Feel free to reach out to us in our developer community via chat or our forums with any questions or requests you may have.