Get growth margins

Applies To

Partner Center

Appropriate roles

Admin agent

Important

The growth margins API is now available in production.

Partners can get a list of active growth margins for a given market (country/region) and segment. This method returns available current growth margins based on the growth margins available start and end dates.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.
Segment represents the type of customer the growth margins are enabled for. Currently supports only commercial.
Country represents the customer country/region growth margins are available for. Country is represented by a two character country code.

REST request

[GET] /v1/catalog/benefits?type=growthmargin&country={country-code}&segment={segment}&baseSkuPaths={baseSkuPaths}

Request syntax

Method	Request URI
GET	{baseURL}/v1/catalog/benefits?type=growthmargin&country={country-code}&segment={segment}&baseSkuPaths={baseSkuPaths} HTTP/1.1

URI parameter

Use the following query parameters to return available growth margins.

Name	Type	Required	Description
type	string	Y	The type of benefit to retrieve. Use `growthmargin` for growth margins.
segment	string	Y	A string that determines which growth margins are available for a given segment.
country	string	Y	A two letter country code determining which customer country/region growth margins are available for.
baseSkuPaths	string	N	Optional. A comma-separated list of up to 10 base product SKUs in `{productId}:{skuId}` or `{productId}/{skuId}` format (for example, `CFQ7TTC0ZSXK:0002,CFQ7TTC0ZSXK:0005`). Returns only benefits whose `requiredProducts` match the specified SKUs. Requests with more than 10 SKU paths return HTTP `400 Bad Request`.

Request headers

For more information, see Partner Center REST headers.

Request body

None

Request example

GET https://api.partnercenter.microsoft.com/v1/catalog/benefits?type=growthmargin&country=US&segment=commercial HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

Request example with baseSkuPaths filter

GET https://api.partnercenter.microsoft.com/v1/catalog/benefits?type=growthmargin&country=US&segment=commercial&baseSkuPaths=CFQ7TTC0ZSXK:0002,CFQ7TTC0ZSXK:0005 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US

REST response

If successful, this method returns a collection of growth margins.

Response fields

The response uses a collection envelope. Response fields are read-only.

Response collection fields

Field	Type	Returned	Description
`totalCount`	integer	Always	Number of growth margin objects returned in `items`.
`items`	array of objects	Always	Growth margins matching the requested market, segment, and optional `baseSkuPaths` filter. The array can be empty when no offers match.
`attributes`	object	Always	Metadata that describes the response collection.
`attributes.objectType`	string	Always	Resource type of the response. The value is `Collection`.

Each object in items has the following fields.

Growth margin identity and required product fields

These fields distinguish the growth margin discount product from the base products to which it can apply.

Field	Type	Returned	Description
`items[].id`	string	Always	Catalog identifier for the growth margin discount product and pricing point, in `{productId}:{skuId}:{availabilityId}` format. This value doesn't identify the base product being purchased.
`items[].productCodes`	array of objects	Always	Product code identities for the growth margin. Process every entry because a growth margin can have more than one product code or term association.
`items[].productCodes[].productCode`	string	Always	Product code, also called the Universal Product Name (UPN), that integrations can use to identify the growth margin.
`items[].productCodes[].termId`	string	Conditional	Term identifier associated with the product code. Omitted when the product code isn't term-specific.
`items[].name`	string	Always	Display name of the growth margin.
`items[].description`	string	Always	Human-readable description of the growth margin.
`items[].requiredProducts`	array of objects	Always	Base product purchase configurations to which the growth margin can apply. These values identify the product being purchased, not the growth margin discount product.
`items[].requiredProducts[].productId`	string	Always	Product ID of an applicable base product.
`items[].requiredProducts[].skuId`	string	Always	SKU ID of an applicable base product. Leading zeros are significant.
`items[].requiredProducts[].termDuration`	string	Always	Applicable base-product term in ISO 8601 duration format, such as `P1Y`.
`items[].requiredProducts[].billingCycle`	string	Always	Applicable base-product billing cycle, such as `Monthly` or `Annual`.

Pricing and offer policy fields

Pricing policies describe the margin value. Offer policies describe when the growth margin is available and who receives it.

Field	Type	Returned	Description
`items[].productPolicy`	object	Always	Container for the pricing, offer, and eligibility policies that define the growth margin.
`items[].productPolicy.pricingPolicies`	array of objects	Always	Pricing rules for the growth margin. Process every policy and benefit entry.
`items[].productPolicy.pricingPolicies[].policyId`	string	Always	Identifier of the pricing policy.
`items[].productPolicy.pricingPolicies[].policyData.benefits`	array of objects	Always	Margin calculations defined by the pricing policy.
`items[].productPolicy.pricingPolicies[].policyData.benefits[].type`	string	Always	Calculation type, such as `PercentDiscount`.
`items[].productPolicy.pricingPolicies[].policyData.benefits[].value`	decimal	Always	Margin value interpreted according to `type`. For `PercentDiscount`, `0.15` represents 15%.
`items[].productPolicy.offerPolicies`	array of objects	Always	Offer rules that define the growth margin availability period and beneficiary.
`items[].productPolicy.offerPolicies[].policyId`	string	Always	Identifier of the offer policy.
`items[].productPolicy.offerPolicies[].policyData.beneficiary`	string	Always	Recipient of the benefit. The value for a growth margin is `Partner`.
`items[].productPolicy.offerPolicies[].policyData.properties.startDate`	string	Always	Start of the availability period in ISO 8601 date-time format.
`items[].productPolicy.offerPolicies[].policyData.properties.endDate`	string	Always	End of the availability period in ISO 8601 date-time format.
`items[].productPolicy.offerPolicies[].policyData.isOptional`	boolean	Always	Whether applying the offer policy is optional.

Eligibility policy fields

Eligibility policies describe the rules that the eligibility API evaluates. Discovery of a growth margin doesn't confirm that a specific customer transaction qualifies.

Field	Type	Returned	Description
`items[].productPolicy.eligibilityPolicies`	array of objects	Always	Eligibility rule sets for the growth margin. Process every entry because an offer can have multiple policies.
`items[].productPolicy.eligibilityPolicies[].policyId`	string	Always	Identifier of the eligibility policy.
`items[].productPolicy.eligibilityPolicies[].policyData.eligibility.constraintsData`	object	Always	Static product, ownership, seat, purchase, prerequisite, and partner constraints used to evaluate qualification.
`items[].productPolicy.eligibilityPolicies[].policyData.eligibility.dynamicPurchaseConstraint`	object	Conditional	Dynamic purchase rule for Strategic SKU Mix scenarios. Omitted when the growth margin doesn't use a dynamic rule.

Arrays can contain multiple entries. Process every item in productCodes, requiredProducts, pricingPolicies, benefits, offerPolicies, and eligibilityPolicies rather than assuming each collection contains one value.

The eligibilityPolicies array contains the following constraint types:

Constraint	Definition
seatConstraints	Defines the minimum or maximum seat requirements that must be met for a transaction to qualify for Growth Margin. Examples include minimum net-new seats or required seat expansion thresholds.
assetOwnershipLimits	Defines limits based on the customer's existing ownership of qualifying subscriptions or assets. Growth Margin eligibility may depend on whether the customer already owns, previously owned, or currently holds qualifying subscriptions.
eligibilityConstraints	Defines the set of business rules that determine whether a transaction qualifies for Growth Margin. These rules can include customer history, seat growth requirements, product eligibility, purchase timing, and other qualifying criteria.
productOwnershipConstraints	Defines product ownership conditions that must be met before Growth Margin can be applied. For example, eligibility may depend on whether the customer currently owns, previously owned, or does not own a specific product or SKU. The structure uses AND-of-OR groups: the outer array represents AND conditions (all must be met), and each inner array represents OR alternatives (at least one must be met). For example, `[[A, B], [C]]` means the customer must own (A or B) AND C.
purchaseRequirementConstraints	Defines purchase-specific requirements that must be satisfied for Growth Margin eligibility, such as purchasing a qualifying product, meeting a minimum seat threshold, selecting an eligible term, or creating a new subscription when required.
prerequisiteConstraints	Defines prerequisite product ownership conditions evaluated within a configurable lookback window. Uses `MustHaveAll`, `MustHaveAny`, and `MustHaveNone` rules to specify products the customer must own, may own any of, or must not own to qualify. Each rule can include seat constraints and a lookback period over which ownership is evaluated.
partnerConstraints	Defines partner-level eligibility conditions through the `isApplicable` and `type` fields.

The seatConstraints value is an array. Each entry has a type that determines which companion fields apply:

`type`	Companion fields
`SubscriptionQuantity`	`minSeats`, `maxSeats`
`SeatGrowthMultiplier`	`seatIncreaseMultiplier`, `minSeats`, `maxSeats`

A growth margin can define a subscription quantity constraint, a seat growth multiplier constraint, or both. When both types are present in the seatConstraints array, the transaction must satisfy both constraints to qualify. Process every entry in the array rather than assuming that seatConstraints contains a single value.

Partner constraints

Each entry in partnerConstraints defines a partner-level eligibility condition.

Field	Type	Description
`isApplicable`	boolean	Indicates whether the partner condition identified by `type` applies.
`type`	string	Identifies the partner eligibility condition being evaluated.

Prerequisite constraints

The prerequisiteConstraints object can contain MustHaveAll, MustHaveAny, and MustHaveNone rules. Each property contains a rule object or null:

MustHaveAll: The customer must satisfy every listed product prerequisite.
MustHaveAny: The customer must satisfy at least one listed product prerequisite.
MustHaveNone: The customer must not satisfy any listed product prerequisite.

Each non-null rule object can contain the following fields. Property names use the exact PascalCase returned by the API.

Field	Type	Description
`Products`	array of objects	Products evaluated by the prerequisite rule.
`Products[].BigId`	string	Product and SKU in `{productId}/{skuId}` format, such as `CFQ7TTC0LFLZ/0002`.
`Products[].MinSeats`	integer or null	Minimum seats required for the product.
`Products[].MaxSeats`	integer or null	Maximum seats allowed for the product.
`SeatConstraint`	object	Aggregate seat rule across the products.
`SeatConstraint.Type`	string	Aggregate rule type, such as `BaseCumulativeQuantity`.
`SeatConstraint.MinSeats`	integer or null	Minimum aggregate seats required.
`SeatConstraint.MaxSeats`	integer or null	Maximum aggregate seats allowed.
`LookbackWindow`	object	Time window used to evaluate product ownership.
`LookbackWindow.Type`	string	Lookback type, such as `Period`.
`LookbackWindow.Period`	string	Lookback duration in ISO 8601 format, such as `P1Y`.

Dynamic purchase constraint for Strategic SKU Mix

The optional dynamicPurchaseConstraint object defines a Strategic SKU Mix rule. It is omitted when the growth margin doesn't use a dynamic purchase rule.

Field	Type	Description
`ResourceProvider`	string	Resource provider that evaluates the rule, such as `saashubrp`.
`ConfigurationProperties`	object	Configuration for the dynamic purchase rule.
`ConfigurationProperties.type`	string	Rule type. Use `UpsellTargetRatio` for a Strategic SKU Mix ratio rule.
`ConfigurationProperties.upsellSkuSet`	array of strings	Product and SKU paths counted as upsell SKUs.
`ConfigurationProperties.qualificationSkuSet`	array of strings	Product and SKU paths included in the qualification calculation.
`ConfigurationProperties.ratioThreshold`	string	Required ratio expressed as a decimal string, such as `"0.8"`.
`ConfigurationProperties.minimumSeats`	integer	Minimum number of upsell seats required.
`ConfigurationProperties.evaluationScope`	string	Scope at which the rule is evaluated, such as `TenantLevel`.

{
  "ConfigurationProperties": {
    "upsellSkuSet": [
      "CFQ7TTC0LFLZ/0002"
    ],
    "qualificationSkuSet": [
      "CFQ7TTC0LFLX/0001",
      "CFQ7TTC0LFLZ/0002"
    ],
    "ratioThreshold": "0.8",
    "minimumSeats": 5,
    "evaluationScope": "TenantLevel",
    "type": "UpsellTargetRatio"
  },
  "ResourceProvider": "saashubrp"
}

Response success and error codes

Each response comes with an HTTP status code that indicates success or failure and more debugging information. Use a network trace tool to read this code, error type, and more parameters. For the full list, see Error Codes.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 18752a69-1aa1-4ef7-8f9d-eb3681b2d70a
Date: Fri, 27 Jun 2026 20:42:26 GMT

{
  "totalCount": 1,
  "items": [
    {
        "id": "39NFJQT10HW7:0002:084R5MQ9QF27",
        "productCodes": [
            {
                "productCode": "00093c3a-0000-0280-f57d-f85412b6826d"
            }
        ],
        "name": "CSP Growth Margin Discount",
        "description": "CSP Growth Margin Discount",
        "requiredProducts": [
            {
                "productId": "CFQ7TTC0ZSXK",
                "skuId": "0002",
                "termDuration": "P1Y",
                "billingCycle": "Monthly"
            }
        ],
        "productPolicy": {
            "pricingPolicies": [
                {
                    "policyId": "PricingPolicyId:1w11wcikt5po",
                    "policyData": {
                        "benefits": [
                            {
                                "type": "PercentDiscount",
                                "value": 0.185
                            }
                        ]
                    }
                }
            ],
            "offerPolicies": [
                {
                    "policyId": "OfferPolicyId:qossxtmg4hky",
                    "policyData": {
                        "beneficiary": "Partner",
                        "properties": {
                            "startDate": "2026-05-12T14:20:05Z",
                            "endDate": "2026-08-12T14:20:11Z"
                        },
                        "isOptional": false
                    }
                }
            ],
            "eligibilityPolicies": [
                {
                    "policyId": "EligibilityPolicyId:ewgn4xy9whko",
                    "policyData": {
                        "eligibility": {
                            "constraintsData": {
                                "seatConstraints": [
                                    {
                                        "minSeats": 0,
                                        "maxSeats": 0,
                                        "seatIncreaseMultiplier": 0,
                                        "type": "SeatGrowthMultiplier"
                                    }
                                ],
                                "assetOwnershipLimits": [],
                                "eligibilityConstraints": [],
                                "productOwnershipConstraints": [
                                    []
                                ],
                                "purchaseRequirementConstraints": [],
                                "prerequisiteConstraints": {
                                    "MustHaveAll": null,
                                    "MustHaveAny": null,
                                    "MustHaveNone": {
                                        "Products": [
                                            {
                                                "BigId": "CFQ7TTC10849/0002",
                                                "MinSeats": null,
                                                "MaxSeats": 5
                                            }
                                        ],
                                        "SeatConstraint": {
                                            "MinSeats": null,
                                            "MaxSeats": null,
                                            "Type": "BaseCumulativeQuantity"
                                        },
                                        "LookbackWindow": {
                                            "Type": "Period",
                                            "Period": "P1Y"
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            ]
        }
    }
  ],
  "attributes": {
    "objectType": "Collection"
  }
}

Note

The baseSkuPaths parameter is purely a server-side filter. The response shape is the same whether or not baseSkuPaths is supplied — it only restricts the result set to benefits matching those base SKUs.

Feedback

Was this page helpful?

Last updated on 2026-09-23