From 38e9ee3e4c8a6bfa5979ebdeb1b2b364133e56b2 Mon Sep 17 00:00:00 2001 From: Liju M Jose Date: Thu, 14 May 2026 18:48:25 +0530 Subject: [PATCH 1/2] Updates to recommendations and flex discounts --- src/pages/docs/flex-discounts/apis.md | 4 +-- src/pages/docs/flex-discounts/index.md | 1 + src/pages/docs/mid-term/index.md | 2 +- src/pages/docs/recommendations/apis.md | 34 ++++++++++++++++++- src/pages/docs/recommendations/index.md | 21 ++++++++++-- .../docs/release-notes/upcoming-releases.md | 34 ++++++++++++++++++- 6 files changed, 89 insertions(+), 7 deletions(-) diff --git a/src/pages/docs/flex-discounts/apis.md b/src/pages/docs/flex-discounts/apis.md index 18f707abb..da5f71714 100644 --- a/src/pages/docs/flex-discounts/apis.md +++ b/src/pages/docs/flex-discounts/apis.md @@ -41,7 +41,7 @@ Sample Request URL: `GET /v3/flex-discounts?market-segment=COM&country=US` | flex-discount-id | String | No | Retrieve a flexible discount by its unique ID. This endpoint returns a single, unique flexible discount object. \
If flex-discount-id query parameter is provided in the request, other non-mandatory params cannot be provided in the same request. | Max: 40 characters | | flex-discount-code | String | No | Filter promotions by code. Examples: "DIWALI", "BLACK_FRIDAY". | | | include-eligible-reusable-discounts | Boolean | No | Include discounts that are not active, but the discount lock end date is still valid. | | -| start-date | String (date) | No | Filter flexible discounts that were available on or after the specified date and time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | +| start-date | String (date) | No | Filter flexible discounts that were available on or after the specified date and time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses.
Pass `start-date=` to scope results to currently-live discounts only. | | | end-date | String (date) | No | Filter flexible discounts that were available on or before this moment in time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | | limit | Integer | No | Specify the number of items to be returned in the response. Default: 20, Max: 50. | | | offset | Integer | No | Set the start offset for the result items. Default: 0 | | @@ -189,7 +189,7 @@ None. | endDate | String (Date) | The final date when the flexible discount can be used. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | startDate | String (Date) | The date from which the flexible discount can be used. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | discountLockEndDate | String (Date and Time) | The date through which a flexible discount may continue to be applied beyond its initial offering period (start/end date). Reusable discounts are identified by the presence of the `discountLockEndDate` field in the response. | -| status | String Enum | Status of flexible discount. Possible values: ACTIVE, EXPIRED, REUSABLE | +| status | String Enum | Status of flexible discount. Possible values: ACTIVE, EXPIRED, REUSABLE
**Note:** Flexible discounts with ACTIVE also includes both currently-running and future-dated discounts. The status field alone is no longer sufficient to determine whether a discount is live. Partners must compare `startDate` against the current date to know if a discount is usable right now. | | qualification | Object | | | qualification.baseOfferIds | Array of strings | List of Base Offer IDs of products eligible for flexible discount. Example: ["Offer ID 1", "Offer ID 2"] \
**Note**: The list of base Offer IDs will be empty if the flexible discount applies to all products. | | outcomes[] | Array of objects | | diff --git a/src/pages/docs/flex-discounts/index.md b/src/pages/docs/flex-discounts/index.md index da6ddfd98..7ce423819 100644 --- a/src/pages/docs/flex-discounts/index.md +++ b/src/pages/docs/flex-discounts/index.md @@ -14,6 +14,7 @@ Key advantages of flexible discounts include: - **Quick flexible discount launches for seasonal sales:** - Allows partners to activate discounts within days for timely seasonal discounts like Black Friday. + - Allows partners to discover upcoming discounts through the API ahead of their start date, enabling advance preparation of marketing and storefront workflows. - **Reusable discounts to automatic discount continuity across renewals** diff --git a/src/pages/docs/mid-term/index.md b/src/pages/docs/mid-term/index.md index 10baf9720..ee04ef25d 100644 --- a/src/pages/docs/mid-term/index.md +++ b/src/pages/docs/mid-term/index.md @@ -27,7 +27,7 @@ You can use the [GET Offer Switch Paths](apis.md#1-retrieve-upgrade-paths) API t You can either switch the entire quantity or a certain number of the original subscription quantity. **Example:** Out of 100 seats, only 40 are switched to Acrobat Standard Enterprise, and the remaining 60 stay on the original product. - If the upgrade path is marked `PARTIALLY_ALLOWED`, the partner can perform either a partial or full upgrade. + If the upgrade path is marked `PARTIAL_ALLOWED`, the partner can perform either a partial or full upgrade. **Note:** After a full switch, only the new product renews. After a partial switch, both products renew. The subscription's anniversary date remains unchanged. diff --git a/src/pages/docs/recommendations/apis.md b/src/pages/docs/recommendations/apis.md index f3a4f1f17..1e515a675 100644 --- a/src/pages/docs/recommendations/apis.md +++ b/src/pages/docs/recommendations/apis.md @@ -128,7 +128,30 @@ The following response header, added to all responses, provides data to understa }, }, ], - }, + } + "overlayRecommendations": { + "new": [ + { + "createdAt": "2026-01-27T08:15:35Z", + "expiresAt": "2026-02-27T08:15:35Z", + "status": "OPEN", + "items": [ + { "offerId": "30006208CA01A12", "quantity": 25 }, + { "offerId": "65318386CA02012", "quantity": 1 } + ] + } + ], + "renew": [ + { + "createdAt": "2026-01-28T09:20:10Z", + "expiresAt": "2026-02-28T09:20:10Z", + "status": "OPEN", + "items": [ + { "offerId": "30006208CA01A12", "quantity": 15 } + ] + } + ] + } } ``` @@ -146,6 +169,15 @@ The following response header, added to all responses, provides data to understa | source | Object | Indicates the source of the recommendation. | | sourceType | String | Specifies the type of the source entity. Currently only `OFFER` is supported. | | offerIds | String Array | List of offer IDs that contributed to this recommendation. | +| overlayRecommendations | Object | Contains overlay recommendation leads created by Adobe agents during overlay interactions. Present only when leads exist for the customer. For more information, see [Overlay recommendations](./index.md#overlay-recommendations). | +| new | Array of Leads | List of leads representing new purchase intent identified during overlay interactions. | +| renew | Array of Leads | List of leads representing renewal intent identified during overlay interactions. | +| createdAt | String (ISO-8601) | Timestamp when the lead was created. | +| expiresAt | String (ISO-8601) | Timestamp when the lead expires if not acted upon. | +| status | String | Lead lifecycle state. Possible values: `OPEN` and `EXPIRED`. | +| items | Array of Items | List of products and quantities in the lead. | +| offerId | String | Offer identifier (Part Number) for the lead item. | +| quantity | Integer | Number of units of the product in the lead. | ### HTTP Status Codes diff --git a/src/pages/docs/recommendations/index.md b/src/pages/docs/recommendations/index.md index 3b30943c9..bb19b0a6e 100644 --- a/src/pages/docs/recommendations/index.md +++ b/src/pages/docs/recommendations/index.md @@ -26,7 +26,7 @@ The [Fetch Recommendations](./apis.md#fetch-recommendations) API returns a ranke Recommendations are grouped into the following categories: -- **Upsell** +- **Upsell** Recommends a higher-tier version of a product the customer already owns. - **Cross-sell** @@ -79,7 +79,7 @@ As a result: ## Partner integration process to provide recommendations -Below is a high-level overview of the partner integration model for providing recommendations: +Below is a high-level overview of the partner integration model for providing non-overlay recommendations: ![Partner integration process](../image/reco.png) @@ -99,4 +99,21 @@ The following figure illustrates how recommendations are fetched to assist custo ![Recommendations Use Case sample](../image/reco_usecase.png) +## Overlay recommendations + +Adobe agents frequently engage directly with customers during overlay interactions to understand their needs and assess purchase intent. When an agent identifies a clear intent to purchase, a lead is generated on behalf of the customer and persisted within a Recommendation object. This lead is surfaced to the customer's assigned partner through the existing [Fetch Recommendations](./apis.md#fetch-recommendations) API. + +Overlay recommendations bridge the coordination gap between Adobe and partners by providing timely, actionable visibility into customer purchase intent. With this information, partners can proactively engage the customer, continue the conversation, and efficiently complete order placement. + +### How overlay recommendations differ from product recommendations? + +| Aspect | Product Recommendations | Overlay Recommendations | +|---|---|---| +| Source | Generated algorithmically by the recommendation engine | Created by Adobe agents during overlay interactions | +| Purpose | Suggest upsell, cross-sell, and add-on opportunities | Communicate customer purchase intent to partners | +| Structure | `productRecommendations` with `upsells`, `crossSells`, `addOns` | `overlayRecommendations` with `new` and `renew` lead arrays | +| Lifecycle | Dynamic per request | Stateful: OPEN, consumed on order placement, or expired | + +Both types are returned together in the [Fetch Recommendations](./apis.md#fetch-recommendations) response, allowing partners to discover product recommendations and purchase-intent leads in a single API call. + Read more about [how to manage recommendations using APIs](apis.md). diff --git a/src/pages/docs/release-notes/upcoming-releases.md b/src/pages/docs/release-notes/upcoming-releases.md index 2f7af623f..ee65e78da 100644 --- a/src/pages/docs/release-notes/upcoming-releases.md +++ b/src/pages/docs/release-notes/upcoming-releases.md @@ -1,3 +1,35 @@ # Upcoming releases -This topic will be updated soon. +## Flexible Discounts are now discoverable before their start date + +Partners can now view upcoming flexible discounts via the GET /v3/flex-discounts API immediately after they are published, even when the discount's start date is in the future. This is a default behavior change and does not require any additional flags or parameters. + +**What changed?** + +The `GET /v3/flex-discounts` endpoint now returns all published discounts regardless of whether their `startDate` has been reached. +Discounts with a future `startDate` are returned with status: ACTIVE. + +**Why it matters** + +Partners can now prepare marketing campaigns, brief resellers, and configure storefronts ahead of a discount's live date, rather than waiting for comms or account-manager outreach. + +**Action required** + +| Action | Details | +|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Use startDate for liveness checks | The status field alone no longer indicates whether a discount is live. Compare startDate to the current date to determine if a discount can be applied to orders today. | +| Audit existing logic | Review any integration logic that branches on status: ACTIVE as a proxy for "currently usable." | +| Legacy behavior | Pass `start-date=` as a query parameter to return only currently-live discounts. | + +## Overlay recommendations are now surfaced to partners + +Partners can now view Adobe-identified customer purchase intent through the existing `GET /v3/recommendations` API. When an Adobe agent identifies purchase intent during an overlay interaction, a lead is created and returned in the recommendations response under a new `overlayRecommendations` field. Partners also receive an email notification when a lead is created. + +**What changed?** + +The `GET /v3/recommendations` endpoint now returns an `overlayRecommendations` object alongside the existing `productRecommendations`. This object contains two arrays: + +- **`new`**: Leads where the customer expressed intent to purchase new products. +- **`renew`**: Leads where the customer expressed intent to renew existing subscriptions. + +Each lead includes `createdAt`, `expiresAt`, `status`, and an `items` array with `offerId` and `quantity`. Leads have a status of `OPEN` until they are consumed during order placement or automatically expired past their `expiresAt` date. From 6e94464a2e3dcb150f29f7928f1d72c404038260 Mon Sep 17 00:00:00 2001 From: Liju M Jose Date: Thu, 14 May 2026 18:55:03 +0530 Subject: [PATCH 2/2] Syntax issue fix --- src/pages/docs/flex-discounts/apis.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/pages/docs/flex-discounts/apis.md b/src/pages/docs/flex-discounts/apis.md index da5f71714..85248d3b3 100644 --- a/src/pages/docs/flex-discounts/apis.md +++ b/src/pages/docs/flex-discounts/apis.md @@ -41,7 +41,7 @@ Sample Request URL: `GET /v3/flex-discounts?market-segment=COM&country=US` | flex-discount-id | String | No | Retrieve a flexible discount by its unique ID. This endpoint returns a single, unique flexible discount object. \
If flex-discount-id query parameter is provided in the request, other non-mandatory params cannot be provided in the same request. | Max: 40 characters | | flex-discount-code | String | No | Filter promotions by code. Examples: "DIWALI", "BLACK_FRIDAY". | | | include-eligible-reusable-discounts | Boolean | No | Include discounts that are not active, but the discount lock end date is still valid. | | -| start-date | String (date) | No | Filter flexible discounts that were available on or after the specified date and time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses.
Pass `start-date=` to scope results to currently-live discounts only. | | +| start-date | String (date) | No | Filter flexible discounts that were available on or after the specified date and time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. \
Pass `start-date=` to scope results to currently-live discounts only. | | | end-date | String (date) | No | Filter flexible discounts that were available on or before this moment in time. This date can be without timestamp or with timestamp, for example, “2025-05-02" or "2025-05-02T22:49:54Z. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | | limit | Integer | No | Specify the number of items to be returned in the response. Default: 20, Max: 50. | | | offset | Integer | No | Set the start offset for the result items. Default: 0 | | @@ -189,7 +189,7 @@ None. | endDate | String (Date) | The final date when the flexible discount can be used. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | startDate | String (Date) | The date from which the flexible discount can be used. Dates with timestamps are only accepted in ISO-8601 format with "Zulu" (UTC) time zone. This is the same format that all dates and times are in Adobe Commerce Partner API (CPAI) responses. | | discountLockEndDate | String (Date and Time) | The date through which a flexible discount may continue to be applied beyond its initial offering period (start/end date). Reusable discounts are identified by the presence of the `discountLockEndDate` field in the response. | -| status | String Enum | Status of flexible discount. Possible values: ACTIVE, EXPIRED, REUSABLE
**Note:** Flexible discounts with ACTIVE also includes both currently-running and future-dated discounts. The status field alone is no longer sufficient to determine whether a discount is live. Partners must compare `startDate` against the current date to know if a discount is usable right now. | +| status | String Enum | Status of flexible discount. Possible values: ACTIVE, EXPIRED, REUSABLE \
**Note:** Flexible discounts with ACTIVE also includes both currently-running and future-dated discounts. The status field alone is no longer sufficient to determine whether a discount is live. Partners must compare `startDate` against the current date to know if a discount is usable right now. | | qualification | Object | | | qualification.baseOfferIds | Array of strings | List of Base Offer IDs of products eligible for flexible discount. Example: ["Offer ID 1", "Offer ID 2"] \
**Note**: The list of base Offer IDs will be empty if the flexible discount applies to all products. | | outcomes[] | Array of objects | |