Microsoft Azure Savings Plan API

swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Savings Plan API
schemes:
- https
tags:
- name: Savings Plan
paths:
  /providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans:
    get:
      description: List savings plans in an order.
      operationId: microsoftAzureSavingsplanList
      tags:
      - Savings Plan
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        SavingsPlansInOrderList:
          $ref: ./examples/SavingsPlansInOrderList.json
      parameters:
      - $ref: '#/parameters/SavingsPlanOrderIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanModelList'
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Get Providers Microsoft Billingbenefits Savingsplanorders Savingsplanorderid Savingsplans
  /providers/Microsoft.BillingBenefits/savingsPlans:
    get:
      description: List savings plans.
      operationId: microsoftAzureSavingsplanListall
      tags:
      - Savings Plan
      x-ms-pageable:
        nextLinkName: nextLink
      x-ms-examples:
        SavingsPlansList:
          $ref: ./examples/SavingsPlansList.json
      parameters:
      - $ref: '#/parameters/ApiVersionParameter'
      - name: $filter
        description: May be used to filter by reservation properties. The filter supports 'eq', 'or', and 'and'. It does not currently support 'ne', 'gt', 'le', 'ge', or 'not'. Reservation properties include sku/name, properties/{appliedScopeType, archived, displayName, displayProvisioningState, effectiveDateTime, expiryDate, provisioningState, quantity, renew, reservedResourceType, term, userFriendlyAppliedScopeType, userFriendlyRenewState}
        in: query
        required: false
        type: string
      - name: $orderby
        description: May be used to sort order by reservation properties.
        in: query
        required: false
        type: string
      - name: refreshSummary
        description: To indicate whether to refresh the roll up counts of the savings plans group by provisioning states
        in: query
        required: false
        type: string
      - name: $skiptoken
        description: The number of savings plans to skip from the list before returning results
        in: query
        required: false
        type: number
      - name: selectedState
        description: The selected provisioning state
        in: query
        required: false
        type: string
      - name: take
        description: To number of savings plans to return
        in: query
        required: false
        type: number
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanModelListResult'
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Get Providers Microsoft Billingbenefits Savingsplans
  /providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans/{savingsPlanId}:
    get:
      description: Get savings plan.
      operationId: microsoftAzureSavingsplanGet
      tags:
      - Savings Plan
      x-ms-examples:
        SavingsPlanItemGet:
          $ref: ./examples/SavingsPlanItemGet.json
        SavingsPlanItemWithExpandedRenewPropertiesGet:
          $ref: ./examples/SavingsPlanItemExpandedGet.json
      parameters:
      - $ref: '#/parameters/SavingsPlanOrderIdParameter'
      - $ref: '#/parameters/SavingsPlanIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/ExpandParameter'
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanModel'
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Get Providers Microsoft Billingbenefits Savingsplanorders Savingsplanorderid Savingsplans Savingsplanid
    patch:
      description: Update savings plan.
      operationId: microsoftAzureSavingsplanUpdate
      tags:
      - Savings Plan
      x-ms-examples:
        SavingsPlanUpdate:
          $ref: ./examples/SavingsPlanUpdate.json
      parameters:
      - $ref: '#/parameters/SavingsPlanOrderIdParameter'
      - $ref: '#/parameters/SavingsPlanIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/SavingsPlanUpdateRequestParameter'
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanModel'
        '202':
          description: The request is accepted.
          headers:
            Location:
              type: string
        '404':
          description: Not found.
          x-ms-error-response: true
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Patch Providers Microsoft Billingbenefits Savingsplanorders Savingsplanorderid Savingsplans Savingsplanid
  /providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans/{savingsPlanId}/validate:
    post:
      description: Validate savings plan patch.
      operationId: microsoftAzureSavingsplanValidateupdate
      tags:
      - Savings Plan
      x-ms-examples:
        SavingsPlanValidateUpdate:
          $ref: ./examples/SavingsPlanValidateUpdate.json
      parameters:
      - $ref: '#/parameters/SavingsPlanOrderIdParameter'
      - $ref: '#/parameters/SavingsPlanIdParameter'
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/SavingsPlanUpdateValidateRequestParameter'
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanValidateResponse'
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Post Providers Microsoft Billingbenefits Savingsplanorders Savingsplanorderid Savingsplans Savingsplanid Validate
  /providers/Microsoft.BillingBenefits/validate:
    post:
      description: Validate savings plan purchase.
      operationId: microsoftAzureValidatepurchase
      tags:
      - Savings Plan
      x-ms-examples:
        SavingsPlanValidatePurchase:
          $ref: ./examples/SavingsPlanValidatePurchase.json
      parameters:
      - $ref: '#/parameters/ApiVersionParameter'
      - $ref: '#/parameters/SavingsPlanPurchaseValidateRequestParameter'
      responses:
        '200':
          description: The request is completed.
          schema:
            $ref: '#/definitions/SavingsPlanValidateResponse'
        default:
          description: Unexpected error.
          schema:
            $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/ErrorResponse
      summary: Microsoft Azure Post Providers Microsoft Billingbenefits Validate
definitions:
  Price:
    type: object
    properties:
      currencyCode:
        type: string
        description: The ISO 4217 3-letter currency code for the currency used by this purchase record.
      amount:
        type: number
        format: double
  PurchaseRequestProperties:
    type: object
    properties:
      displayName:
        type: string
        description: Friendly name of the savings plan
      billingScopeId:
        $ref: '#/definitions/BillingScopeId'
      term:
        $ref: '#/definitions/Term'
      billingPlan:
        $ref: '#/definitions/BillingPlan'
      appliedScopeType:
        $ref: '#/definitions/AppliedScopeType'
      commitment:
        $ref: '#/definitions/Commitment'
      effectiveDateTime:
        $ref: '#/definitions/EffectiveDateTime'
      renew:
        $ref: '#/definitions/Renew'
      appliedScopeProperties:
        $ref: '#/definitions/AppliedScopeProperties'
  BenefitStartTime:
    type: string
    format: date-time
    description: This is the DateTime when the savings plan benefit started.
  RenewDestination:
    type: string
    description: SavingsPlan Id of the SavingsPlan which is purchased because of renew.
  Sku:
    type: object
    description: The SKU to be applied for this resource
    properties:
      name:
        type: string
        description: Name of the SKU to be applied
  SavingsPlanModelProperties:
    type: object
    description: Savings plan properties
    properties:
      displayName:
        $ref: '#/definitions/DisplayName'
      provisioningState:
        $ref: '#/definitions/ProvisioningState'
      displayProvisioningState:
        description: The provisioning state of the savings plan for display, e.g. Succeeded
        type: string
        readOnly: true
      billingScopeId:
        $ref: '#/definitions/BillingScopeId'
      billingProfileId:
        $ref: '#/definitions/BillingProfileId'
      customerId:
        $ref: '#/definitions/CustomerId'
      billingAccountId:
        $ref: '#/definitions/BillingAccountId'
      term:
        $ref: '#/definitions/Term'
      billingPlan:
        $ref: '#/definitions/BillingPlan'
      appliedScopeType:
        $ref: '#/definitions/AppliedScopeType'
      userFriendlyAppliedScopeType:
        description: The applied scope type of the savings plan for display, e.g. Shared
        type: string
        readOnly: true
      appliedScopeProperties:
        $ref: '#/definitions/AppliedScopeProperties'
      commitment:
        $ref: '#/definitions/Commitment'
      effectiveDateTime:
        $ref: '#/definitions/EffectiveDateTime'
      expiryDateTime:
        $ref: '#/definitions/ExpiryDateTime'
      purchaseDateTime:
        $ref: '#/definitions/PurchaseDateTime'
      benefitStartTime:
        $ref: '#/definitions/BenefitStartTime'
      extendedStatusInfo:
        $ref: '#/definitions/ExtendedStatusInfo'
      renew:
        $ref: '#/definitions/Renew'
      utilization:
        $ref: '#/definitions/Utilization'
      renewSource:
        $ref: '#/definitions/RenewSource'
      renewDestination:
        $ref: '#/definitions/RenewDestination'
      renewProperties:
        $ref: '#/definitions/RenewProperties'
  RenewSource:
    type: string
    description: SavingsPlan Id of the SavingsPlan from which this SavingsPlan is renewed.
  SavingsPlanUpdateRequest:
    type: object
    description: Savings plan patch request
    properties:
      properties:
        $ref: '#/definitions/SavingsPlanUpdateRequestProperties'
  SavingsPlanOrderAliasProperties:
    type: object
    description: Savings plan properties
    properties:
      displayName:
        $ref: '#/definitions/DisplayName'
      savingsPlanOrderId:
        type: string
        description: Identifier of the savings plan created
        readOnly: true
      provisioningState:
        $ref: '#/definitions/ProvisioningState'
      billingScopeId:
        $ref: '#/definitions/BillingScopeId'
      term:
        $ref: '#/definitions/Term'
      billingPlan:
        $ref: '#/definitions/BillingPlan'
      appliedScopeType:
        $ref: '#/definitions/AppliedScopeType'
      appliedScopeProperties:
        $ref: '#/definitions/AppliedScopeProperties'
      commitment:
        $ref: '#/definitions/Commitment'
      renew:
        $ref: '#/definitions/Renew'
  UtilizationAggregates:
    description: The aggregate values of savings plan utilization
    type: object
    properties:
      grain:
        description: The grain of the aggregate
        readOnly: true
        type: number
      grainUnit:
        description: The grain unit of the aggregate
        readOnly: true
        type: string
      value:
        description: The aggregate value
        readOnly: true
        type: number
      valueUnit:
        description: The aggregate value unit
        readOnly: true
        type: string
  EffectiveDateTime:
    type: string
    format: date-time
    description: DateTime of the savings plan starts providing benefit from.
    readOnly: true
  SavingsPlanModel:
    type: object
    description: Savings plan
    required:
    - sku
    allOf:
    - $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/Resource
    properties:
      sku:
        description: Savings plan SKU
        $ref: '#/definitions/Sku'
      properties:
        description: Savings plan properties
        x-ms-client-flatten: true
        $ref: '#/definitions/SavingsPlanModelProperties'
  ExtendedStatusInfo:
    type: object
    readOnly: true
    properties:
      statusCode:
        type: string
        description: Status code providing additional information.
      message:
        type: string
        description: The message giving detailed information about the status code.
  Term:
    type: string
    description: Represent benefit term in ISO 8601 format.
    enum:
    - P1Y
    - P3Y
    - P5Y
    x-ms-enum:
      name: Term
      modelAsString: true
  CustomerId:
    type: string
    readOnly: true
    description: Fully-qualified identifier of the customer where the savings plan is applied. Present only for Partner-led customers.
  AppliedScopeType:
    type: string
    description: Type of the Applied Scope.
    enum:
    - Single
    - Shared
    - ManagementGroup
    x-ms-enum:
      name: AppliedScopeType
      modelAsString: true
  SavingsPlanUpdateValidateRequest:
    type: object
    properties:
      benefits:
        type: array
        items:
          $ref: '#/definitions/SavingsPlanUpdateRequestProperties'
        x-ms-identifiers: []
  SavingsPlanValidResponseProperty:
    type: object
    description: Benefit scope response property
    properties:
      valid:
        type: boolean
        description: Indicates if the provided input was valid
      reasonCode:
        type: string
        description: Failure reason code if the provided input was invalid
      reason:
        type: string
        description: Failure reason if the provided input was invalid
  Commitment:
    type: object
    description: Commitment towards the benefit.
    allOf:
    - $ref: '#/definitions/Price'
    properties:
      grain:
        type: string
        description: Commitment grain.
        enum:
        - Hourly
        x-ms-enum:
          name: CommitmentGrain
          modelAsString: true
  BillingProfileId:
    type: string
    readOnly: true
    description: Fully-qualified identifier of the billing profile where the savings plan is applied. Present only for Field-led or Customer-led customers.
  SavingsPlanSummary:
    type: object
    description: Savings plans list summary
    properties:
      name:
        description: This property has value 'summary'
        readOnly: true
        type: string
      value:
        $ref: '#/definitions/SavingsPlanSummaryCount'
  ManagementGroupId:
    type: string
    description: Fully-qualified identifier of the management group where the benefit must be applied.
  TenantId:
    type: string
    description: Tenant ID where the benefit is applied.
  SavingsPlanValidateResponse:
    type: object
    properties:
      benefits:
        type: array
        items:
          $ref: '#/definitions/SavingsPlanValidResponseProperty'
        x-ms-identifiers: []
      nextLink:
        type: string
        description: Url to get the next page.
  BillingPlan:
    type: string
    description: Represents the billing plan in ISO 8601 format. Required only for monthly billing plans.
    enum:
    - P1M
    x-ms-enum:
      name: BillingPlan
      modelAsString: true
  SavingsPlanOrderAliasModel:
    type: object
    description: Savings plan order alias
    required:
    - sku
    allOf:
    - $ref: ../../../../../common-types/resource-management/v3/types.json#/definitions/Resource
    properties:
      sku:
        description: Savings plan SKU
        $ref: '#/definitions/Sku'
      kind:
        type: string
        description: Resource provider kind
      properties:
        description: Savings plan order alias properties
        x-ms-client-flatten: true
        $ref: '#/definitions/SavingsPlanOrderAliasProperties'
    x-ms-azure-resource: true
  RenewProperties:
    type: object
    properties:
      purchaseProperties:
        $ref: '#/definitions/PurchaseRequest'
  SubscriptionId:
    type: string
    description: Fully-qualified identifier of the subscription.
  PurchaseRequest:
    type: object
    properties:
      sku:
        $ref: '#/definitions/Sku'
      properties:
        x-ms-client-flatten: true
        $ref: '#/definitions/PurchaseRequestProperties'
  PurchaseDateTime:
    type: string
    description: Date time when the savings plan was purchased
    readOnly: true
    format: date-time
  SavingsPlanPurchaseValidateRequest:
    type: object
    properties:
      benefits:
        type: array
        items:
          $ref: '#/definitions/SavingsPlanOrderAliasModel'
  ExpiryDateTime:
    type: string
    description: Expiry date time
    readOnly: true
    format: date-time
  ResourceGroupId:
    type: string
    description: Fully-qualified identifier of the resource group.
  AppliedScopeProperties:
    type: object
    description: Properties specific to applied scope type. Not required if not applicable.
    properties:
      tenantId:
        $ref: '#/definitions/TenantId'
      managementGroupId:
        $ref: '#/definitions/ManagementGroupId'
      subscriptionId:
        $ref: '#/definitions/SubscriptionId'
      resourceGroupId:
        $ref: '#/definitions/ResourceGroupId'
      displayName:
        type: string
        description: Display name
  Utilization:
    readOnly: true
    type: object
    description: Savings plan utilization
    properties:
      trend:
        description: The number of days trend for a savings plan
        readOnly: true
        type: string
      aggregates:
        description: The array of aggregates of a savings plan's utilization
        type: array
        items:
          $ref: '#/definitions/UtilizationAggregates'
        x-ms-identifiers: []
  BillingAccountId:
    type: string
    readOnly: true
    description: Fully-qualified identifier of the billing account where the savings plan is applied. Present only for Enterprise Agreement customers.
  SavingsPlanModelListResult:
    type: object
    properties:
      value:
        description: The list of savings plans.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/SavingsPlanModel'
      nextLink:
        type: string
        readOnly: true
        description: Url to get the next page.
      additionalProperties:
        description: The roll out count summary of the savings plans
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/SavingsPlanSummary'
        x-ms-identifiers: []
  BillingScopeId:
    type: string
    description: Subscription that will be charged for purchasing the benefit
  ProvisioningState:
    type: string
    description: Provisioning state
    readOnly: true
    enum:
    - Creating
    - PendingBilling
    - ConfirmedBilling
    - Created
    - Succeeded
    - Cancelled
    - Expired
    - Failed
    x-ms-enum:
      name: ProvisioningState
      modelAsString: true
  Renew:
    type: boolean
    default: false
    description: Setting this to true will automatically purchase a new benefit on the expiration date time.
  SavingsPlanSummaryCount:
    description: The roll up count summary of savings plans in each state
    type: object
    properties:
      succeededCount:
        description: The number of savings plans in Succeeded state
        readOnly: true
        type: number
      failedCount:
        description: The number of savings plans in Failed state
        readOnly: true
        type: number
      expiringCount:
        description: The number of savings plans in Expiring state
        readOnly: true
        type: number
      expiredCount:
        description: The number of savings plans in Expired state
        readOnly: true
        type: number
      pendingCount:
        description: The number of savings plans in Pending state
        readOnly: true
        type: number
      cancelledCount:
        description: The number of savings plans in Cancelled state
        readOnly: true
        type: number
      processingCount:
        description: The number of savings plans in Processing state
        readOnly: true
        type: number
      noBenefitCount:
        description: The number of savings plans in No Benefit state
        readOnly: true
        type: number
      warningCount:
        description: The number of savings plans in Warning state
        readOnly: true
        type: number
  SavingsPlanModelList:
    type: object
    properties:
      value:
        type: array
        items:
          $ref: '#/definitions/SavingsPlanModel'
        x-ms-identifiers: []
      nextLink:
        type: string
        description: Url to get the next page.
  DisplayName:
    type: string
    description: Display name
  SavingsPlanUpdateRequestProperties:
    type: object
    description: Savings plan patch request
    properties:
      displayName:
        $ref: '#/definitions/DisplayName'
      appliedScopeType:
        $ref: '#/definitions/AppliedScopeType'
      appliedScopeProperties:
        $ref: '#/definitions/AppliedScopeProperties'
      renew:
        $ref: '#/definitions/Renew'
      renewProperties:
        $ref: '#/definitions/RenewProperties'
parameters:
  ApiVersionParameter:
    name: api-version
    in: query
    x-ms-parameter-location: client
    required: true
    description: The api-version to be used by the service
    type: string
  SavingsPlanOrderIdParameter:
    name: savingsPlanOrderId
    x-ms-parameter-location: method
    in: path
    required: true
    type: string
    description: Order ID of the savings plan
  ExpandParameter:
    name: $expand
    description: May be used to expand the detail information of some properties.
    in: query
    x-ms-parameter-location: client
    required: false
    type: string
  SavingsPlanIdParameter:
    name: savingsPlanId
    x-ms-parameter-location: method
    in: path
    required: true
    type: string
    description: ID of the savings plan
  SavingsPlanPurchaseValidateRequestParameter:
    name: body
    in: body
    x-ms-parameter-location: method
    required: true
    description: Request body for validating the purchase of a savings plan
    schema:
      $ref: '#/definitions/SavingsPlanPurchaseValidateRequest'
  SavingsPlanUpdateValidateRequestParameter:
    name: body
    in: body
    x-ms-parameter-location: method
    required: true
    description: Request body for validating a savings plan patch request
    schema:
      $ref: '#/definitions/SavingsPlanUpdateValidateRequest'
  SavingsPlanUpdateRequestParameter:
    name: body
    in: body
    x-ms-parameter-location: method
    required: true
    description: Request body for patching a savings plan order alias
    schema:
      $ref: '#/definitions/SavingsPlanUpdateRequest'
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'