Orders.created API

Is there any way to send a webhook call on all orders created (not just through the API webpoint)? Zapier seems to have this, but the zap does not include the order ID which I would need to retrieve order details from the API. My use case is that of a delivery driver needing to get alerted to any new delivery orders.

After I receive the order ID, I need to call the order API for the order details. I only want to take action on delivery orders though. There does not appear to be a field that shows order type in the API response though. Is there any way for me to filter the orders for deliveries only?

Hi @cyops welcome to the forums!

It looks like you have a few questions, so I’ll try to address them in order below:

  1. Order webhooks will only be sent for orders created explicitly by the API (CreateOrder endpoint). Other orders, like creating them through the Square POS, will not trigger a webhook.
  2. All orders will have an order_id (and furthermore, all payments will have an order even if you do not explicitly create one). The order.created webhook has the id in data->id.
  3. You’re right; the webhook doesn’t contain the full Order object so you’ll need to retrieve the order first. You can use SearchOrders to filter by fulfillment_type, although I don’t believe DELIVERY is a valid type. Currently, only Square Online (Weebly) supports delivery orders, but the public API does not unfortunately. If you are creating delivery orders through Weebly, then it may be possible for DELIVERY to work as a query parameter, but it’s not formally documented just to point out.

Please let me know if you have additional questions or concerns!

Ok, so I’m certain I understand:

  1. There is no way to send ALL orders via any API or hook that includes the full order object? How could a delivery person be notified if a customer calls an order in instead of placing the order through Square Online?

  2. Is there another hook for sending Square Online orders? I’ve tested a Square Online order with Zapier, and I can indeed receive a delivery order that includes a type flag of DELIVERY, however, the full order object is not passed over. It is missing delivery address, order id, and any line items. At a minimum, what I need to be able to do is receive all Square Online orders and have them include the order ID and type flag of DELIVERY. I could then use an API call to get the order details. Ideally there would be a hook that would send order id, type of order, line items, pickup time and delivery address. I find it odd that the whole point of square is to accept payments and sell things and the one thing the hooks can’t apparently do is send out a complete order object. Am I missing something?

  1. It doesn’t need to be through Square Online; Any API call that calls CreateOrder will trigger the webhook. With that said, if it’s created in a way without the API, it will not trigger the webhook, it solely depends on how you’re creating the order so if you want to discuss further please let me know how you’re creating the order. Otherwise, you’ll need to create your own logic to be notified (or register for payment webhooks instead to listen for, since unpaid orders do not push to Square Dashboard or Square POS).
  2. Since DELIVERY is not really available in the API, the details are not available unfortunately. The only way you can create a DELIVERY order is via Square Online, not the API, so the details are not through the API. There’s a few feature requests on the forums for this to be made available, but it currently doesn’t exist. As for the remaining details of the order object, you can simply retrieve it via the API when you receive the webhook via the order_id. The delivery_details will not be available, though, just to reiterate (everything else will be there; prices, items, times, etc).

So, unless I’m mistaking your answers, it appears that the only way for a Square customer to interface with a delivery company is by using one of Square’s delivery partners like Door Dash. Square has purposefully made it impossible to work with other delivery providers and even charges its customers $.50 an order for selecting delivery if they don’t use a Square Partner. Your API has no ability to send out to a hook that a delivery order was made. Even your payment.created hook sends out the order_id as a hashed value, so it can’t be used it to get order details. None of your endpoints can deliver a full order object that includes a delivery address. I have five restaurant clients that use Square as their POS and also use Square Online. They all want to use a 3rd party delivery service from anybody but Postmates, Door Dash, Uber Eats, etc. Unfortunately, we can’t even connect them to an app for their own delivery drivers because your API does not support sending a full order object or even the bare minimum details about an order that would allow us to retrieve the order details we need to make a delivery.

Can you clarify this or provide examples? That should not be the case at all.

As for the rest - yes, I know, and it’s unfortunate. You can definitely use SHIPMENT as the type of order as a workaround, while DELIVERY is still in the works. It’s one of the top feature requests (you can find it in the forums more than once, I believe), and the team is well aware that it’s a feature. It’s definitely not being hidden to make you pay for other services, it’s just not currently in a state to be made public, but there’s work being done to make it available.

Also, I’m still not sure what you mean by “sending a full order object”. As I mentioned before, the webhook will include the order_id, which you can then to just simply retrieve the order if you want the rest of the order…so you can get the full order object if you get the webhook.

My example is that I received a payment notification with an order_id of 750vgzk2FKbMbqUEwmTKmuTApLUZY. This corresponds to order number 173601250 in the POS or order dashboard. It is not clear which of these numbers is used to call for order details. If it is the long hashed value though, it is not useful to use as an order number for pickup.

In my use case, a full order object includes all the data that is needed to dispatch a driver. This includes a human readable order number, delivery time, delivery address, line items, and customer name.

750vgzk2FKbMbqUEwmTKmuTApLUZY is the order_id. You can retrieve it using the RetrieveOrder endpoint; the other is a visible number on the Seller Dashboard that is auto-assigned by Weebly. I’m not sure what you mean by not useful; it’s simply the id that is assigned on the backend used for finding the order.

Got it, thanks for clarifying. Since they’re being created by Weebly (and not by your application), then you’re correct: there’s no way to get the full delivery details, I just wasn’t clear where the orders were being created from. This is the feature request that the team is working on but I do not have an ETA on when it will be available unfortunately.

When using the shipment API ORDERS Field to create shipment orders. Is there a way to in realtime display ship fees on the orders on the front end of the Square UI? If you could do this then you could use the spilt payment API to take the shipment fee ?

Also is there a way to charge the sellers account for shipment fees- if they are not captured during the transaction?

:wave: Is this with the Square online store or with a custom application your building? If it’s with the Square online store there isn’t a way to programmatically update the order and have it change and display the shipping cost while the customer is checking out.

If your building a custom application you can UpdateOrder to show your customer any updates to the shipping cost as they’re checking out prior to making the payment. :slightly_smiling_face: