Skip to main content
How-to

Item ID Renaming Consequences

The Item ID field on an item's Item Editor Item tab is editable after the item is created, but the change is local to that one field. Auto orders, kit components, and upsell paths each keep their own independent copy of the Item ID, and none of them update when you rename it in the Item Editor. StoreFront page assignments are the exception — they're linked to the item's internal identifier and generally tolerate a rename. This guide covers what breaks in each subsystem, and the recommended approach when an Item ID genuinely needs to change.

Table of Contents​

Overview​

Renaming an item's Item ID does not cascade anywhere else in your UltraCart account. Auto orders, kit items, and upsell paths each store their own reference to the original Item ID, so a rename in the Item Editor silently orphans those references instead of updating them. StoreFront page assignments are the exception, since they're linked by internal identifier rather than by Item ID — see StoreFront Page Assignments for the one case where a rename can still break them.

SubsystemWhat breaksDetails
Auto orders / subscriptionsRebilling stops matching the itemJump to section
Kit itemsThe kit's component list still references the old IDJump to section
Upsell paths / offersTrigger, Suppression, and Upsell Item lists still reference the old IDJump to section
StoreFront page assignmentsTolerates the rename (linked by internal item identifier); item set attributes are the exceptionJump to section
warning

Do not rename the Item ID of an item that has active auto orders, is used as a kit component, or is referenced in an upsell path or offer. Create a new item instead — see Recommended Approach.

Auto Orders and Subscriptions​

Renaming the Item ID of an item with active auto orders is not recommended: the auto order record stays linked to the original ID, so rebilling for customers already on that schedule fails. See Can I edit the item ID of an auto order item? in the Auto Order FAQ.

If the goal is a price change only, use Grandfathered Pricing on the item's Auto Order tab instead of renaming the item.

If a new Item ID is genuinely required, create a new item with the desired ID and schedule, let the existing auto orders on the old ID complete their remaining rebills, and begin selling the new item going forward. See Subscription Items for the broader auto order and subscription model.

Kit Items​

Kit components are referenced by Item ID in the kit's component configuration. Renaming a component item's ID does not update any kit that includes it — every kit referencing that component must have its component list manually updated to the new ID. There is no bulk or automatic update across kits. See Item Management: Kit Items for how components are added and referenced.

Upsells and Visual Builder Paths​

Upsell Path and Offer configuration in the StoreFront Upsells editor stores Item IDs directly in several fields, and none of them update automatically when the underlying item is renamed: Trigger Items, Suppression Items, Upsell Item Id's, and Accessory Item Ids - Add/Remove.

The Migrate Accessory Item Ids - From/To fields are the one place in the Visual Builder built specifically to handle an Item ID change for accessory items. Trigger Items, Suppression Items, and Upsell Item Id's have no equivalent migrate field and must be edited by hand in every path or offer that references the old ID.

StoreFront Page Assignments​

Unlike the other subsystems on this page, item-to-page assignment is linked by the item's internal identifier (OID), not its Item ID, whether the assignment was made from the Item Editor's storefront assignment fields or from the Storefronts pages editor. A rename doesn't break the link — the page stays assigned to the same item.

The exception is any StoreFront feature that references items through an item set attribute, such as a widget configured with a list of Item IDs. Item sets are stored as a CSV of Item IDs directly on the page rather than by OID, so renaming an Item ID that appears in an item set breaks that reference and the item set must be updated by hand.

If the assignment has a Custom URL configured, the public-facing URL is decoupled from the Item ID as well. Without a Custom URL, the page's default URL is based on the Item ID, so the URL itself can change even though the assignment doesn't break.

  1. Don't rename an Item ID in place if the item has active auto orders, is used as a kit component, or is referenced in any upsell path or offer.
  2. Create a new item with the desired Item ID.
  3. Manually update kit component lists, upsell Trigger Items / Suppression Items / Accessory Item Ids, and any StoreFront item set attributes to point at the new item. Regular StoreFront page assignments don't need this step since they follow the item by internal identifier — reassign a page only if you want it to sell the new item instead of the old one.
  4. For subscription items, let existing auto orders on the old ID complete naturally rather than migrating them; use Grandfathered Pricing if only the price needs to change.
  5. Once the old Item ID's remaining auto orders and references are cleared, retire it by checking Inactive, and optionally Exclude From Search, on the item.

Troubleshooting​

Rebilling fails after an Item ID rename​

Symptoms: Auto order rebills start failing, or stop appearing on the Future Orders tab, shortly after an item's Item ID was changed.

Root Cause: The auto order record still points at the original Item ID; the rename broke the link between the item and its auto order schedule.

Diagnosis:

  1. Open the auto order record and compare its item reference against the current Item Editor entry for that product.

Solution: Revert the Item ID if possible, or create a new item and have affected customers migrate to it. Use Grandfathered Pricing for future price-only changes instead of renaming.

Upsell offer stops triggering the expected accessory or trigger item​

Symptoms: An upsell path or offer that used to trigger, suppress, or offer a given item stops behaving as configured after that item's ID was changed elsewhere.

Root Cause: The path/offer's Trigger Items, Suppression Items, or Accessory Item Ids list still references the old Item ID.

Diagnosis:

  1. Open the upsell path or offer editor and compare the configured Item ID list against the current Item Editor entry.

Solution: Manually update the Item ID list, or use the Migrate Accessory Item Ids (From/To) fields for accessory item references specifically.

An item disappears from a StoreFront item set after a rename​

Symptoms: A StoreFront widget or page that lists items through an item set stops showing an item shortly after that item's Item ID was changed elsewhere. Regular page assignments for the item are unaffected.

Root Cause: Item sets are stored as a CSV of Item IDs directly on the page, not by the item's internal identifier, so they don't follow a rename the way page assignments do.

Diagnosis:

  1. Open the StoreFront page or widget configuration and compare the item set's CSV against the current Item Editor entry for that product.

Solution: Manually update the Item ID in the item set's CSV to match the new Item ID.

Was this page helpful?