We are rolling out a change that uses Square’s OrderFulfillment.uid as part of the primary key for stored fulfillment records. As part of the migration, affected connections reset their order cursor and re-fetch historical orders using SearchOrders and RetrieveOrder.
During one historical backfill, we encountered an OrderFulfillment object whose uid was null after deserializing Square’s response. Because our updated implementation expects uid to be present, the sync failed with:
Null primary key found while syncing table square.order_fulfillment. Primary Key uid is null in object.
We have not yet confirmed whether the raw API response explicitly contained "uid": null or omitted the uid property, because both produce the same value after deserialization.
The affected fulfillment had the following values:
type: PICKUP
state: COMPLETED
pickup_details: null
We have paused the rollout while we investigate and are adding defensive handling for fulfillments without a uid.
Could you please clarify:
Can OrderFulfillment.uid legitimately be absent or null in a response from SearchOrders or RetrieveOrder?
If so, under what circumstances can this occur—for example, for older orders, orders created through Square products instead of the API, particular API versions, or certain fulfillment types or states?
Is there a Square-Version or order creation date after which uid is guaranteed to be present for every fulfillment?
When a fulfillment is created without a client-supplied uid, does Square always generate one? Can a persisted fulfillment remain without a uid?
Is a fulfillment’s uid stable across repeated reads and updates of the same order?
If uid can be absent, what does Square recommend as a stable identifier for distinguishing multiple fulfillments within the same order?
We can provide the affected merchant location and order details privately to Square staff if needed.
Impact: This is blocking an in-progress rollout related to storing fulfillment records during incremental syncs and historical backfills.
We don’t currently have access to the affected merchant’s connection. We have requested access and are waiting for the customer to grant it, so we cannot retrieve the specific order ID or replay the failing call yet. We’ll share the order ID privately as soon as access is available.
We can also provide our Square application ID privately if that would help. Please let us know the preferred way to share it with you.
In the meantime, our logs confirm:
Square-Version: 2026-01-22
The failure occurred during a historical backfill through SearchOrders/RetrieveOrder
The deserialized fulfillment had type=PICKUP, state=COMPLETED, pickup_details=null, and no uid
The same failure occurred again when the backfill was retried
While we work on obtaining the order ID, could you please answer any of our original questions that can be addressed based on the expected API contract or general Orders API behavior—particularly whether OrderFulfillment.uid is guaranteed to be present and stable for every persisted fulfillment, whether Square always generates it when the client does not provide one, and what identifier Square recommends if uid can be absent?
These answers would help us decide whether uid can safely be used as a primary key or whether a fallback identifier is required.
We’ll follow up with the affected order ID and any additional merchant details privately once access is granted.
Square automatically assigns a uid, and it should ordinarily be present on a persisted fulfillment returned by the Orders API. The uid is the recommended identifier for distinguishing fulfillments within the same order. When present, it is intended to remain stable across repeated reads and updates of that fulfillment.
Although the API schema doesn’t technically mark uid as required, we aren’t aware of a normal condition that would explain it being absent here. We therefore want to investigate this specific order before determining whether this is a legacy data condition, an unexpected response, or another issue.
Adding defensive handling so that one anomalous record doesn’t block the entire backfill is reasonable. However, we would still like to understand why this fulfillment had no uid.
When you regain access, please share the order ID and application ID which are safe to share in this thread because they aren’t credentials. Please don’t share an access token or any other authentication credentials.
Once we have the order ID, we can investigate the stored order and response path and provide a more definitive explanation.
Unfortunately, we were unable to get source access from the merchant, so we have no way to retrieve the order ID for the fulfillment that triggered this failure. However, we don’t want this to block us indefinitely.
To move forward with our migration, we need your guidance on which combination of fields can be used as the primary key for a fulfillment when uid is null. As a starting point, we are considering type together with pickup_details.placed_at or shipment_details.placed_at, since these values are set at creation rather than changing later in the fulfillment lifecycle. If those detail objects are also absent, we are considering the fulfillment’s position in the fulfillments array as an additional fallback.
Would Square recommend either of these approaches, or is there a better-supported stable identifier that we should use instead?
Also, please let us know whether we should continue following up in this thread or open a new one, as this thread currently appears resolved on our end.
We don’t recommend type + placed_at or array position as stable primary keys. Neither has a documented uniqueness or stability guarantee.
fulfillment.uid serves that exact purpose and is the intended identifier within an order and should be populated. A missing UID is unexpected behavior that we need to investigate. So if you encounter this again in the future, please do let us know so that we can take a further look.