The source field of an POS order has been changed

wsdzy2010 · December 15, 2022, 8:40pm

Previously, we use source to differ different sources of orders. For example, if the order is created by order API on KIOSK, we will add a specific name: KIOSK as the source, so that when we get the order from Square, we can apply different logics based on its source.

For the order created from Square POS, since there is no document and its source is always undefined or null as we observed, then we use undefined or null to identify it. However, recently there is merchant Square POS created the order with source equals to {}, then it causes some errors on our handle process. We want to know is the source stable. Why the source value has been changed from undefined to {}. If it’s not stable, how can we know whether an order created from Square POS or not?

The previous order details with source undefined:

{
  "order": {
    "id": "3jKOopXRcf29TSz87IUiqY5eV",
    "location_id": "L50C4RKGJWEB5",
    "line_items": [
      {
        "uid": "09A5D543-2AE7-4733-BB88-06DACF59AEB7",
        "catalog_object_id": "RMLJCSBVREDY67WBMEACI5SV",
        "catalog_version": 1666833071177,
        "quantity": "1",
        "name": "1 pc Mochi Donut",
        "variation_name": "Regular",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "modifiers": [
          {
            "uid": "DC4FB22F-15CB-4CFC-AB3B-AE1B6DE14E91",
            "base_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "name": "Mango",
            "catalog_object_id": "WHEKCNP4ZLXZF4VUJNFWI552",
            "catalog_version": 1661099056038,
            "quantity": "1"
          }
        ],
        "gross_sales_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 39,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 339,
          "currency": "USD"
        },
        "variation_total_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "applied_taxes": [
          {
            "uid": "A15C2719-4207-4C29-B701-DE650A7F2447",
            "tax_uid": "3D11B5C9-0DB4-4CEB-8B1D-260D45DC5BE6",
            "applied_money": {
              "amount": 27,
              "currency": "USD"
            }
          },
          {
            "uid": "F5E47784-ABA8-43E8-9952-0DCCEDEE99FC",
            "tax_uid": "97529A05-0605-4700-B85B-C0ED6B0E7B23",
            "applied_money": {
              "amount": 12,
              "currency": "USD"
            }
          }
        ],
        "item_type": "ITEM"
      },
      {
        "uid": "692D397E-627C-4128-A90B-EE27195CF4AF",
        "catalog_object_id": "RMLJCSBVREDY67WBMEACI5SV",
        "catalog_version": 1666833071177,
        "quantity": "1",
        "name": "1 pc Mochi Donut",
        "variation_name": "Regular",
        "base_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "modifiers": [
          {
            "uid": "497CFE8A-3B24-43F2-BB81-3AD8AC2A9F57",
            "base_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "name": "Taro",
            "catalog_object_id": "CHHM7TBEWX35RBM6ZG2UW3V6",
            "catalog_version": 1661099056038,
            "quantity": "1"
          }
        ],
        "gross_sales_money": {
          "amount": 300,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 39,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "total_money": {
          "amount": 339,
          "currency": "USD"
        },
        "variation_total_price_money": {
          "amount": 300,
          "currency": "USD"
        },
        "applied_taxes": [
          {
            "uid": "A069485D-5A46-4144-BEE6-F8B47E65F2B5",
            "tax_uid": "3D11B5C9-0DB4-4CEB-8B1D-260D45DC5BE6",
            "applied_money": {
              "amount": 27,
              "currency": "USD"
            }
          },
          {
            "uid": "7C1EF89C-76B9-4775-824E-8F2BDE90FB61",
            "tax_uid": "97529A05-0605-4700-B85B-C0ED6B0E7B23",
            "applied_money": {
              "amount": 12,
              "currency": "USD"
            }
          }
        ],
        "item_type": "ITEM"
      }
    ],
    "taxes": [
      {
        "uid": "97529A05-0605-4700-B85B-C0ED6B0E7B23",
        "catalog_object_id": "Z55ZVJ52ISA4JIOZ2GFMX22Q",
        "catalog_version": 1661183031004,
        "name": "Service Charge",
        "percentage": "3.99",
        "type": "ADDITIVE",
        "applied_money": {
          "amount": 24,
          "currency": "USD"
        },
        "scope": "LINE_ITEM"
      },
      {
        "uid": "3D11B5C9-0DB4-4CEB-8B1D-260D45DC5BE6",
        "catalog_object_id": "OEGHEI4L4SV3I3HV2ZHCJFVF",
        "catalog_version": 1660940117887,
        "name": "sales tax",
        "percentage": "9",
        "type": "ADDITIVE",
        "applied_money": {
          "amount": 54,
          "currency": "USD"
        },
        "scope": "LINE_ITEM"
      }
    ],
    "created_at": "2022-12-13T21:04:26Z",
    "updated_at": "2022-12-13T21:04:26Z",
    "state": "COMPLETED",
    "total_tax_money": {
      "amount": 78,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_tip_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_money": {
      "amount": 678,
      "currency": "USD"
    },
    "closed_at": "2022-12-13T21:04:26Z",
    "tenders": [
      {
        "id": "xxxxx",
        "location_id": "L50C4RKGJWEB5",
        "transaction_id": "xxxxx",
        "created_at": "2022-12-13T21:04:22Z",
        "amount_money": {
          "amount": 678,
          "currency": "USD"
        },
        "processing_fee_money": {
          "amount": 39,
          "currency": "USD"
        },
        "customer_id": "xxxxx",
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "MASTERCARD",
            "last_4": "xxxxx",
            "fingerprint": "xxxxx"
          },
          "entry_method": "KEYED"
        },
        "tip_money": {
          "amount": 0,
          "currency": "USD"
        }
      }
    ],
    "total_service_charge_money": {
      "amount": 0,
      "currency": "USD"
    },
    "return_amounts": {
      "total_money": {
        "amount": 0,
        "currency": "USD"
      },
      "tax_money": {
        "amount": 0,
        "currency": "USD"
      },
      "discount_money": {
        "amount": 0,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "service_charge_money": {
        "amount": 0,
        "currency": "USD"
      }
    },
    "net_amounts": {
      "total_money": {
        "amount": 678,
        "currency": "USD"
      },
      "tax_money": {
        "amount": 78,
        "currency": "USD"
      },
      "discount_money": {
        "amount": 0,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "service_charge_money": {
        "amount": 0,
        "currency": "USD"
      }
    },
    "net_amount_due_money": {
      "amount": 0,
      "currency": "USD"
    }
  }
}

The recent order with {} source:

{
  "order": {
    "id": "bRb7CZjt88jJDI7bVAhvUS17afOZY",
    "location_id": "L50C4RKGJWEB5",
    "line_items": [
      {
        "uid": "5F4B57C8-E0EB-4A41-952F-078DEAADDA82",
        "catalog_object_id": "FOHRGNMCBC6AZPNR43NZHDHE",
        "catalog_version": 1666833071177,
        "quantity": "1",
        "name": "Caramel Bubble Milk Black Tea W. Oreo & Milk Foam",
        "variation_name": "Regular",
        "base_price_money": {
          "amount": 750,
          "currency": "USD"
        },
        "modifiers": [
          {
            "uid": "5A206853-13E5-405F-AFDD-663DFA6D4E55",
            "base_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "name": "Regular Ice",
            "catalog_object_id": "R7V7KUMRCR3KXAMK2D5YZ5XU",
            "catalog_version": 1660940610188,
            "quantity": "1"
          },
          {
            "uid": "BFB5A4C7-457A-4784-84A1-8D83CF55258E",
            "base_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 0,
              "currency": "USD"
            },
            "name": "100% Sugar",
            "catalog_object_id": "J2P27WP4SJHOR7KI4KHVEFEI",
            "catalog_version": 1661096568688,
            "quantity": "1"
          },
          {
            "uid": "F40C0D09-B7C9-4BE6-8979-BB429B4B50C3",
            "base_price_money": {
              "amount": 125,
              "currency": "USD"
            },
            "total_price_money": {
              "amount": 125,
              "currency": "USD"
            },
            "name": "Bubble",
            "catalog_object_id": "4R4AXLAQ7FUTVZDHMA3N2RLB",
            "catalog_version": 1661096890162,
            "quantity": "1"
          }
        ],
        "gross_sales_money": {
          "amount": 875,
          "currency": "USD"
        },
        "total_tax_money": {
          "amount": 101,
          "currency": "USD"
        },
        "total_discount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "total_money": {
          "amount": 876,
          "currency": "USD"
        },
        "variation_total_price_money": {
          "amount": 750,
          "currency": "USD"
        },
        "applied_taxes": [
          {
            "uid": "B498DFFC-0107-485B-B0D1-CD7E1DF2C242",
            "tax_uid": "62150C36-5023-4C5E-B983-020CA4112807",
            "applied_money": {
              "amount": 31,
              "currency": "USD"
            }
          },
          {
            "uid": "ED8CDB02-6CC5-480E-8BAB-CCBB47A8C988",
            "tax_uid": "C6E8C0CD-EE2A-46A1-80AC-85ABD99A18BD",
            "applied_money": {
              "amount": 70,
              "currency": "USD"
            }
          }
        ],
        "applied_discounts": [
          {
            "uid": "9B93D476-B68F-4D1C-B1C3-D1CD478271F3",
            "discount_uid": "FE8AFC61-9D8B-4CFD-84A7-3A2FB13EB4DE",
            "applied_money": {
              "amount": 100,
              "currency": "USD"
            }
          }
        ],
        "item_type": "ITEM"
      }
    ],
    "taxes": [
      {
        "uid": "C6E8C0CD-EE2A-46A1-80AC-85ABD99A18BD",
        "catalog_object_id": "OEGHEI4L4SV3I3HV2ZHCJFVF",
        "catalog_version": 1660940117887,
        "name": "sales tax",
        "percentage": "9.0",
        "type": "ADDITIVE",
        "applied_money": {
          "amount": 70,
          "currency": "USD"
        },
        "scope": "LINE_ITEM"
      },
      {
        "uid": "62150C36-5023-4C5E-B983-020CA4112807",
        "catalog_object_id": "Z55ZVJ52ISA4JIOZ2GFMX22Q",
        "catalog_version": 1661183031004,
        "name": "Service Charge",
        "percentage": "3.99",
        "type": "ADDITIVE",
        "applied_money": {
          "amount": 31,
          "currency": "USD"
        },
        "scope": "LINE_ITEM"
      }
    ],
    "discounts": [
      {
        "uid": "FE8AFC61-9D8B-4CFD-84A7-3A2FB13EB4DE",
        "catalog_object_id": "YJDFV5VSLH6FADCORCFI52ZK",
        "catalog_version": 1670339793390,
        "name": "$1 off",
        "amount_money": {
          "amount": 100,
          "currency": "USD"
        },
        "applied_money": {
          "amount": 100,
          "currency": "USD"
        },
        "type": "FIXED_AMOUNT",
        "scope": "ORDER"
      }
    ],
    "created_at": "2022-12-14T23:12:51.693Z",
    "updated_at": "2022-12-14T23:12:58.000Z",
    "state": "COMPLETED",
    "version": 5,
    "total_tax_money": {
      "amount": 101,
      "currency": "USD"
    },
    "total_discount_money": {
      "amount": 100,
      "currency": "USD"
    },
    "total_tip_money": {
      "amount": 0,
      "currency": "USD"
    },
    "total_money": {
      "amount": 876,
      "currency": "USD"
    },
    "closed_at": "2022-12-14T23:12:56.411Z",
    "tenders": [
      {
        "id": "xxxx",
        "location_id": "L50C4RKGJWEB5",
        "transaction_id": "xxxx",
        "created_at": "2022-12-14T23:12:52Z",
        "amount_money": {
          "amount": 876,
          "currency": "USD"
        },
        "type": "CARD",
        "card_details": {
          "status": "CAPTURED",
          "card": {
            "card_brand": "xxxx",
            "last_4": "xxxx",
            "fingerprint": "xxxx"
          },
          "entry_method": "CONTACTLESS"
        },
        "payment_id": "xxxx"
      }
    ],
    "total_service_charge_money": {
      "amount": 0,
      "currency": "USD"
    },
    "net_amounts": {
      "total_money": {
        "amount": 876,
        "currency": "USD"
      },
      "tax_money": {
        "amount": 101,
        "currency": "USD"
      },
      "discount_money": {
        "amount": 100,
        "currency": "USD"
      },
      "tip_money": {
        "amount": 0,
        "currency": "USD"
      },
      "service_charge_money": {
        "amount": 0,
        "currency": "USD"
      }
    },
    "source": {},
    "net_amount_due_money": {
      "amount": 0,
      "currency": "USD"
    }
  }
}

Bryan-Square · December 15, 2022, 9:20pm

The source is stable. If it wasn’t set previously and for POS payments and is now showing Square POS it’s not a breaking change.

wsdzy2010 · December 15, 2022, 10:50pm

Then how can we identify whether an order created from Square POS or not, can you provide a way to help us?

Btw, it’s not showing Square POS， now it is
"source": {}
in this specific merchant account while our other merchant square account’s POS orders still return the undefined / null

Bryan-Square · December 16, 2022, 12:47am

Ideally you should be looking to the payment from the Payments API for the information. This way a value is always set :

"application_details": {
                "square_product": "SQUARE_POS"

wsdzy2010 · December 16, 2022, 3:14am

that also makes sense, thx

Alfred · May 26, 2025, 6:57pm

Hi @Bryan-Square ,

We are facing the same problem, the background is that we want to query the orders/payments created from Square POS through Square API, while there are also orders/payments created from Square Restaurant and the application developed by ourselves.

As this post mentioned, we noticed the orders created from Square POS is with empty source name (it’s with source {}, although the Square document says the order may be with source ‘SQUARE_POS’), however order API (POST /v2/orders/search - Square API Reference) doesn’t support querying by empty source name.
As it’s mentioned in your reply, application_details.square_product can be used to check whether a payment is created from Square POS, but payment API (GET /v2/payments - Square API Explorer) doesn’t support querying by square_product as well.

So may i know whether there is any other way that we can query these orders/payments created from Square POS?

An alternative is that we can query all orders through Square order API regardless of the source, then check the orders in our application to see which one is created from Square POS; but the fact is only a small portion of orders are created from Square POS, and we don’t want to query the unnecessary orders to our application as it will make more Square API calls than necessary.

Bryan-Square · May 27, 2025, 4:17pm

At this time there isn’t query for the source of the payment in the Payments API or the Orders API. You’ll need to query the returned results to of the APIs. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team.

Alfred · June 4, 2025, 7:08pm

@Bryan-Square
Sorry to keep asking on this topic, but may i know whether there is any way for us to create payment with application_details. square_product = “SQUARE_POS” in Square sandbox env? We want to create such kind of payments to test the query + filtering function in our application.

Bryan-Square · June 4, 2025, 9:18pm

At this time the ability to take test payments on the Square POS in sandbox isn’t currently available. Only production payments are available at this time.

Topic		Replies	Views
Source not displaying properly in Square Dashboard Questions orders-api	6	693	October 30, 2024
Why the square_product value has been changed without notification Questions payments-api	7	503	June 20, 2023
Square API Order Sources Not Matching UI Feature Requests orders-api	0	726	December 10, 2020
Transaction.product field replacement in new API Questions orders-api , payments-api	6	1288	June 19, 2020
What's the channel field for order in squareup dashboard? Questions orders-api	21	885	August 6, 2024

The source field of an POS order has been changed

Related topics