Seeking clarity on the Orders API

Questions
,
1

Hi, I’d like some help understanding the lifecycle of an Order.

My use case is: I’m working with client restaurants offering a proprietary credits program that would allow customers to settle their balance using credits not processed as payments through Square. I’d like to:

  • Have my system sync with Square to know when there is an open Order
  • Notify the customer of the credits due and allow them to confirm transfer of their credits
  • Have the Square point of sale interface indicate to the cashier that the Order balance has been satisfied externally.

What I already have working:

  • Subscribing to webhooks so I know when an Order was created and the balance due
  • Notification through my system to the customer requesting payment via credits
  • Creation of a Payment object with EXTERNAL type through the Square API, including the Order id to reference back to the open Order that is being paid for

What I do not understand and need help with:

  • I have read different documentation and answers on this forum about how to set an Order to COMPLETED state
  • I don’t know if making the Payment attached to the Order is enough to designate the Order as completed or if there is more to do
  • I have tried to update the Order (after payment) to set to COMPLETED state, but it seems not to take effect… it remains in a state of OPEN
  • I have read that for Orders not created through the API they cannot be updated via the API, so I wonder if that’s what’s going on?
  • Ideally, I would like for the cashier to be able to see a visual confirmation in the POS dashboard UX indicating the credits payment went through so they know the balance is paid up, but I don’t know what property of an Order to update to make that obvious, OR how to use the API to achieve that.

I hope all the above is clear enough. The main point is: I want to make sure that after the payment happens, the cashier has a way of seeing that it is indeed paid so they can consider the sale completed by the customer. Thanks.

2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Order Fulfillments
Order-Ahead Application Use Case
Payouts API Overview

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

The lifecycle of an order in Square involves several stages. When an order is first created, it is in an ‘OPEN’ state. This means that the order has been initiated, but not yet paid for or fulfilled.

When you create a Payment object with the ‘EXTERNAL’ type and associate it with the Order ID, you are essentially marking that order as paid. However, this does not automatically change the state of the order to ‘COMPLETED’.

To change the state of an order to ‘COMPLETED’, you need to use the UpdateOrder endpoint of the Orders API. However, it’s important to note that only orders created via the API can be updated to ‘COMPLETED’ state using the API. If the order was created through the Square Point of Sale application or another non-API method, it cannot be updated to ‘COMPLETED’ via the API.

As for providing a visual confirmation to the cashier, the Square Point of Sale application will show the status of the order, including whether it has been paid. If the order was paid using an ‘EXTERNAL’ payment, this should be reflected in the order’s details. However, the specific details of how this information is displayed may vary depending on the version and configuration of the Point of Sale application.

In summary, to ensure that an order is marked as completed after payment, you should create the order via the API, create a Payment object with type ‘EXTERNAL’ and associate it with the order, and then update the order’s state to ‘COMPLETED’ using the UpdateOrder endpoint.

This answer was reviewed by @Bryan-Square.

4

Is your application the one creating the order from the Orders API or are you looking to read orders taken with the Square POS? :slightly_smiling_face:

5

Thanks for the quick reply. I am looking to read orders taken with the Square POS. Based on the answer above given by the Square-Dev-AI, and from what I’ve read, it seems like there is currently no way for me to update such an Order to COMPLETED state.

My intent is to give customers the best experience by avoiding any need to change their current workflow: if they already take orders through the Square POS, I don’t want to ask them to adopt a new tool for creating orders. I understand that if I did that, I could then create the order object with API, update it to COMPLETED state via API, and then choose how that state is reflected in the tool.

But, again, I was hoping to unobtrusively add this new behavior for customers using the Square POS. It sounds like you’re confirming my suspicion that there’s currently no way to do exactly that, unless I misunderstand the AI response. At least it’s helpful to know whether or not it’s possible.

6

Okay yeah, that is correct. Orders that are taken on the Square POS aren’t available till they’re fully paid for at this time. We hope to have more for you in the future. :slightly_smiling_face: