Cross-org identity & install order

Config Promotion works because the same record carries the same identity in every org. That identity is the SyncKey, and getting it consistent across your orgs comes down to installing in the right order. This page explains both.

The SyncKey

A SyncKey is a unique, durable, per-record identity — a UUID such as 3f2504e0-4f89-41d3-9a0c-0305e82c3301 — stamped on every promotable config record (products, bundles, pricing and product rules and their conditions/actions, attributes and values, dimensions, discount schedules and tiers, block pricing and its conditions).

Two properties make it the cross-org key:

  • It’s stamped automatically. Every config record gets a SyncKey the moment it’s created, with no admin action. Records also get one on every package install and upgrade — so when an upgrade adds new promotable objects, their existing records are keyed too.
  • It’s immutable. Once a record has a SyncKey, Pinion treats it as read-only — an edit that tries to change it is quietly reverted to the stored value. The SyncKey is a system-managed field; reps and admins never set or see it in day-to-day work. This immutability is what lets two orgs trust that a shared key means “the same record.”

Install order — the happy path

The goal is for the same record to carry the same SyncKey in every org, so promotion auto-matches with no manual work. The reliable way to get there:

  1. Install Pinion in PRODUCTION first. The post-install step stamps every existing promotable record with a SyncKey. Production is now the key-of-record source — the org whose keys everything else should inherit.

  2. Then refresh your sandbox(es) FROM that production. A full or partial sandbox refresh copies the org’s data — including the SyncKey values — so each sandbox inherits production’s keys. The same product now has the same SyncKey in production and in the sandbox, and Config Promotion auto-matches the two with no manual mapping.

  3. Promote freely. With keys aligned, the Map & promote workbench shows green (already-matched) records, and Deploy to Sandbox updates in place instead of creating duplicates.

Backfill SyncKeys — the maintenance button

SyncKeys are stamped automatically on create and on every upgrade, so most records are keyed without you doing anything. But some records can slip through: records that predate a feature, an org that was deployed from a source build rather than installed, or an incomplete install can leave a record with a blank SyncKey — and a record with no SyncKey can’t be promoted.

The fix is the Backfill SyncKeys button, on the Maintenance card of the Deploy to Sandbox tab. It runs a background job that assigns a SyncKey to every config record that doesn’t already have one and leaves keyed records untouched — so it’s safe to run anytime and re-running is a no-op.

The Maintenance card on the Deploy to Sandbox tab, with a Backfill SyncKeys button
The Maintenance card — Backfill SyncKeys re-stamps any config records missing a key. Idempotent, so re-running is a safe no-op.

When you click it, Pinion asks you to confirm, then enqueues the job and shows the job id. Run it when you suspect some records aren’t promotable — for example if the workbench shows a record you expect, but it won’t promote, or Troubleshooting points you at unstamped records.

  • Overview — what Config Promotion is and the two ways to promote.
  • Map & promote workbench — where mismatched keys are reconciled by hand.
  • Deploy to Sandbox — the bulk push that also re-seeds a sandbox’s keys after a refresh; home of the Backfill SyncKeys button.
  • Troubleshooting — what to do when a record is unstamped or a reference won’t resolve.