AdobeDocs · lijumjose · Jul 21, 2026 · Jul 21, 2026
diff --git a/src/pages/docs/order-management/create-order.md b/src/pages/docs/order-management/create-order.md
@@ -8,10 +8,12 @@ Ensure that you are aware of the following before creating an order:
 
 - `orderType` is required in the Create Order request.
   - Possible values are: NEW, RETURN, PREVIEW, PREVIEW_RENEWAL, or RENEWAL
+  - See [Order Scenarios](./order-scenarios.md) for request and response samples for each order type.
 - `subscriptionId` is mandatory in lineitems for:
   - `orderType` RENEWAL
   - `orderType` PREVIEW_RENEWAL if lineitems are present
 - `referenceOrderId` is required for RETURN orders and should not be included for other order types.
+- For `RETURN` orders that reference a `NEW` or `RENEWAL` order, you can now return a quantity that is less than the original line item quantity, within 14 days of the original order. The requested quantity is validated against the line item’s current `remainingQuantity` value on the original order. See [Return or cancellation of order](order-scenarios.md#return-or-cancellation-of-order) for details on eligibility, exclusions, and error codes.
 - `currencyCode` should now be sent at the lineItem-level instead of order level.
   - For backwards compatibility, `currencyCode` can still be sent at the order level.
 - The `discountCode` is applicable only to High Volume Discount customers who have migrated from VIP to VIP MP. You can use the discount code only if their discount level in VIP is between 17 and 22.
@@ -85,6 +87,11 @@ Order resource without read-only fields:
 }
 ```
 
+**Notes:**
+
+- See [Order Scenarios](./order-scenarios.md) for request and response samples for each order type.
+- See [Order resource](../references/resources.md#order-top-level-resource) for descriptions for each request and response parameter.
+
 ## HTTP status codes
 
 | Status code | Description                 |

diff --git a/src/pages/docs/order-management/get-order.md b/src/pages/docs/order-management/get-order.md
@@ -42,11 +42,20 @@ None.
     {
       "extLineItemNumber": 4,
       "offerId": "80004567EA01A12",
-      "quantity": 1,
+      "quantity": 70,
       "subscriptionId": "86756309",
       "status": "1000",
       "currencyCode": "USD",
-      "deploymentId": "12345"
+      "deploymentId": "12345",
+      "remainingQuantity": 60
+    },
+    {
+      "extLineItemNumber": 5,
+      "offerId": "65304479CA01A12",
+      "quantity": 50,
+      "subscriptionId": "9245678",
+      "status": "1000",
+      "remainingQuantity": 50
     }
   ],
   "links": {
@@ -59,6 +68,14 @@ None.
 }
 ```
 
+See [Order resource](../references/resources.md#order-top-level-resource) for descriptons corresponding to each parameter included in the response.
+
+**remainingQuantity**
+
+The `remainingQuantity` parameter is included at the lineItem level for `NEW` and `RENEWAL` orders. It indicates the quantity available after the returns and mid-term switch plan cancellations against the same line item.
+
+This field is not  present on `RETURN` order responses. For orders placed before this field was introduced, `remainingQuantity` is populated the first time the order is read, rather than backfilled in advance. See [Return or cancellation of order](order-scenarios.md#return-or-cancellation-of-order) for how it's used to validate a return request.
+
 ### HTTP status codes
 
 | Status code | Description                         |
@@ -160,7 +177,8 @@ The `promotions` array indicates the promotions applied to the Order. For exampl
        "quantity": 1, 
        "status": "1002", 
        "subscriptionId": "", 
-       "currencyCode": "USD", 
+       "currencyCode": "USD",
+       "remainingQuantity": 1,
        "promotions": [ 
                   { 
                       "code": "SUMMER_SALE_123", 
@@ -174,7 +192,8 @@ The `promotions` array indicates the promotions applied to the Order. For exampl
        "quantity": 11, 
        "status": "1002", 
        "subscriptionId": "", 
-       "currencyCode": "USD", 
+       "currencyCode": "USD",
+       "remainingQuantity": 10, 
        "promotions": [ 
                   { 
                       "code": "WINTER_SALE_123", 
@@ -258,6 +277,7 @@ The pricing data is returned only when:
       "subscriptionId": "", 
       "status": "", 
       "currencyCode": "USD",
+      "remainingQuantity": 10,
       "proratedDays" : 90,
       "pricing": {
             "partnerPrice": 365.00,              
@@ -328,6 +348,7 @@ For complete set of request and response parameter descriptions, refer to [Order
                     "subscriptionId": "cc92f750c3455ea60250bf20e7814dNA",
                     "status": "1000",
                     "currencyCode": "USD",
+                    "remainingQuantity": 2500,
                     "pricing": {
                             "partnerPrice": 365.00,              
                             "discountedPartnerPrice": 365.00,  

diff --git a/src/pages/docs/order-management/order-scenarios.md b/src/pages/docs/order-management/order-scenarios.md
@@ -71,14 +71,20 @@ This section lists the sample requests and responses of an order with `orderType
 
 ## Return or cancellation of order
 
+This section lists the sample requests and responses of an order with `orderType` - RETURN.
+
 **Notes:**
 
 - `referenceOrderId` is the order that is being returned.
 - `referenceOrderId` must be a valid, returnable order.
-  - Either NEW or RENEWAL.
+  - Eligible source order types: `NEW` or `RENEWAL`, including auto-renewal and early renewal orders, placed within the last 14 days.
+  - **Not eligible:** 
+    - The return or cancellation of `SWITCH` orders are not supported using `orderType` as `RETURN`. Use [`REVERT_SWITCH`](#order-scenarios-corresponding-to-mid-term-upgrade) instead. 
+    - Stock Credit Packs, or SCP, Acrobat license packs, MOQ offers, and consumables, such as Sign transactions, are also not eligible.
 - Line items being returned must match `extLineItemNumber`, `offerId`, and quantity of the original order:
   - Line items can be cancelled independently in the same or different RETURN order.
-  - No partial line item cancellations.
+  - Partial line item cancellations are allowed. See [Partial return considerations](#partial-returns) for details.
+  - The `quantity` parameter indicates the quantity being returned. The value can be equal to or less than the quantity owned.
 - Same 1000 | 1002 | 1004 statuses.
 - As line items from an order get cancelled, the line item status on the original order changes from 1000 to 1008.
   - When all line items for an order are cancelled, the status changes to 1008 for the original order.
@@ -130,6 +136,83 @@ This section lists the sample requests and responses of an order with `orderType
 }
 ```
 
+### Partial returns
+
+Partial quantity returns are supported for eligible `NEW` and `RENEWAL` orders within the return window. You can return part of a line item, and you can submit multiple partial returns against the same line item. Each request is validated against the line item’s current `remainingQuantity` value.
+
+For example, if a line item starts with a quantity of 70 and you return 10, the `remainingQuantity` becomes 60. If you later return 5 more, the `remainingQuantity` becomes 55. Returning the full original quantity in a single request is still supported.
+
+**Sample request**
+
+```json
+{
+  "referenceOrderId": "0123456789",
+  "orderType": "RETURN",
+  "externalReferenceId": "759",
+  "currencyCode": "USD",
+  "lineItems": [
+    {
+      "extLineItemNumber": 4,
+      "offerId": "80004567EA01A12",
+      "quantity": 10,
+      "currencyCode": "USD",
+      "deploymentId": "12345"
+    }
+  ]
+}
+```
+
+The return response is the same as a standard return. The credit is calculated using the pricing from the original order. To confirm the updated returnable quantity, call [Get order details](get-order.md) for the *original* order:
+
+**Request:** `GET /v3/customers/9876543210/orders/0123456789`
+
+**Response:**
+
+```json
+{
+  "orderId": "0123456789",
+  "orderType": "RENEWAL",
+  "status": "1000",
+  "lineItems": [
+    {
+      "extLineItemNumber": 4,
+      "offerId": "80004567EA01A12",
+      "quantity": 70,
+      "subscriptionId": "a4f1c2d0-0001",
+      "status": "1000",
+      "remainingQuantity": 60
+    }
+  ],
+  "links": {}
+}
+```
+
+The `remainingQuantity` drops from 70 to 60. Each request is checked against the current value. Licenses covered by the returned quantity are de-provisioned immediately once the return is accepted.
+
+#### **Validation and errors**
+
+A RETURN request against a NEW or RENEWAL line item is rejected with HTTP 422, if it does not meet the required conditions. The original order remains unchanged.
+
+| Scenario | Condition | Error code |
+|---|---|---|
+| Return exceeds remaining quantity | Requested quantity is greater than the current **remainingQuantity** | **RETURN_QTY_EXCEEDS_REMAINING** |
+| Minimum Order Quantity offer | Offer is flagged as MOQ | **RETURN_NOT_SUPPORTED_MOQ_SKU** |
+| Switch Plan order | Referenced order is a **SWITCH** order. Use **REVERT_SWITCH** instead. | **RETURN_NOT_SUPPORTED_SWITCH_ORDER** |
+| Three-Year Commit minimum | Return would reduce the committed product-family quantity below the minimum commit quantity | **RETURN_VIOLATES_3YC_MCQ** |
+
+Each rejection response uses the same structure.
+
+```json
+{
+  "code": "RETURN_QTY_EXCEEDS_REMAINING",
+  "message": "Requested return quantity 60 exceeds remaining returnable quantity 55 for line item 4 (offer 80004567EA01A12)."
+}
+```
+
+#### **Switch Plan interaction**
+
+If a later Switch Plan moves licenses off the original line item, the original line item’s `remainingQuantity` decreases by the switched amount. For example, if a NEW order line item has a quantity of 100 and a Switch Plan moves 20 licenses to a new product, the original line item’s `remainingQuantity` becomes 80. The partner can return up to 80 units against the original order. Returning more than 80 is rejected with `RETURN_QTY_EXCEEDS_REMAINING`.
+
 ## Preview an order
 
 The  `Create Order` API with `orderType` PREVIEW is a simulated order request that helps partners validate and prepare an order before actually placing it.

diff --git a/src/pages/docs/references/error-handling.md b/src/pages/docs/references/error-handling.md
@@ -69,14 +69,15 @@ Some error responses will include additionalDetails, an array of strings with mo
 |2117 | Cancellation window has closed | Cancel Order | 400|
 |2118 | Order has already been cancelled | Cancel Order | 400|
 |2119 | Too many line items| Preview Order, Create Order |400|
-|2120 | Line item quantity out of range| Preview Order, Create Order |400|
+|2120 | Line item quantity out of range \<br /\>\<br /\> Reason: Requested cancel quantity exceeds remaining quantity | Preview Order, Create Order |400|
 |2121 | Duplicate line item numbers| Preview Order, Create Order|400|
 |2122 | Line item Offer ID is invalid |Preview Order, Create Order| 400|
 |2123 | extLineItemNumber out of range |Preview Order, Create Order| 400|
 |2124| Distributor not allowed to sell the program |Preview Order, Create Order| 400|
 |2125| Distributor not allowed to sell in the currency for the region |Preview Order, Create Order| 400|
 |2125| Distributor not allowed to sell in the currency for the region |Preview Order, Create Order| 400|
 |2126| externalReferenceId exceeds maximum character limit | Create Order, Create Reseller, Create Customer|400|
+|2127| Order cancellation is not allowed \<br /\>\<br /\> Reason: Requested cancel quantity exceeds remaining quantity | Create Order|400|
 |2128 | Currency is not valid for Offer ID |Preview Order, Create Order| 400|
 |2129| Customer is not eligible to purchase Offer ID| Create Order | 400|
 |2130| Line item Offer ID does not match original order| Create Return Order (V3) | 400|
@@ -147,17 +148,27 @@ Some error responses will include additionalDetails, an array of strings with mo
 |5136 |INVALID_COUNTRY \<br /\> \<br /\>Not allowed to fetch Recommendations for Country  `<code>` |Fetch Recommendations \<br /\>Get Order \<br /\>Preview Order |400 |
 |5137|INVALID_LANGUAGE \<br /\> \<br /\>Not allowed to fetch Recommendations for language `<Code>` |Fetch Recommendations \<br /\>Get Order \<br /\>Preview Order | 400 |
 
+## 2127 Ineligible order cancellation
+
+These reason code values are included in the `additionalDetails` array for 2127 errors.
+
+| REASON_CODE                                            | Description                                                                                                                                                         | Action Required                                                                                                                                      |
+|--------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| SWITCH_ORDER_CANCELLATION_NOT_ALLOWED                  | Referenced order is a SWITCH order. Partial quantity returns are not supported for Switch Plan orders.                                                              | Use `REVERT_SWITCH` instead.                                                                                                                         |
+| THREE_YEAR_COMMIT                                      | Return would reduce the committed product-family quantity below the minimum commit quantity                                                                         | Modify the return quantity so that the remaining quantity does not fall below the minimum committed quantity.                                        |
+| PARTIAL_CANCELLATION_NOT_ALLOWED_FOR_SCP_OR_CONSUMABLE | Partial quantity returns are not supported for Switch Plan orders, Stock Credit Packs, Acrobat license packs, MOQ offers, or consumables such as Sign transactions. | Remove  Switch Plan orders, Stock Credit Packs, Acrobat license packs, MOQ offers, or consumables such as Sign transactions from the partial return. |
+
 ## 2129 Ineligible Purchase REASON_CODE List
 
 These REASON_CODE values are included in the `additionalDetails` array for 2129 errors.
 
-|REASON_CODE | Description | Action Required|
-|----| --- | -- |
-|INELIGIBLE_SWITCH| The order includes products that are incompatible with each other or with a product the customer already has. |Try removing the incompatible line item and placing the order again |
-|INELIGIBLE_ADD_ON| Customer is attempting to purchase an add-on product without the base product.| Try placing the order again with the base product included.|
-|INELIGIBLE_CONSUMED| RETURN order only: customer is attempting to return a consumable product that has already been consumed. |Order cannot be returned if the transactions are consumed. |
-|INELIGIBLE_MARKET_SEGMENT| The order includes an item that belongs to a market segment that either the reseller or the customer do not belong to.| Ensure the correct offer is used for the customer and reseller’s market segment.|
-|CUSTOMER_NOT_ELIGIBLE_FOR_PURCHASE| Customer is purchasing the offer multiple times in the same term.| Retry order placement with a qualifying product.|
+| REASON_CODE                        | Description                                                                                                            | Action Required                                                                  |
+|------------------------------------|------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
+| INELIGIBLE_SWITCH                  | The order includes products that are incompatible with each other or with a product the customer already has.          | Try removing the incompatible line item and placing the order again              |
+| INELIGIBLE_ADD_ON                  | Customer is attempting to purchase an add-on product without the base product.                                         | Try placing the order again with the base product included.                      |
+| INELIGIBLE_CONSUMED                | RETURN order only: customer is attempting to return a consumable product that has already been consumed.               | Order cannot be returned if the transactions are consumed.                       |
+| INELIGIBLE_MARKET_SEGMENT          | The order includes an item that belongs to a market segment that either the reseller or the customer do not belong to. | Ensure the correct offer is used for the customer and reseller’s market segment. |
+| CUSTOMER_NOT_ELIGIBLE_FOR_PURCHASE | Customer is purchasing the offer multiple times in the same term.                                                      | Retry order placement with a qualifying product.                                 |
 
 ## 2141 Ineligible Flexible Discounts REASON_CODE list
 

diff --git a/src/pages/docs/references/resources.md b/src/pages/docs/references/resources.md
@@ -166,6 +166,7 @@ Please see the Validations/Regular Expressions section for any regular expressio
 |status (read only)| String | Status code of the line item | 4 characters|
 |currencyCode | String | Currency code applicable for the offer | 3 characters|
 |proratedDays | Integer |  The number of days for which order will be invoiced. This applies in the case of mid-term purchases.| |
+|remainingQuantity | Integer |  The quantity available after the returns and mid-term switch plan cancellations against the same line item.| |
 | flexDiscounts        | Object | Details of the flexible discount applied to that lineItem             | |
 | flexDiscounts[].id  | String | A unique identifier for the flexible discount. Used to retrieve or reference a specific flexible discount.          | |
 | flexDiscounts[].code  | String | The flexible discount code that was applied to that lineItem          | |