Using Contracts With Order Editing Rules
Contracts let you attach product behaviour to orders that match an Order Editing Rule.
Rules decide which orders are eligible and when editing is available. Contracts decide what should happen to products during the edit.
Use contracts when an edit should automatically add products, remove products, keep bundle items together, apply discounts to added items, or protect selected items during cancellation and refund workflows.
When to use contracts
Contracts are useful for:
- Product bundles.
- Required accessories.
- Free gifts.
- Warranty, deposit, fee, or service items.
- Products stored in metafields.
- Removing child products when a parent product is removed.
- Adding a fixed product when an order edit is saved.
- Preventing selected items from being removed during cancellation or refund requests.
Contracts are separate from rules. You create contracts in the Contracts area, then attach one or more contracts to an Order Editing Rule.
How contracts work with rules
- Order Editing evaluates the order against active Order Editing Rules.
- Matching rules can provide contract IDs.
- Order Editing fetches the matching contracts.
- Disabled contracts are skipped.
- The contracts are evaluated during the customer edit or cancellation flow.
- Matching contract actions tell Order Editing which products to add, remove, discount, or keep on the order.
If multiple matching rules reference contracts, Order Editing can evaluate contracts from all of those matched rules.
Create a contract
- In Order Editing, go to Settings.
- Open Contracts.
- Click Create Contract.
- Add a contract name.
- Choose when the contract should run.
- Choose whether the contract applies to all products or only products matching conditions.
- Add one or more actions.
- Add an optional customer message.
- Save the contract.
Use clear names, such as Add care kit when sofa is added, Remove bundle children when parent removed, or Keep deposit item on cancellation.
Choose when the contract runs
The trigger event controls when Order Editing checks the contract.
Trigger | When it runs | Use it for |
Product added | When a product is added to the order | Adding required accessories, free gifts, products from metafields, or service and warranty items. |
Product removed | When a product is removed from the order | Removing bundle components, removing accessories that should not remain, or keeping selected products during cancellation or refund requests. |
Order edit saved | Once when an order edit is saved | Order-level actions that should not depend on one specific added or removed product. |
Order-saved contracts can use fixed product actions, such as adding or removing a selected product or list of products. They do not have a single trigger product, so metafield-based actions are not available for this trigger.
Choose whether the contract applies to all products
A contract can apply to:
- All products, meaning the trigger event is enough to run the contract.
- Products matching conditions, meaning the trigger product must match your selected conditions.
If you choose product conditions, at least one condition is required.
Contract condition reference
Contract conditions match the product or variant involved in the edit.
Setting | Options | Notes |
Product fields | Product title, product type, product vendor, product tag, or collection | Use product tags, SKUs, or collections where possible because titles can change. |
Variant fields | Variant title or variant SKU | Use SKU when it is the most reliable product identifier. |
Operators | Equals, does not equal, contains, does not contain, starts with, or ends with | Choose the most specific operator that fits the product group. |
Multiple conditions | AND or OR | Use AND when every condition must match. Use OR when at least one condition must match. |
Use SKU or product tags when possible. Titles are easy to understand, but they are more likely to change.
Add actions
Actions define what the contract does after the trigger and conditions match.
A contract must have at least one action.
Action reference
Action | What it does | Use it for | Common settings or notes |
Add a product | Adds a specific product variant to the order | Care kits, gift items, warranty items, required accessories, service fees, or deposit products. | Variant to add, quantity, maximum quantity, stock check, and optional line item discount. |
Remove a product | Removes a specific product variant from the order | Removing a selected product that should not remain after the trigger event. | Select the product or variant to remove. |
Add products referenced in a metafield | Adds products or variants listed in a metafield on the trigger product or trigger variant | Dynamic bundles where each parent product defines its own included products. | Metafield owner, namespace, key, maximum quantity, no duplicates, stock check, and optional line item discount. |
Remove products referenced in a metafield | Removes products or variants listed in a metafield on the trigger product or trigger variant | Removing related bundle components when the trigger product is removed. | The metafield must be readable and must reference supported products or variants. |
Add a list of products | Adds a fixed list of selected products or variants | Simple bundles where every matching edit should add the same set of items. | This is often simpler than metafields when the related products do not vary by trigger product. |
Remove a list of products | Removes a fixed list of selected products or variants | Workflows where every matching edit should remove the same set of items. | Select the products or variants to remove. |
Keep certain items on the order | Keeps selected products or variants on the order during cancellation or refund workflows | Deposits, fees, delivered services, or non-refundable bundle components. | Mainly used with product removal or cancellation-related flows. |
Metafield add actions support product list references, variant list references, and product variant list references. The metafield must be available with storefront read access so Order Editing can read it during the customer edit.
If a product-list metafield is used, Order Editing resolves the product to an available variant when applying the action.
Action availability by trigger
Not every action is available for every trigger.
Trigger | Available action types | Notes |
Product added | Add actions and most bundle-style actions | There is a trigger product to inspect, so metafield-based add actions can be used. |
Product removed | Removal actions and cancellation protection actions | Use this when the customer removes a product or requests a cancellation or refund. |
Order edit saved | Direct product actions and fixed-list product actions | Metafield actions are not available because there is no single trigger product to read metafields from. |
If an action is not shown in the contract builder, it is not available for the selected trigger.
Discounts on added products
Some add actions can apply a line item discount to the product that the contract adds.
Setting | What to enter |
Discount title | A customer-friendly label, such as Bundle discount, Included accessory, or Free gift. |
Discount value | The discount amount or percentage. |
Discount type | The available discount type for the store setup. |
Use discount titles that make sense to customers and staff, such as Bundle discount, Included accessory, or Free gift.
Customer message
Contracts can include a short customer message.
Use the message to explain why Order Editing changed the products in the order.
Example:
We added the required care kit for this product.
Keep the message short. The contract message is intended to be a brief explanation, not a full policy.
Attach a contract to a rule
- Go to Settings > Order Editing Rules.
- Create a rule or open an existing rule.
- Open the Contracts section.
- Select one or more contracts.
- Save or publish the rule.
The contract is only considered when the Order Editing Rule matches the order.
You can also create a new contract directly from the rule setup flow. If the rule has unsaved changes, save the rule before navigating away to manage all contracts.
Evaluation behaviour
Contracts are evaluated in two main situations.
Current order state evaluation
Order Editing can evaluate the current order state to work out which contract actions should apply.
In this evaluation:
- Current line items can be treated like product-added triggers.
- Order-saved contracts can be evaluated once.
- Product-removed contracts are not inferred from the current state because Order Editing needs an actual removal event.
- Contract actions are applied in a single pass so one action does not repeatedly trigger another contract.
- If multiple matching actions add the same item, Order Editing uses the highest required quantity rather than adding the quantities together.
Saved edit or order delta evaluation
When a customer saves an edit, Order Editing can evaluate what changed.
In this evaluation:
- Added products can trigger product-added contracts.
- Removed products can trigger product-removed contracts.
- Quantity updates are not treated the same as add or remove events.
- Disabled contracts are skipped.
- Only contracts referenced by matching Order Editing Rules are considered.
This is why product-removed contracts should be tested with an actual removal, not just by viewing the current order state.
Metafield requirements
Metafield-based contracts need the metafield to be readable by Order Editing.
Before using a metafield action, check that:
Requirement | What to check |
Metafield exists | The metafield exists on the product or variant used by the contract. |
Supported type | The metafield uses a supported product or variant reference type. |
Namespace and key | The contract uses the exact namespace and key from Shopify. |
Storefront read access | The metafield is readable by Order Editing during the customer edit. |
Referenced products | The referenced products or variants are active and available where expected. |
Metafield actions are powerful for bundles because product teams can manage included products directly on the product or variant instead of creating a separate contract for every bundle.
Example: add bundle components from a metafield
You sell a parent product that includes several components. Each parent product has a metafield listing the included variants.
Create a contract:
- Trigger: Product added.
- Conditions: match the parent products, or apply to all products if only eligible products use the metafield.
- Action: Add products referenced in a metafield.
- Metafield owner: product or variant, depending on where the included products are stored.
- Optional settings: no duplicates, maximum quantity, only add if in stock.
Attach the contract to the rule that matches eligible orders.
Example: remove bundle components when the parent is removed
You sell a parent product with required child products. If the customer removes the parent product, the child products should also be removed.
Create a contract:
- Trigger: Product removed.
- Conditions: match the parent product by SKU, tag, type, or title.
- Action: Remove products referenced in a metafield or Remove a list of products.
Attach the contract to the rule that controls editing for those orders.
Example: add a fixed item when an edit is saved
You need to add a fixed service item whenever a matching order is edited.
Create a contract:
- Trigger: Order edit saved.
- Applies to: all products.
- Action: Add a product or Add a list of products.
Attach the contract to the rule that matches the order types that need the service item.
Example: protect deposit items during cancellation
You allow customers to cancel or partially cancel some items, but deposit products should stay on the order.
Create a contract:
- Trigger: Product removed.
- Conditions: match the products or variants involved in the cancellation workflow.
- Action: Keep certain items on the order.
Attach the contract to the rule that applies to those orders.
Testing contracts
Always test contracts before relying on them for live customers.
- Create or update the contract.
- Attach it to a matching active Order Editing Rule.
- Place a test order that matches the rule.
- Make the exact edit that should trigger the contract.
- Confirm the expected products are added, removed, discounted, or protected.
- Test a similar edit that should not trigger the contract.
- Test an order that does not match the attached rule.
- If the contract uses metafields, test with products that have and do not have the metafield.
- If the contract uses stock checks, test with in-stock and out-of-stock items.
Troubleshooting
The contract is not running
Check that the contract is enabled, attached to a matching active rule, and triggered by the edit the customer actually made.
The rule matches, but the contract still does nothing
Check the contract trigger. A product-added contract needs an added product. A product-removed contract needs a removed product. An order-saved contract runs when the edit is saved.
Metafield products are not being added or removed
Check the metafield namespace, key, owner, type, storefront read access, and referenced products or variants.
The wrong products are being matched
Review the contract conditions and the AND/OR setting. Use SKU, product tag, product type, or collection where possible instead of title matching.
A removed-product contract does not appear in preview
Product-removed contracts need an actual removal event. They may not be inferred from the current order state.
An added item appears once instead of multiple times
For current state evaluation, Order Editing uses the highest required quantity for duplicate add actions instead of adding duplicate quantities together.
The action is unavailable
Check the selected trigger. Some actions are only available when there is a trigger product, and metafield actions are not available for order-saved contracts.
A disabled contract is selected
Disabled contracts are skipped during evaluation. Enable the contract before testing it.
Best practices
- Keep contract names specific.
- Use product tags, SKUs, or collections for stable matching.
- Use metafields for bundles that vary by parent product.
- Use fixed product lists for simple, repeatable bundles.
- Use stock checks when adding physical products that might sell out.
- Add short customer messages for automatic product changes.
- Test each trigger with the exact customer edit that should activate it.
- Attach contracts only to rules that should be allowed to run them.
