Orders with Fulfillment Dashboard Behavior

Questions
1

Hello:

We need the orders to show up in Merchant’s Dashboard, so “fulfillment” is added to each order.

There’s a strange behavior when a specific condition is met:

  1. An order is created via API
  2. The order has a fulfillment (state = PROPOSED, type = PICKUP)
Response has the following:
...ORDER:
    "state": "OPEN",
    "version": 1,
    "fulfillments": [
      {
        "uid": "Pz9pfqXmC0YMpiRdZZ6OPB",
        "type": "PICKUP",
        "state": "PROPOSED",

3a. If the order is $0, we use /pay with payment_ids = to finalize it
3b. If the order is >$0 we use /payments to finalize it
4. Since the order has a fulfillments it’s STATE is returned “OPEN”

The orders are now visible in Square Dashboard as “New, Paid”

image

  1. We update the order fulfillment to “state = COMPLETED” via API

The order disappears from the Square Dashboard. This is most likely because the order is FULFILLED, but still OPEN. (NOTE: If We update the order as Picked Up from the dashboard, The order remains visible in dashboard. Most likely because Square marks is as “COMPLETED” once fulfillments are completed)

  1. If we set order to COMPLETED by setting “state=COMPLETED”. The order is again visible in Square dashboard as “Completed, Paid”
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

Create Orders
Orders API
Square Developer

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

What is your application ID and are you testing in production or sandbox? :slightly_smiling_face:

4

Hi Bryan:

Sorry, I must have edited the question as you were responding.

The issue with “status/state” was due to the api-version header not being added on the fulfillment update. It looks like if “Square-Version” is not added to headers, then the ORDER response has “status” which must be some default version schema. Otherwise it has “state” (this seems to be true for all v2/orders).

The issue with the dashboard.

  • If the order is in “OPEN” state and has “PROPOSED” fulfillment - it is visible in the dashboard as NEW, PAID.

  • If we change only the fulfillment to “Completed”, the order disappears from the dashboard.

  • Once the “state” is set to “completed” - it appears in the dashboard again as COMPLETED, PAID

Here are 2 orders (production)

Visible in dashboard
ID : d25xhOVUeG4aCtCicizKgErXOJIZY
State = OPEN
Fulfillment State = PROPOSED

NOT Visible in dashboard
ID : rv2Xmcwtb9vHHUlXPY4sn1vqYH7YY
State = OPEN
Fulfillment State = COMPLETED

5

Hi Bryan:

Please see updated post and comment.

6

This is happening because the order is still open. If you change the state of the order to COMPLETED it will show in the Completed section of the Dashboard. Also you can UpdateOrder to complete both the fulfillment and the order in one call if you want. It would look like:

{
    "order": {
        "version": 3,
        "state": "COMPLETED",
        "fulfillments": [
            {
                "uid": "lDWWjyNgKXuWN00OmO86pB",
                "state": "COMPLETED"
            }
        ]
    }
}

:slightly_smiling_face:

7

Hi Bryan:

Right, so the order is in a somewhat “limbo” state from the dashboard’s perspective - it has been fulfilled and paid, but hasn’t been “completed”, so it is not visible in the dashboard, which probably filters out only specific states for order+fulfillment. It was just something that came up during QA and I wanted to verify with you.

Yes, we’re doing an “atomic” update on fulfillment and order state together.

The docs say that it may be possible for an order to have “multiple fulfillments” after creation, and even though we have not encountered (or tested) this yet, I am just wondering what would be the dashboard visibility on such orders : e.g. one fulfillment is “completed” and one is “pending” (for example for a multiple delivery orders). I guess we’ll cross that bridge when we get to it.

Thank you for you help.