How to set up Custom Offer relation types and Auto Convert To

Introduction

Besides the built-in Upgrade and Downgrade paths, Vendors can create their own relation types between Offers. A custom relation type adds a new section to the Related Services area on the Offer edit page, where you link a source Offer to one or more destination Offers.

The most common use case is automatic promotion conversion. When a promotional Offer expires, the Platform needs to know which regular Offer the Subscription should convert to. By creating an Auto Convert To relation type and assigning a destination Offer, you define that conversion target explicitly — so the Platform can switch the Subscription automatically when the promotion ends.

Custom relation types are managed in Product Management and are available to Vendor Admins, Product Managers, and Super Admins.

When to use custom offer relation types

The built-in Upgrade and Downgrade relations cover most scenarios, but they are many-to-many by design — a single Offer can have multiple upgrade and downgrade targets. Some business scenarios require a different kind of link between Offers. Custom relation types solve this.

Typical scenarios:

• Automatic promotion conversion — A promotional Offer (for example, "M365 Business Basic — 6 Months Free") can be upgraded or downgraded to many Offers while the promotion is active. But when the promotion expires, the Subscription must convert to exactly one regular Offer. An Auto Convert To relation type with single-target cardinality defines that one-to-one mapping.
• Cross-sell recommendations — You can create a multi-target relation type (for example, "Cross-sell") to link an Offer to related Offers that Vendor automation services can consume.

Enable the feature for a vendor

Custom relation types are disabled by default. You must enable them on the Vendor Edit page before you can create any relation types.

1. Open the Vendor Edit page for the target Vendor.|

   

2. Scroll down to the Custom Offer Relation Types section.
3. Set the Enable Custom Relation Types toggle to ON.
4. Save the page.

The section expands and shows the Relation Types table (initially empty) and the Add Relation Type button.

Create a relation type

1. In the Custom Offer Relation Types section, select Add Relation Type.
2. Enter a Title — for example, "Auto Convert To". This name becomes the section heading in Related Services on every Offer edit page of this Vendor.
3. Enter a Key — for example, "autoConvertTo". The Key is a machine-readable identifier. It must start with a lowercase letter, contain only letters and digits (no spaces), and be unique for this Vendor. You cannot change it after creation.
4. If the relation should point to exactly one destination Offer (required for automatic promotion conversion), enable Allow only one destination offer.
5. Select Add Relation Type to confirm.

The new type appears in the Relation Types table with columns: Title, Key, Destination Offers (Only one / Multiple), Status (Active / Deactivated), and actions (Edit / Deactivate).

Validation rules:

• Title — required, unique per Vendor, up to 250 characters.
• Key — required, unique per Vendor, up to 100 characters, pattern: lowercase letter followed by letters or digits.
• Different Vendors can use the same Title and Key.

Assign destination offers

Once a relation type is Active, a new section named after its Title appears in Related Services on the Offer edit page (Offer Details → Business Rules → Related Services), right below the Upgrades and Downgrades sections. One section is rendered per Active custom relation type of the Offer's Vendor.

1. Open the Offer in edit mode and navigate to Offer Details → Business Rules → Related Services.
2. Find the section for your custom relation type (for example, "Auto Convert To").
3. Select the add action (for example, + Add Auto Convert To Option).
4. Choose the destination Offer from the dropdown.
5. Save the Offer.

For single-target types, adding a second destination is blocked. For multi-target types, you can add as many destinations as needed. You can change or remove a destination at any time, regardless of the Offer's status (Draft, Published, or Unpublished).
 

Set up automatic promotion conversion (Auto Convert To)

When a promotional Offer expires, the Subscription must switch to a regular Offer at standard pricing. Without a defined conversion target, the Platform cannot determine which Offer to convert to — even if the Offer has Upgrade paths configured — because upgrades are many-to-many and do not indicate a single conversion target.

The Auto Convert To relation type solves this. Here is how to set it up end to end:

1. Enable Custom Offer Relation Types for the Vendor (see the section above).
2. Create a relation type with Title "Auto Convert To", Key "autoConvertTo", and Allow only one destination offer enabled.
3. For each promotional Offer, open the Related Services section and assign the regular (non-promotion) Offer as the destination in the Auto Convert To section.
4. Designate the relation type as the conversion relation for the Vendor. This is a one-time Vendor-level setting configured through the API by your platform administrator.

Once configured, when the promotion period ends and Vendor automation triggers the conversion, the Platform reads the Auto Convert To destination from the promotional Offer and converts the Subscription to the regular Offer automatically. Billing, proration, term dates, and seat carryover follow the existing conversion behavior — this feature only changes how the target Offer is resolved.

What happens if the conversion target is missing?

If no destination Offer is configured for the promotional Offer, or if the Vendor has not designated a conversion relation, the conversion Order fails with a descriptive error. The Vendor's automation services are responsible for resolving such issues — the Platform does not send proactive alerts about missing or misconfigured conversion targets.

Manage relation types

You manage relation types from the Relation Types table on the Vendor Edit page. Each row shows the type's Status (Active or Deactivated) and the available actions.

Edit a relation type

• You can rename the Title at any time. The new name is immediately reflected as the section heading on the Offer edit page.
• The Key is read-only after creation.
• You can switch cardinality from multiple to single only if no Offer currently has more than one destination for this type. Switching from single to multiple is always allowed.

Deactivate a relation type

• Select Deactivate in the table row. This hides the type's section from the Offer edit page and removes its data from the Offer payload. All destination assignments are preserved internally.
• You can deactivate a type even if Offers reference it.

Reactivate a relation type

• Select Reactivate on a deactivated row. The section reappears on the Offer edit page and the data is included in the Offer payload again, with all previously assigned destinations intact.

Delete a relation type

• A relation type can only be deleted if no Offer references it. Otherwise, use Deactivate instead.

Important information

• The conversion relation designation (which relation type is used for automatic promotion conversion) must be configured through the API. There is no UI for this setting.
• The Platform does not alert you if a destination Offer is unpublished or archived after being assigned. A conversion Order targeting an unavailable destination fails with an error.
• Custom relations are never shown to Customers. They do not appear on the Subscription page or in the Seller storefront.
• The feature toggle cannot be disabled while any relation type is Active. Deactivate all types first.
• There is no search or discovery feature for relation types. Keep track of the Keys and Titles you create.

Summary

Custom Offer Relation Types let Vendors define their own links between Offers, beyond the built-in Upgrade and Downgrade paths. The feature is enabled per Vendor and each custom type adds a new section to the Related Services area on the Offer edit page. The primary use case is the Auto Convert To relation, which gives the Platform a clear, single conversion target for when a promotional Offer expires. Product Managers assign the destination Offer through the familiar Offer edit page, and the Platform handles the Subscription conversion automatically.