Get Subscription Promotions via API

Introduction 

The Subscription Promotions API allows Distributors, Sellers, and Customers to retrieve promotion records applied to a specific Subscription. This endpoint returns detailed promotion data from the Platform, including Markup values, validity periods, promotion categories, and Organization-specific benefits. The Markup value represents the promotion discount expressed as a negative number (for example, -5.00 means a 5% promotion discount).

This API supports Microsoft Growth Margin scenarios. Growth margins are incremental partner margins that Microsoft provides to Microsoft Cloud Solution Provider partners for driving high-value growth into strategic products, such as new-to-offer wins, seat expansion, and adoption of select AI workloads. When a growth margin applies, the partner receives a new partner price for the transaction in addition to the standard base margin. Growth margins are partner-earned economics (a partner margin), not a Customer-facing Discount. Customer-facing promotions can stack on top of a growth margin. For more details on how growth margins work within the Platform, see What is Growth Margin and how does it work?

The Category field in the response indicates whether a promotion record is a standard promotion ("Default") or a growth margin ("GrowthMargin"). This endpoint enables partners and integrations to retrieve and manage promotional data for both new purchases and existing Subscriptions, without relying solely on calculated pricing results.

In this article:

• Overview of the endpoint

• Request details

  • Path parameter

  • Headers

• Response structure
• Error handling
• Organization scope and filtering
• Scenarios
• Example request and response
• Summary
• Related content

Overview of the endpoint

The GET /subscriptions/{subscriptionId}/promotions endpoint retrieves all promotion records associated with a given Subscription. The response includes both promotions and Organization-specific promotions. A single Subscription can carry both types at the same time.

Key capabilities of this endpoint:

• Retrieve promotions already applied to a Subscription

• View Discount details, validity periods, and promotion categories

• Access Organization-specific promotional benefits

• Support Microsoft Growth Margin scenarios

• Provide data needed by external integrations to manage promotions

Request details

Method and route:

GET https://api.appxite.com/subscription/subscriptions/{subscriptionId}/promotions

Path parameter

• subscriptionId
  • Mandatory parameter
  • The unique identifier (GUID) of the Subscription for which you want to retrieve promotion records.

Headers

• Authorization
  • Bearer token (existing authentication)
• X-Referer
  • The URL of the requesting Platform
• X-On-Behalf-Of
  • The identifier of the user on whose behalf the request is made
• Content-Type
  • application/json

Response structure

A successful request returns a 200 OK response containing a Promotions array wrapped in a JSON object. The array can contain zero, one, or multiple promotion records.

Response fields

When a Subscription has no promotions, the endpoint returns 200 OK with an empty Promotions array. This is a normal response, not an error.

Error handling

Errors are returned using standard HTTP status codes with a ProblemDetails body that describes what went wrong.

Example error response:

{
  "title": "Not Found",
  "status": 404,
  "detail": "No subscription found with id {subscriptionId}."
}

Organization scope and filtering

All roles authenticate using the same mechanism: a Bearer token passed in the Authorization header, together with the X-Referer (identifying the Platform) and X-On-Behalf-Of (identifying the user). The token carries the caller's existing Platform permission scope, and the endpoint uses that scope to determine which promotion records to return.

The filtering rules are:

• Promotions (where OrganizationId is null) are always returned to any authorized caller.

• Organization-specific promotions are returned only if the caller has permission to view that Organization.

• Rows for Organizations outside the caller's scope are silently dropped from the array.

What each role sees

This means two different callers querying the same Subscription can receive different arrays, depending on their access rights. For example, a Seller calling a Subscription that also holds a Distributor-scoped row will not see the Distributor's promotion record, because the Distributor's Markup rate is outside the Seller's permission scope.

Scenarios

The following table describes expected results for common scenarios:

Example request and response

Example request

GET https://api.appxite.com/subscription/subscriptions/{subscriptionId}/promotions

Headers:
  X-Referer: https://{your-platform-domain}/
  X-On-Behalf-Of: {user-id}
  Content-Type: application/json
  Authorization: Bearer {your-access-token}

Example response — Customer role

A Customer calling this endpoint sees only the promotion record. The Organization-specific rows are not visible to this role:

{
  "Promotions": [
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "39NFJQT1W0JK:0001:39NFJQT1Q5KV",
      "Markup": -5.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": null,
      "Category": "Default"
    }
  ]
}

Example response — Seller Admin role

Indirect Model (multi-tier) Seller — by default, a Seller admin in the Indirect Model sees only the promotion record:

{
  "Promotions": [
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "39NFJQT1W0JK:0001:39NFJQT1Q5KV",
      "Markup": -5.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": null,
      "Category": "Default"
    }
  ]
}

Direct Model (one-tier) Seller, or Indirect Model Seller upon request — a Seller admin in the Direct Model sees the Growth Margin record with the Seller's Organization ID alongside the promotion. For Indirect Model Sellers, this view becomes available after reaching out to the Support team and requesting it:

{
  "Promotions": [
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "7BHK2MT4X9PL:0002:7BHK2MT4R3NW",
      "Markup": -12.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": "A1B2C3D4-E5F6-7890-ABCD-EF1234567890",
      "Category": "GrowthMargin"
    },
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "39NFJQT1W0JK:0001:39NFJQT1Q5KV",
      "Markup": -5.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": null,
      "Category": "Default"
    }
  ]
}

Example response — Distributor Admin role

A Distributor admin sees all promotion records, including the Organization-specific growth margin and the promotion:

{
  "Promotions": [
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "4RWP6NV8Y1QC:0003:4RWP6NV8K7MJ",
      "Markup": -12.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": "F9E8D7C6-B5A4-3210-FEDC-BA9876543210",
      "Category": "GrowthMargin"
    },
    {
      "SubscriptionId": "C5EB7DF8-ADD8-42AE-89C6-8EAFF4CFC336",
      "ExternalId": "39NFJQT1W0JK:0001:39NFJQT1Q5KV",
      "Markup": -5.00,
      "EffectiveFromDateUtc": "2024-07-01T00:00:00Z",
      "EffectiveTillDateUtc": "2025-06-30T00:00:00Z",
      "OrganizationId": null,
      "Category": "Default"
    }
  ]
}

Summary

The GET /subscriptions/{subscriptionId}/promotions endpoint provides a straightforward way to retrieve all promotion records for a Subscription. It supports Microsoft Growth Margin scenarios and respects the caller's permission scope by filtering out Organization-specific records the caller is not authorized to view. The endpoint returns all promotions regardless of their effective date status, giving partners and integrations full visibility into applied and historical promotions.