How to retrieve Adobe promotions via API

Introduction

This article explains how to use the API endpoint to retrieve available Adobe promotions (flexible discounts). The Platform provides functionality to validate and provision Adobe promotions. This API enables Distributors and Sellers to programmatically access the complete list of available promotions through the Developer Portal, allowing them to identify which Offers are eligible for promotional pricing, including reusable discounts that may be automatically applied at renewal.

In this article:

• Understanding the Adobe promotions API
• Required and optional parameters
• Authentication and permissions
• API request examples
• Understanding API responses
• Reusable flexible discounts
• Applying promotion codes in the Platform
• Error handling

Understanding the Adobe promotions API

The Adobe promotions API retrieves flexible discounts from Adobe's partner API and returns them to authorized users. This endpoint acts as a proxy to the Adobe API, requiring specific authentication and permissions to access promotional information.

The API returns data about active and (when requested) reusable promotions, including discount percentages, applicable Offers, validity periods, and qualification criteria.

Method: GET
Endpoint: https://api.appxite.com/adobe/get-flexible-discounts[?market-segment][&country][&start-date][&end-date][&limit][&offset][&flex-discount-code][&offer-ids][&categories][&include-eligible-reusable-discounts]

Required and optional parameters

Request parameters

• market-segment — Industry segment in 3-letter format. Supported values: COM (Commercial), GOV (Government), EDU (Education) [Required, query parameter].
• country — Country code in 2-alpha ISO 3166-1 format; examples: NO (Norway), SE (Sweden), LV (Latvia) [Required, query parameter].
• start-date — Start date filter in YYYY-MM-DD format [Optional, query parameter].
• end-date — End date filter in YYYY-MM-DD format [Optional, query parameter].
• limit — Maximum number of results [Optional, query parameter].
• offset — Number of results to skip for pagination (integer) [Optional, query parameter].
• flex-discount-code — Specific discount code filter [Optional, query parameter].
• offer-ids — Comma-separated list of Adobe external Offer identifiers; example: 65304579CA01A12 [Optional, query parameter].
• categories — Filter by promotion category. Supported values: STANDARD, INTRO [Optional, query parameter].
• include-eligible-reusable-discounts — When set to true, the response also returns reusable flexible discounts for which the Customer is eligible. Default value: false [Optional, query parameter].

Request headers (required)

• Ocp-Apim-Subscription-Key — Subscription Key generated upon subscribing for a relevant product [string].
• Authorization — Bearer Token [string].
• Api-Version — API Version (e.g. 1.0) [string].
• Accept-Language — Add language value to get a response in the selected language (where applicable). Language values ("Locale") can be retrieved by using the "List all Languages" API value. Examples of locale: en-US, fi, nl [string, optional].
• Environment — Environment (Sandbox or Production) [string, optional].
• X-Referer — Platform URL [string].

Authentication and permissions

The API follows the same authentication logic as other Adobe endpoints. Authentication requires:

• Valid referrer (portal).
• One of the following permission levels:
  • Distributor admin
  • Seller admin

Unauthorized users will receive an authentication error when attempting to access this endpoint.

API request examples

Basic request with mandatory parameters

curl --location 'https://api.appxite.com/adobe/get-flexible-discounts?market-segment=COM&country=NO' \
--header 'accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx' \
--header 'Api-Version: 1.0' \
--header 'X-Referer: https://your-platform-url.com'

Request with optional filters

curl --location 'https://api.appxite.com/adobe/get-flexible-discounts?market-segment=EDU&country=SE&categories=INTRO&limit=20' \
--header 'accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: [your-subscription-key]' \
--header 'Authorization: Bearer [your-bearer-token]' \
--header 'Api-Version: 1.0' \
--header 'Accept-Language: en-US' \
--header 'X-Referer: [your-platform-url]'

Request including reusable discounts

curl --location 'https://api.appxite.com/adobe/get-flexible-discounts?market-segment=COM&country=NO&include-eligible-reusable-discounts=true' \
--header 'accept: application/json' \
--header 'Ocp-Apim-Subscription-Key: [your-subscription-key]' \
--header 'Authorization: Bearer [your-bearer-token]' \
--header 'Api-Version: 1.0' \
--header 'X-Referer: [your-platform-url]'

Understanding API responses

Successful response (200 OK)

A successful request returns a JSON object containing:

• limit — Maximum results returned per page.
• offset — Current pagination offset.
• count — Number of results in current response.
• totalCount — Total number of matching promotions.
• flexDiscounts — Array of promotion objects.
• links — Navigation links for pagination.

Promotion object structure

Each promotion in the flexDiscounts array contains:

• id — Unique promotion identifier.
• category — Promotion category. Possible values:
  • STANDARD — Regular flexible discounts.
  • INTRO — Introductory offers available only to Customers who have never previously owned the Product.
• name — Descriptive promotion name.
• description — Detailed promotion description.
• code — Promotion code for application.
• startDate — Promotion start date (ISO 8601 format).
• endDate — Promotion end date (ISO 8601 format).
• status — Current promotion status. Possible values: ACTIVE, EXPIRED, REUSABLE.
• discountLockEndDate — Returned only for reusable discounts. Indicates the date through which the discount may continue to be applied beyond its endDate (ISO 8601 format). The presence of this field identifies the discount as reusable.
• qualification — Eligibility criteria including baseOfferIds array.
• outcomes — Array of discount details. Supported outcome types:
  • PERCENTAGE_DISCOUNT — Applies a percentage reduction to the standard price.
  • FIXED_DISCOUNT — Applies a fixed monetary reduction to the standard price. The discountValues array contains the country, currency, and value fields.
  • FIXED_PRICE — Sets the Product at a fixed promotional price, independent of volume discount levels. The discountValues array contains the country, currency, and value fields defining the fixed promotional price.

Example successful response (standard discount)

{
  "limit": 50,
  "offset": 0,
  "count": 1,
  "totalCount": 1,
  "flexDiscounts": [
    {
      "id": "XXXXXXXXXXXXXXXXX",
      "category": "STANDARD",
      "name": "Flexible Discount for COM for all countries",
      "description": "Exclusive 15% off on all products for COM",
      "code": "FLEX_DISC_COM_ALL_COUNTRIES",
      "startDate": "2025-01-01T10:00:48Z",
      "endDate": "2035-12-31T10:16:00Z",
      "status": "ACTIVE",
      "qualification": {
        "baseOfferIds": []
      },
      "outcomes": [
        {
          "type": "PERCENTAGE_DISCOUNT",
          "discountValues": [
            { "value": 15.0 }
          ]
        }
      ]
    }
  ],
  "links": {
    "self": {
      "uri": "/v3/flex-discounts?market-segment=COM&country=LV&limit=50&offset=0",
      "method": "GET",
      "headers": []
    }
  }
}

Example successful response (reusable discount)

{
  "limit": 50,
  "offset": 0,
  "count": 1,
  "totalCount": 1,
  "flexDiscounts": [
    {
      "id": "YYYYYYYYYYYYYYYYY",
      "category": "STANDARD",
      "name": "Loyalty discount – reusable",
      "description": "10% off, reusable on renewals until lock date",
      "code": "LOYALTY_REUSE_10",
      "startDate": "2026-01-01T00:00:00Z",
      "endDate": "2026-06-30T23:59:59Z",
      "status": "REUSABLE",
      "discountLockEndDate": "2027-12-31T23:59:59Z",
      "qualification": {
        "baseOfferIds": ["65304579CA01A12"]
      },
      "outcomes": [
        {
          "type": "PERCENTAGE_DISCOUNT",
          "discountValues": [
            { "value": 10.0 }
          ]
        }
      ]
    }
  ]
}

Reusable flexible discounts

Reusable flexible discounts allow eligible Customers to continue benefiting from a discount beyond its original endDate, until the configured discountLockEndDate. This reduces churn caused by sharp price increases at renewal and removes the need for the Customer to explicitly opt in again.

How standard and reusable discounts differ

How reusable discounts are applied

• If a Customer has used a reusable flexible discount before its endDate, that Customer can continue to use the same discount until the discountLockEndDate.
• When a reusable discount has already been used in an order that contributes to a Subscription, the Subscription will have the reusable discount automatically applied during auto-renewal until the discountLockEndDate.
• To auto-apply the reusable discount, Customers do not need to explicitly opt in using Update Subscription.
• If a flexible discount is explicitly opted in using Update Subscription, the explicitly opted discount takes priority, and the automatic application of the reusable discount does not occur.
• If multiple reusable flexible discounts have been used in different orders contributing to the same Subscription, the most recently applied reusable discount is automatically applied at auto-renewal.

Identifying a reusable discount in the response

A flexible discount is reusable if both of the following conditions are met in the API response:

• The status field is set to REUSABLE.
• The discountLockEndDate field is present.

Applying promotion codes in the Platform

Once a valid promotion code has been retrieved via the API, it can be applied directly in the Platform when placing an Order. To learn more, see the article How to apply Adobe promotion codes.

How to apply a promotion code

1. Open the Purchase Form for the relevant Product.
2. Locate the Promotion code field.
3. Enter the promotion code (e.g., VALUE_ADD_27).
4. Click View available promotions to validate the code and confirm it is applicable to the selected Offer.

Price table behaviour after applying a promotion code

Once a valid promotion code is applied, the price table updates automatically to reflect the promotional pricing. The Cost Price (you buy for) and the Customer Price (you sell for) are both recalculated based on the promotion terms:

• For PERCENTAGE_DISCOUNT promotions, the Cost Price is reduced by the defined percentage.
• For FIXED_DISCOUNT promotions, the Cost Price is reduced by the fixed monetary value defined in the promotion's discountValues.
• For FIXED_PRICE promotions, the Cost Price is replaced by the fixed promotional value defined in the promotion's discountValues.

The updated Cost Price and Customer Price are displayed alongside the standard prices, clearly indicating that a promotion has been applied. The Markup and Margin values in the price table are recalculated accordingly to reflect the new pricing.

Reusable discount applied at renewal

When a reusable discount is eligible for a Subscription, the Subscription Form displays the discount as automatically applicable at the next renewal. No additional action is required from the Customer until the discountLockEndDate is reached.

Error handling

Missing required parameter: market-segment

Response: 400 Bad Request

{
  "error": "Market segment (market-segment) is required"
}

Invalid market-segment format

Response: 400 Bad Request

{
  "error": "Market segment must be exactly 3 characters (e.g., COM, EDU)"
}

Missing required parameter: country

Response: 400 Bad Request

{
  "error": "Country (country) is required"
}

Invalid country code format

Response: 400 Bad Request

{
  "error": "Country must be 2 or 3 characters ISO 3166-1 alpha code"
}

Invalid country for partner

Response: 200 OK

{
  "error": "Failed to get flexible discounts for market segment COM and country US",
  "details": {
    "code": "1178",
    "message": "Invalid Country for Partner",
    "additionalDetails": []
  }
}

Limitations

• Reusable flexible discounts are only returned when include-eligible-reusable-discounts=true is explicitly passed in the request. The default behaviour returns only standard (non-reusable) discounts.
• Only one flexible discount code can be applied per line item in an Order Preview.
• An explicitly opted-in flexible discount on a Subscription (via Update Subscription) takes priority over an eligible reusable discount; the reusable discount is not auto-applied in that case.
• Flexible discount codes are not validated when creating or updating a Subscription. Validation of Customer eligibility occurs exclusively through the Preview Renewal API.
• A flexible discount code can be redeemed only once per Customer.

Summary

The Adobe promotions API provides a straightforward method for retrieving available flexible discounts through the Developer Portal. By using the required market-segment and country parameters, along with optional filters such as categories and include-eligible-reusable-discounts, administrators can programmatically access promotional information to determine which Offers qualify for discounts. The API returns comprehensive promotion details including discount types (PERCENTAGE_DISCOUNT, FIXED_DISCOUNT, and FIXED_PRICE), promotion categories (STANDARD and INTRO), validity periods, eligibility criteria, and — for reusable discounts — the discountLockEndDate indicating until when the discount may continue to be applied. When a promotion code is applied in the Platform, the price table automatically reflects the updated Cost Price and Customer Price. Reusable discounts are auto-applied to eligible Subscriptions at renewal without requiring additional opt-in. Proper error handling ensures clear feedback when parameters are missing, invalid, or unauthorized for the requesting Partner.

Related content

• Adobe Self service APIs
• How to apply Adobe promotion codes