Duplicate Order Results from Search Orders API — Different IDs for Same Order

Questions
1

Hi Square Dev Team,

We’re encountering an issue when searching for orders using the Search Orders API.

The response sometimes includes multiple versions of what appears to be the same order, but each with a different id. This causes us to store the same order multiple times on our end.

Here are two examples from our recent API response:

Order A

{
  "id": "EGLZJbmHhDw9JabgPtMiKwZAzj9YY",
  "location_id": "L7V12XD2KYKCC",
  "line_items": [
    {
      "uid": "d4hoCp1kd6irtQovXJlcQB",
      "catalog_object_id": "I7V7IUDAHXXISOBQCRNYRD4C",
      "catalog_version": 1758094724005,
      "quantity": "1",
      "name": "Fleece Popover Jacket - Pink & Blue $ Check",
      "variation_name": "S",
      "base_price_money": { "amount": 7000, "currency": "USD" }
    }
  ],
  "fulfillments": [
    {
      "uid": "NDK73jFVJsbniWRxpMFlrB",
      "type": "SHIPMENT",
      "state": "PROPOSED",
      }
    }
  ],
  "created_at": "2025-09-17T08:19:18.355Z",
  "updated_at": "2025-09-17T08:43:33.958Z",
  "state": "OPEN",
  "version": 30,
  "reference_id": "468842787"
}

Order B

{
  "id": "IKwvRKILEG0BNUBIoJxAPc5YjzSZY",
  "location_id": "L7V12XD2KYKCC",
  "line_items": [
    {
      "uid": "XyZTeSnVWObsBsyeQ6XH0B",
      "catalog_object_id": "I7V7IUDAHXXISOBQCRNYRD4C",
      "catalog_version": 1758094724005,
      "quantity": "1",
      "name": "Fleece Popover Jacket - Pink & Blue $ Check",
      "variation_name": "S",
      "base_price_money": { "amount": 7000, "currency": "USD" }
    }
  ],
  "fulfillments": [
    {
      "uid": "j66fll1CvYZblwdUiNs6XC",
      "type": "SHIPMENT",
      "state": "PROPOSED",
      }
    }
  ],
  "created_at": "2025-09-17T08:46:46.128Z",
  "updated_at": "2025-09-17T08:48:50.026Z",
  "state": "OPEN",
  "version": 27,
  "reference_id": "733284391"
}

Both of these represent the same order in the Square Dashboard — same customer, same products — but they have different id and reference_id values.

We understand that the version field represents updates to the order, but in this case, it looks like two separate order objects entirely.

Question:
How should we determine the actual or canonical order reference when multiple IDs exist for what is clearly the same order? Is there a field or linking identifier we can rely on to group or deduplicate these?

2

:waving_hand: 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

Orders API
Square Order Checkout
Create Orders

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

This is expected with Square Online store orders. There are instances where it will create orders that will never be paid for. You should look for orders with tender_ids or payment_ids in them instead.

Our recommended flow would be to start with the payment from the Payments API. Then take the order_id in the payment to get the paid order. :slight_smile:

4

Hey Bryan,

Thanks for the reply. That’s exactly what we’re doing, but we’re running into issues with orders that have a 100% discount (used for promotional events). These orders don’t have tenders or payment information attached.

We’ve also encountered cases where a customer creates an order, then edits their email, which results in two versions of the same order with different IDs (causing duplicate on our end).

To address this, we currently skip orders without tenders or payments, but this also prevents us from processing legitimate promotional orders with full discounts.

For reference, see order ID 6jiUzy4RCY3TImRwCbyUGp1qU8eZY

Do you have any suggested workarounds for handling these cases?

5

You can parse the order for discounts that == 100% as well as parsing them for tenders and payment_ids. :slight_smile:

6

Bryan,

That doesn’t really address the issue.

Edited or non-final orders don’t include tenders or payment IDs.

Legitimate orders with a 100% discount also don’t have tenders or payment IDs.

So, if a 100% discount order gets edited — or if Square’s API happens to create a duplicate with different IDs — those orders would also lack tenders/payment IDs and would break your suggested parsing logic.

7

Do you have an example of an order that has a 100% discount with no tender or payment_id that is visible to the seller in the Dashboard? :slight_smile:

8

Do you have an example of an order that has a 100% discount with no tender or payment_id that is visible to the seller in the Dashboard? :slight_smile:

9

6jiUzy4RCY3TImRwCbyUGp1qU8eZY

10

In that case you’ll need to look at the net_amount_due_money and make sure it’s a 0 value. :slight_smile: