Manage orders - Get a benefit by name

Service:
Partner Center Rest
API Version:
v1

Gets a specific benefit using its discount name.
Retrieves a specific Azure Consumption Promotion discount by name. The benefit must exist under an Azure subscription within the partner's Azure Plan for this customer.

GET https://api.partnercenter.microsoft.com/v{version}/customers/{customer_id}/benefits/{benefit_name}

URI Parameters

Name In Required Type Description
benefit_name
 path True

string

The benefit (discount) resource name. This corresponds to the ARM discount name (a GUID when created through Partner Center, any string otherwise), not the discount identifier.
customer_id
 path True

string

The customer identifier.
version
 path True

string

The API version number.

Request Header

Name Required Type Description
Authorization True

string

Authorization ******
ms-correlationid

string

Used for tracking requests internally. If a ms-correlationid is not provided, the server will generate a new one for each request
ms-cv

string

Used for tracking requests internally. If a ms-cv is not provided, the server will generate a new one for each request
ms-requestid

string

Used for idempotency of requests. If a ms-requestid is not provided, the server will generate a new one for each request
Accept True

string

Typically application/json.

Responses

Name Type Description
200 OK

Benefit

The request was successful. The response body contains the benefit information.

Media Types: "application/json", "text/json", "application/xml", "text/xml"
400 Bad Request

There was a missing or an invalid input. The response body will provide the error details.

Media Types: "application/json", "text/json", "application/xml", "text/xml"
401 Unauthorized

The request was not authenticated. The client needs to authenticate with the partner API service first.

Media Types: "application/json", "text/json", "application/xml", "text/xml"
403 Forbidden

The request was authenticated but was refused since the caller does not have the rights to invoke it.

Media Types: "application/json", "text/json", "application/xml", "text/xml"
404 Not Found

The resource is not found or not available with the given input parameters.

Media Types: "application/json", "text/json", "application/xml", "text/xml"
500 Internal Server Error

The partner API service or one of its dependencies failed to fulfill the request. Callers may retry this.

Media Types: "application/json", "text/json", "application/xml", "text/xml"

Definitions

Name Description
Benefit

Represents a benefit (Azure Consumption Promotion discount) associated with a customer.
BenefitAppliedScopeProperties

Represents the properties of the scope that a benefit is applied to.
BenefitLinks

Represents the links to related resources for a benefit.
BenefitScheduledNextTermInstructions

Represents the instructions that are applied to a benefit at the start of its next term.
ConsumptionDetails

Represents how much of a benefit has been consumed.
Link

Represents a link resource.
ProductIdentifier

Identifies a product by its product identifier and SKU identifier.
PurchaseCommitment

Represents a purchase commitment resource.
ScheduledAction

Represents a scheduled action resource.
StringStringKeyValuePair

Represents a key value pair resource.
SubscriptionDetails

Represents the Azure subscription details for a benefit.

Benefit

Object

Represents a benefit (Azure Consumption Promotion discount) associated with a customer.

Name Type Description
appliedScope

string

The scope that the benefit is applied to.
appliedScopeProperties

BenefitAppliedScopeProperties

The properties of the scope that the benefit is applied to.
autoRenewEnabled

boolean

A value indicating whether the benefit renews automatically at the end of its term.
billingCycle enum:
  • annual
  • biennial
  • monthly
  • none
  • one_time
  • quadrennial
  • quinquennial
  • triennial
  • unknown

The billing cycle for the benefit. Possible values include: 'unknown', 'monthly', 'annual', 'none', 'one_time', 'triennial', 'biennial', 'quadrennial', 'quinquennial'.
consumptionDetails

ConsumptionDetails

The details of how much of the benefit has been consumed.
creationDate

string (date-time)

The date and time when the benefit was created, in UTC.
discountPercentage

number (double)

The discount percentage (0-100). Omitted when not applicable.
displayName

string

The display name of the benefit.
endDate

string (date-time)

The date and time when the benefit ends, in ISO 8601 format. Omitted when the benefit has no expiry. Uses ISO 8601 date-time format.
externalSystemId

string

The identifier for the benefit in the external system that created it.
kind enum:
  • AzurePromotion
  • SpendPlan

The kind of benefit. Possible values include: 'AzurePromotion', 'SpendPlan'.
links

BenefitLinks

Links to related resources.
name

string

The benefit name. This corresponds to the ARM discount name (a GUID when created through Partner Center, any string otherwise).
orderId

string

The Partner Center order identifier. Omitted when the benefit was not ordered through Partner Center.
product

ProductIdentifier

The product identifier (product ID and SKU ID) associated with the benefit.
purchaseCommitment

PurchaseCommitment

The purchase commitment that the benefit was bought under.
scheduledActions

ScheduledAction[]

The actions that are scheduled to run against the benefit.
startDate

string (date-time)

The date and time when the benefit starts, in ISO 8601 format. Uses ISO 8601 date-time format.
status enum:
  • Active
  • Disabled
  • Exhausted
  • Expired
  • None
  • Pending

The current status of the benefit. Possible values include: 'None', 'Active', 'Pending', 'Expired', 'Disabled', 'Exhausted'.
subscriptionDetails

SubscriptionDetails

The Azure subscription details (subscription identifier, resource group, and ARM resource identifier) the benefit is scoped to.
termDuration

string

The duration of the benefit term, in ISO 8601 format.

BenefitAppliedScopeProperties

Object

Represents the properties of the scope that a benefit is applied to.

Name Type Description
resourceGroupName

string

The name of the resource group that the benefit is applied to.
subscriptionId

string

The identifier for the Azure subscription that the benefit is applied to.
Object

Represents the links to related resources for a benefit.

Name Type Description
next

Link

Additional next associated with the resource links.
previous

Link

Additional previous associated with the resource links.
self

Link

The link to the benefit resource itself.

BenefitScheduledNextTermInstructions

Object

Represents the instructions that are applied to a benefit at the start of its next term.

Name Type Description
billingCycle enum:
  • annual
  • biennial
  • monthly
  • none
  • one_time
  • quadrennial
  • quinquennial
  • triennial
  • unknown

The billing cycle to apply for the next term. Possible values include: 'unknown', 'monthly', 'annual', 'none', 'one_time', 'triennial', 'biennial', 'quadrennial', 'quinquennial'.
productCode

string

The product code for the product to purchase for the next term.
productId

string

The identifier for the product to purchase for the next term.
purchaseCommitment

PurchaseCommitment

The purchase commitment to apply for the next term.
skuId

string

The identifier for the SKU to purchase for the next term.
termDuration

string

The duration of the next term, in ISO 8601 format.

ConsumptionDetails

Object

Represents how much of a benefit has been consumed.

Name Type Description
amount

number (double)

The amount of the benefit that has been consumed.
currency

string

The currency code for the consumed amount.
percentage

number (double)

The percentage of the benefit that has been consumed.
Object

Represents a link resource.

Name Type Description
body

string

The body for the link.
headers

StringStringKeyValuePair[]

The collection of headers associated with this link.
method

string

The method for the link.
uri

string

The URI for the related resource.

ProductIdentifier

Object

Identifies a product by its product identifier and SKU identifier.

Name Type Description
productCode

string

The product code for the product.
productId

string

The product identifier.
skuId

string

The SKU identifier.

PurchaseCommitment

Object

Represents a purchase commitment resource.

Name Type Description
amount

number (double)

The monetary amount.
currency

string

The three-letter ISO currency code.
grain

string

The measurement grain used for this value.

ScheduledAction

Object

Represents a scheduled action resource.

Name Type Description
actionType enum:
  • Cancel
  • RenewToExtendedServiceTerm
  • RenewToNewTerm
  • Transition

The action to perform. Supported values are RenewToExtendedServiceTerm, Cancel, RenewToNewTerm, and Transition.
effectiveDate

string (date-time)

The date and time when a CustomDate scheduled action takes effect, in ISO 8601 format.
instructions

BenefitScheduledNextTermInstructions

The product, quantity, and term instructions for the scheduled change. Not used for Cancel.
scheduleType enum:
  • BillingCycleEnd
  • CustomDate
  • TermEnd

When the action takes effect. Supported values are TermEnd, BillingCycleEnd, and CustomDate.

StringStringKeyValuePair

Object

Represents a key value pair resource.

Name Type Description
key

string

The key for the key value pair.
value

string

The value for the key value pair.

SubscriptionDetails

Object

Represents the Azure subscription details for a benefit.

Name Type Description
resourceGroup

string

The Azure resource group containing the discount.
resourceId

string

The full ARM resource identifier of the discount.
subscriptionId

string

The Azure subscription identifier the discount is scoped to. Value is typically a GUID.