Frequently asked questions

This detailed FAQ covers common questions about Adobe’s mid-term upgrade feature, also referred to as Switch Orders. Use this resource to learn the upgrade process, resolve issues, and efficiently implement switch order workflows.

Table of contents

General concepts

What is a mid-term upgrade?

Answer: A mid-term upgrade allows partners to upgrade a customer's product subscription to a higher-tier product at any time during the current term, without waiting for renewal. This is handled through the Orders API with the order type set to “SWITCH.”

What is the difference between a switch and a regular order?

Answer:

Regular order
Switch order
Timing
Can be placed anytime
Mid-term upgrade during active subscription.
Existing subscription
Creates new subscription
Modifies existing subscription.
Pricing
Full term pricing
Prorated pricing for remaining term.
Original product
Not affected
Quantity reduced or subscription cancelled.
Flexible promotion
Allowed
Not allowed.
Use case
New purchase or add-on
Upgrade to higher-tier product.

What is the difference between a full switch and a partial switch?

Answer:

Can I switch between any two products?

Answer: No. Switch paths are predefined and directional. You can only switch between products that have an established upgrade path.

Which products are not eligible for mid-term upgrades?

Answer: Stock Credit Packs (SCP) and Adobe Sign are not eligible for mid-term upgrades.

Switch paths and eligibility

How do I discover available upgrade paths for my customer?

Answer: Use one of two API methods:

How do I discover available upgrade paths for an offer?

Answer: Use the GET Offer Switch Paths API to discover upgrade paths at the product level using the base offer ID.

{
    "totalCount": 3,
    "count": 3,
    "offset": 0,
    "limit": 20,
    "productUpgrades": [
            {
                "sourceBaseOfferId": "65304479CA01A12",
                "targetList": [
                        {
                                "targetBaseOfferId": "65324898CA01A12",
                                "sequence": 1,
                                "switchType": "PARTIAL_ALLOWED"
                        },
                        {
                                "targetBaseOfferId": "30005296CA01A12",
                                "sequence": 2,
                                "switchType": "PARTIAL_ALLOWED"
                        },
                        {
                               "targetBaseOfferId": "65324888CA01A12",
                               "sequence": 3,
                               "switchType": "FULL_ONLY"
                        }
                    ]
            }
        ]
}

Response fields explained:

Field
Description
totalCount
Total number of upgrade paths available.
count
Number of upgrade paths returned in this response.
offset
Pagination offset (start index).
limit
Maximum number of items per response.
productUpgrades
Array of upgrade paths for the source offer.
sourceBaseOfferId
The base offer ID you are upgrading from.
targetList
List of possible upgrade targets.
targetBaseOfferId
The base offer ID you can upgrade to.
sequence
Order in which upgrade paths are listed.
switchType
Indicates if partial upgrades are allowed (PARTIAL_ALLOWED) or only full upgrades (FULL_ONLY).

Example interpretation:

Why does the API show a switch path exists, but my switch order fails?

Answer: Several factors beyond the general switch path may affect eligibility:

Troubleshooting steps:

  1. Verify subscription status using GET /customers/{customerId}/subscriptions/{subscriptionId}.
  2. Check whether the customer's market segment matches the switch path.
  3. Confirm discount levels match (for 3YC customers).
  4. Verify the switch path using subscription-specific API to ensure it's valid for this customer.

Why am I getting "Switch path validity check failed" (Error 2150)?

Answer: This error indicates the requested switch path is not valid. Common causes:

Resolution:

Order types and workflow

What are the different order types for mid-term upgrades?

Answer: There are four order types:

Type
Description
Preview
Execute
Shows pricing/refund
PREVIEW_SWITCH
Preview upgrade before execution
Yes
No
Shows prorated pricing
SWITCH
Execute the upgrade
Yes
Yes
Charges prorated amount
PREVIEW_REVERT_SWITCH
Preview reverting an upgrade
Yes
No
Shows refund/credit
REVERT_SWITCH
Reverse a previous upgrade
Yes
Yes
Processes refund/credit

Recommended workflow:

  1. PREVIEW_SWITCH → Review pricing → Get customer approval.
  2. SWITCH → Execute upgrade.
  3. (If needed) PREVIEW_REVERT_SWITCH → Review impact.
  4. (If needed) REVERT_SWITCH → Reverse upgrade.

Is PREVIEW_SWITCH required before executing a SWITCH?

Answer: No, PREVIEW_SWITCH is optional but highly recommended.

Benefits of using PREVIEW_SWITCH:

Best practice: Always use PREVIEW_SWITCH for customer-facing scenarios to avoid billing disputes.

What is the complete workflow for a mid-term upgrade?

Answer: Follow these steps:

POST /v3/customers/{customerId}/orders?fetch-price=true
{
    "orderType": "PREVIEW_SWITCH",
    "currencyCode": "USD",
    "lineItems": [{
        "offerId": "{target-offer-id}",
        "quantity": 10,
        "extLineItemNumber": 1
    }],
    "cancellingItems": [{
        "subscriptionId": "{subscription-id}",
        "quantity": 10,
        "extLineItemNumber": 1,
        "referenceLineItemNumber": 1
    }],
    "externalReferenceId": "preview-12345"
}

 POST /v3/customers/{customerId}/orders
{
    "orderType": "SWITCH",
    "currencyCode": "USD",
    "lineItems": [{
        "offerId": "{target-offer-id}",
        "quantity": 10,
        "extLineItemNumber": 1
    }],
    "cancellingItems": [{
        "subscriptionId": "{subscription-id}",
        "quantity": 10,
        "extLineItemNumber": 1,
        "referenceLineItemNumber": 1
    }],
    "externalReferenceId": "switch-12345"
}

How long does a switch order take to process?

Answer:

Type
Typical time
Max time
Response
Processing
PREVIEW_SWITCH
Instant
1-2s
200
Synchronous
SWITCH
2-8 minutes
10 min
202
Poll for 1000
REVERT_SWITCH
2-8 minutes
10 min
202
Poll for 1000

Status codes:

Best practice: Poll every 30 seconds for up to 10 minutes. If status remains 1002 after 10 minutes, escalate to support.

Can I place multiple switch orders for the same subscription simultaneously?

Answer: No. Only one switch order can be processed for a subscription at a time.

Behavior:

Example scenario:

Subscription A (100 licenses):

Quantities and pricing

What quantity constraints apply to switch orders?

Answer:

Key rules:

Examples:

Valid: Switching 10 licenses:

"lineItems": [{"quantity": 10}],
"cancellingItems": [{"quantity": 10}]

Invalid: Quantities don't match:

"lineItems": [{"quantity": 10}],
"cancellingItems": [{"quantity": 5}]  // Error 2149

Invalid: Exceeds subscription.

// Current subscription has 8 licenses.

"lineItems": [{"quantity": 10}],
"cancellingItems": [{"quantity": 10}]  // Error 2151

How is pricing calculated for mid-term upgrades?

Answer: Pricing is prorated based on the remaining term of the original subscription.

How do I get detailed pricing information before executing a switch?

Answer: Use the fetch-price=true query parameter with PREVIEW_SWITCH:

POST /v3/customers/{customerId}/orders?fetch-price=true
{
    "orderType": "PREVIEW_SWITCH",
    ...
}

Response includes:

{
    "lineItems": [{
        "pricing": {
            "partnerPrice": 300.00,
            "discountedPartnerPrice": 270.00,
            "netPartnerPrice": 270.00,
            "lineItemPartnerPrice": 73.97
        },
        "proratedDays": 100
    }],
    "cancellingItems": [{
        "pricing": {
            "partnerPrice": 180.00,
            "discountedPartnerPrice": 162.00,
            "netPartnerPrice": 162.00,
            "lineItemPartnerPrice": 44.38
        }
    }],
    "pricingSummary": [{
        "totalLineItemPartnerPrice": 29.59,  // Net charge
        "currencyCode": "USD"
    }]
}

Fields explained:

Why am I getting "Quantity exceeded" (Error 2151) when I have enough licenses?

Answer: Common causes:

Resolution:

Step 1: Check current subscription quantity.

GET /v3/customers/{customerId}/subscriptions/{subscriptionId}

# Response shows actual available quantity
{
    "subscriptionId": "sub-123",
    "currentQuantity": 70,  // ← Actual available
    "offerId": "..."
}

Step 2: Adjust switch quantity to ≤ currentQuantity.

Revert switch

What is a revert switch and when should I use it?

Answer: A revert switch reverses a previous mid-term upgrade and restores the subscription to its original state.

What happens:

Time limitation:

Can I perform a partial revert switch?

Answer: No. When you perform a revert switch, you must revert the exact quantity as the original switch.

Example:

Original switch:

// Switched 30 licenses from Acrobat Pro to Acrobat Sign
{
    "orderType": "SWITCH",
    "lineItems": [{"quantity": 30}],
    "cancellingItems": [{"quantity": 30}]
}

Valid revert:

// Must revert all 30 licenses
{
    "orderType": "REVERT_SWITCH",
    "referenceOrderId": "original-switch-order-id",
    "lineItems": [{"quantity": 30}],  // Same as original
    "cancellingItems": [{"quantity": 30}]  // Same as original
}

Invalid revert:

// Cannot revert only 15 licenses
{
    "orderType": "REVERT_SWITCH",
    "referenceOrderId": "original-switch-order-id",
    "lineItems": [{"quantity": 15}],  // ← Error!
    "cancellingItems": [{"quantity": 15}]
}

Workaround for partial revert: If you need to keep some licenses on the new product:

  1. Revert the entire switch (all 30 licenses).
  2. Place a new switch order for the desired quantity (e.g., 15 licenses).

How do I perform a revert switch?

Answer: Follow this workflow:

POST /v3/customers/{customerId}/orders?fetch-price=true
{
    "orderType": "PREVIEW_REVERT_SWITCH",
    "currencyCode": "USD",
    "referenceOrderId": "{original-switch-order-id}",
    "lineItems": [{
        "offerId": "{original-offer-id}",  // Back to original
        "quantity": 30,  // Same as original switch
        "extLineItemNumber": 1
    }],
    "cancellingItems": [{
        "subscriptionId": "{switch-subscription-id}",  // New subscription to cancel
        "quantity": 30,  // Same as original switch
        "extLineItemNumber": 1,
        "referenceLineItemNumber": 1
    }],
    "externalReferenceId": "preview-revert-12345"
}

POST /v3/customers/{customerId}/orders
{
    "orderType": "REVERT_SWITCH",
    "currencyCode": "USD",
    "referenceOrderId": "{original-switch-order-id}",
    "lineItems": [{
        "offerId": "{original-offer-id}",
        "quantity": 30,
        "extLineItemNumber": 1
    }],
    "cancellingItems": [{
        "subscriptionId": "{switch-subscription-id}",
        "quantity": 30,
        "extLineItemNumber": 1,
        "referenceLineItemNumber": 1
    }],
    "externalReferenceId": "revert-12345"
}

Can I revert a switch multiple times?

Answer: No. Each switch can only be reverted once.

Scenario:

  1. Original: Acrobat Pro (100 licenses).
  2. Switch: 30 to Acrobat Sign → Creates sub-B.
  3. Revert: Back to Acrobat Pro → Cancels sub-B, restores 30 to original.
  4. Attempt second revert: Fails (sub-B already cancelled).

If you need to switch again: After reverting, you can create a new switch order (not a revert):

  1. Revert completed → Back to Acrobat Pro (100 licenses).
  2. New switch: 30 to Acrobat Sign → Creates sub-C (different subscription).

What happens if I try to revert a switch that's already been reverted?

Answer: The order will fail with an error.

Can I return licenses from a reverted subscription?

Answer: No. After a revert switch, you cannot place a return order on the switch subscription (it's already cancelled).

Can I perform concurrent revert switches on the same order?

Answer: No. Only one revert switch will succeed.

User reassignment

Can users be automatically reassigned during a mid-term upgrade?

Answer: Yes, but only for Teams-to-Teams upgrades.

What happens to user assignments if I don't use reassign-users=true?

Answer: Users will get removed from original license.

Special customer types

Can government (LGA) customers perform mid-term upgrades?

Answer: Yes, but with specific requirements:

Can global customers perform mid-term upgrades?

Answer: Yes, with significant limitations on cross-country switches.

API implementation

What are the required fields for a switch order?

Answer:

{
    "orderType": "SWITCH",  // Required: SWITCH, PREVIEW_SWITCH, REVERT_SWITCH
    "currencyCode": "USD",  // Required: ISO currency code
    "lineItems": [{  // Required: Array with exactly 1 item
        "offerId": "65325063CA01A12",  // Required: Target offer ID
        "quantity": 10,  // Required: Number of licenses to switch
        "extLineItemNumber": 1  // Required: Must be 1
    }],
    "cancellingItems": [{  // Required: Array with exactly 1 item
        "subscriptionId": "sub-123",  // Required: Subscription to switch from
        "quantity": 10,  // Required: Must match lineItems.quantity
        "extLineItemNumber": 1,  // Required: Must be 1
        "referenceLineItemNumber": 1  // Required: Must match lineItems.extLineItemNumber
    }],
    "externalReferenceId": "switch-12345"  // Required: Unique identifier
}

Why do I get "Line item and cancelling line item mismatch" (Error 2153)?

Answer: This error occurs when extLineItemNumber doesn't match referenceLineItemNumber.

Can I include multiple line items in a switch order?

Answer: No. Switch orders support only ONE line item.

What is the difference between extLineItemNumber and referenceLineItemNumber?

Answer:

Field
In
Description
Value for switch orders
extLineItemNumber
lineItems
Identifies the line item in the current order
Always 1
extLineItemNumber
cancellingItems
Identifies the cancelling item
Always 1
referenceLineItemNumber
cancellingItems
References which line item is being cancelled
Must match lineItems.extLineItemNumber

For switch orders: All three must be 1 (since only one line item is allowed).

What query parameters are available for switch orders?

Answer:

Parameter
For
Purpose
Value
fetch-price
PREVIEW_SWITCH <br />PREVIEW_REVERT_SWITCH
Get detailed pricing information
true, false
reassign-users
SWITCH
Automatically reassign users (Teams only)
true, false

Examples:

# Get pricing details
POST /v3/customers/{customerId}/orders?fetch-price=true

# Auto-reassign users
POST /v3/customers/{customerId}/orders?reassign-users=true

# Both parameters
POST /v3/customers/{customerId}/orders?fetch-price=true&reassign-users=true

Error handling

What are the common error codes for switch orders?

Answer:

Code
Error
Cause/resolution
2149
Quantity mismatch
lineItems.quantity ≠ cancellingItems.quantity. <br /> Ensure quantities match exactly.
2150
Switch path validity check failed.
Invalid switch path. <br /> Verify path exists with GET switch-paths API.
2151
Quantity exceeded.
Switch quantity > subscription quantity. <br />Check subscription currentQuantity.
2152
Multiple line items not supported.
More than 1 line item. <br /> Use single line item only.
2153
Line item and cancelling line item mismatch.
extLineItemNumber ≠ referenceLineItemNumber. <br /> Set both to 1.
2154
Upgrade not supported.
High Growth Offer restrictions, net refund scenario, or restricted product. <br /> Check product eligibility and pricing.
3115
Invalid subscription.
Subscription expired/cancelled. <br /> Verify subscription status.

General troubleshooting:

Miscellaneous

What are High Growth Offers and how do they affect switches?

Answer: High Growth Offers are special promotional subscriptions with restricted switch eligibility.

Restrictions:

Example:

Can I switch products across different regions?

Answer: Very limited. For global customers:

Allowed
Not allowed
Within same deployment
Yes
Same country, same deployment
Home country to deployment country
No
Error 2150 or 2154
Deployment country to home country
No
Error 2150 or 2154
Between different deployments
No
Error 2150 or 2154

Error message: "Switch path validity check failed" or "Upgrade not supported" with additional details like "Invalid deploymentId" or "Invalid currency."