diff --git a/src/pages/docs/order-management/create-order.md b/src/pages/docs/order-management/create-order.md index 96a7ecdc0..d5e45b6d6 100644 --- 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 index 2c635adba..80e739edc 100644 --- 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 index 7fda96beb..1157ae94a 100644 --- 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 index d0856bae2..f444a65b3 100644 --- a/src/pages/docs/references/error-handling.md +++ b/src/pages/docs/references/error-handling.md @@ -69,7 +69,7 @@ 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 \
\
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| @@ -77,6 +77,7 @@ Some error responses will include additionalDetails, an array of strings with mo |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 \
\
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 \
\
Not allowed to fetch Recommendations for Country `` |Fetch Recommendations \
Get Order \
Preview Order |400 | |5137|INVALID_LANGUAGE \
\
Not allowed to fetch Recommendations for language `` |Fetch Recommendations \
Get Order \
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 index 7a8c115d4..0a43e7c4e 100644 --- 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          | | diff --git a/src/pages/docs/release-notes/upcoming-releases.md b/src/pages/docs/release-notes/upcoming-releases.md index 63b5ddef2..1b944e080 100644 --- a/src/pages/docs/release-notes/upcoming-releases.md +++ b/src/pages/docs/release-notes/upcoming-releases.md @@ -1,8 +1,46 @@ # Upcoming releases +## Partial quantity returns for VIP Marketplace orders + +**Expected release:** August, 2026 + +Partners can now return a portion of an eligible line item quantity from a NEW or RENEWAL order within 14 days of the order date. Previously, partners could return only the entire line item quantity in a single request. + +**What changed?** + +The following enhancements support partial quantity returns for eligible orders: + +- The newly introduced `remainingQuantity` parameter on the Order resource indicates the quantity that is still available for return in NEW and RENEWAL orders. The [Get Order Details](../order-management/get-order.md) and [Get Ordr History](../order-management/get-order.md#get-the-order-history-of-a-customer) APIs return this parameter. The value is initially set to the line item's quantity and decreases after each return or mid-term Switch Plan cancellation associated with that line item. +- You can now submit a return request for any quantity that is less than or equal to the line item's `remainingQuantity`. The request and response schema of a `RETURN` order remains unchanged. +- You can submit multiple partial returns against the same line item. Each return request is validated against the line item's current `remainingQuantity`. +- Partial quantity returns are not supported for Switch Plan orders, Stock Credit Packs, Acrobat license packs, MOQ offers, or consumables such as Sign transactions. +- Licenses associated with a returned quantity are deprovisioned immediately after the return order is completed. + +For complete request and response examples and a list of supported error codes, see [Return or cancellation of order](../order-management/order-scenarios.md#return-or-cancellation-of-order). + +**Why it matters** + +Previously, when a customer needed fewer licenses than originally ordered, partners had to return the entire line item and place a new order for the correct quantity. This process could result in a revenue gap of 1 to 14 days between the full-term billed return and the day-billed replacement order. + +With partial quantity returns, partners can return only the quantity that the customer no longer requires through a single request, eliminating the need to create a replacement order. + +**Action required** + +Review the following updates to ensure that your integration supports partial quantity returns: + +| Action | Details | +|----------|----------| +| Read `remainingQuantity` on `NEW` and `RENEWAL` orders | Use the `remainingQuantity` parameter instead of the line item's `quantity` parameter to determine how many units are eligible for return. | +| Handle the new 422 error codes | Support the following error codes: `RETURN_QTY_EXCEEDS_REMAINING`, `RETURN_NOT_SUPPORTED_MOQ_SKU`, `RETURN_NOT_SUPPORTED_SWITCH_ORDER`, and `RETURN_VIOLATES_3YC_MCQ`. | +| Continue using existing full-line return logic | No changes are required for existing full-line returns. Returning the full original quantity of a line item in a single request continues to work as before. | + +### Sandbox changes + +The Order details also displays the remaining quantity available for return. For more information, see [Cancel an order in Sandbox](../../sandbox/sandbox-portal/order-management/cancel-order.md). + ## Churn and seat expansion propensity are now surfaced in the Recommendations API -**Expected release:** July 2026 +**Expected release:** August 2026 Partners can now see churn risk and seat expansion signals for each customer through the existing [Fetch Recommendations](../recommendations/apis.md#fetch-recommendations) (`POST /v3/recommendations`) API. diff --git a/src/pages/sandbox/sandbox-portal/order-management/cancel-order.md b/src/pages/sandbox/sandbox-portal/order-management/cancel-order.md index f8208c84d..abfffb786 100644 --- a/src/pages/sandbox/sandbox-portal/order-management/cancel-order.md +++ b/src/pages/sandbox/sandbox-portal/order-management/cancel-order.md @@ -1,14 +1,19 @@ # Cancel an order -Cancellation of Orders can be done through either the Portal or through Postman. Attempting to cancel an Order 14 days (about 2 weeks) after its creation will be rejected. +Cancellation of Orders can be done through either the Portal or through Postman. Attempts to cancel an order more than 14 days after its creation are rejected. Cancelling an order will update the subscriptions associated with the Order as follows: - Subscription quantity will be lowered by the quantity of the associated Order line item. - Subscriptions that only have licenses from this Order will also change to status 1004 (inactive) after the quantity is set to zero. +- Subscription quantity and status updates may take some time after the order is cancelled. Poll the subscription to retrieve the updated quantity and status. +- The `quantity` field at the lineItem level indicates the original quantity placed on the order. +- The `remainingQuantity` field at the lineItem-level indicates the quantity that is still available for return in NEW and RENEWAL orders. -Subscription quantity and status updates may take time after canceling the Order. Please poll the subscription for updated quantity/status. +**Note:** Both full order cancellations and partial returns are allowed. -**Note:** Only full order cancellations are allowed. +![alt text]() -Orders can be canceled through the Portal by changing the status of the order to 1008 – Cancelled. The process to change an order's status is found in the section ‘Editing the Order Status and Creation Date (Portal Only)’ above. +You can cancel orders through the Portal by changing the order status to 1008 – Cancelled. For information about changing an order's status, see [Editing the Order Status and Creation Date (Portal Only)](./edit-order-status.md). + +For more information on cancellation and partial returns, see [Return or cancellation of order](../../../docs/order-management/order-scenarios.md#return-or-cancellation-of-order). diff --git a/src/pages/sandbox/sandbox-portal/order-management/image (13).png b/src/pages/sandbox/sandbox-portal/order-management/image (13).png new file mode 100644 index 000000000..a1cd9eed0 Binary files /dev/null and b/src/pages/sandbox/sandbox-portal/order-management/image (13).png differ