APIs as a Product, Part 7 of 10 · Keeping catalogs in sync across partners.
Picture a merchant whose outlets all sell the same chicken rice. Same name, same photo, same description. A partner asks a simple question: can we treat it as one product?
It sounds obvious. It isn't. Two of the outlets charge more because they sit in a mall. One has stopped serving it on weekends. Another sells it only as part of a set lunch. On a menu, it is one dish. In the data, it is four different things that happen to share a name.
This is the problem at the centre of every catalog sync. Each partner has its own idea of what a product is, its own IDs, and its own rules for prices, options and availability. Your job is to keep them all pointing at the right thing, and to know when two things that look the same are not.
Whose ID wins
The first decision is who owns identity. We kept our own ID as the source of truth and stored each partner's ID as a mapping to it. A partner could rename, re-order or restructure their menu, and we would still know which of our items they meant.
Two rules made this hold up. An ID, once used, was never reused for something else. And items that were removed kept their IDs, so that an order from last month, a refund or a dispute could still resolve to what the customer actually bought. Deleting an ID is easy. Explaining a refund for an item that no longer exists is not.
When not to match
The tempting move is to match items automatically by name. It saves time, and it is right most of the time. The cost is in the cases where it is wrong.
A wrong match isn't a data problem. It's a money problem. If two items are merged and they carry different prices, the partner charges one amount and the merchant expects another. That gap turns up later as a reconciliation break, a confused merchant, or a customer who was charged for something they didn't get.
So we treated matching as a business decision, not a data clean-up. Items were the same product only when they shared price, options and availability, or when the merchant said so. Anything else stayed separate, with outlet-level differences held as overrides on a shared base item rather than as copies.
Options make it harder still. "Add egg", "large" and "less spicy" are small on a menu, but they change price, stock and what the kitchen makes. A partner that flattens them into free text can send orders nobody can price.
The cheapest mistake in catalog sync is the match you didn't make. The most expensive is the one you made wrong.
Related reading: Reorder Used to Depend on What the Store Called an Item and Platform at Scale, Part 2: The Menu Is the Storefront.