# Clarification needed - Fulfillment.uid ( OrderFulfillment ) null during historical order backfill **URL:** \ **Category:** Questions\ **Tags:** orders-api\ **Created:** [September 22, 2026, 12:54pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922 "2026-09-22T12:54:03Z")\ **Posts on this page:** 6\ **Page:** 1
**Author:** ![developers111](https://avatars.discourse-cdn.com/v4/letter/d/e36b37/32.png) [@developers111](https://developer.squareup.com/forums/u/developers111)\ **Post date:** [September 22, 2026, 12:54pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/1 "2026-09-22T12:54:03Z")
Application: Fivetran Square connector Square-Version: `2026-01-22` 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: 1. Can `OrderFulfillment.uid` legitimately be absent or null in a response from `SearchOrders` or `RetrieveOrder`? 2. 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? 3. Is there a `Square-Version` or order creation date after which `uid` is guaranteed to be present for every fulfillment? 4. When a fulfillment is created without a client-supplied `uid`, does Square always generate one? Can a persisted fulfillment remain without a `uid`? 5. Is a fulfillment’s `uid` stable across repeated reads and updates of the same order? 6. 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. ---
**Author:** ![jaeha](https://avatars.discourse-cdn.com/v4/letter/j/ebca7d/32.png) [@jaeha](https://developer.squareup.com/forums/u/jaeha)\ **Post date:** [September 22, 2026, 4:33pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/5 "2026-09-22T16:33:30Z")
Thanks for the detailed report. Could you please share the affected order ID or application ID with us, so that we can investigate this further? ---
**Author:** ![developers111](https://avatars.discourse-cdn.com/v4/letter/d/e36b37/32.png) [@developers111](https://developer.squareup.com/forums/u/developers111)\ **Post date:** [September 24, 2026, 6:56pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/6 "2026-09-24T18:56:15Z")
Thanks, Jaeha. 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. ---
**Author:** ![jaeha](https://avatars.discourse-cdn.com/v4/letter/j/ebca7d/32.png) [@jaeha](https://developer.squareup.com/forums/u/jaeha)\ **Post date:** [September 25, 2026, 5:56pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/7 "2026-09-25T17:56:37Z")
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. ---
**Author:** ![developers111](https://avatars.discourse-cdn.com/v4/letter/d/e36b37/32.png) [@developers111](https://developer.squareup.com/forums/u/developers111)\ **Post date:** [October 7, 2026, 6:36pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/9 "2026-10-07T18:36:30Z")
Hi Jaeha, 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. ---
**Author:** ![jaeha](https://avatars.discourse-cdn.com/v4/letter/j/ebca7d/32.png) [@jaeha](https://developer.squareup.com/forums/u/jaeha)\ **Post date:** [October 7, 2026, 11:13pm UTC](https://developer.squareup.com/forums/t/clarification-needed-fulfillment-uid-orderfulfillment-null-during-historical-order-backfill/27922/10 "2026-10-07T23:13:54Z")
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.