openapi: 3.2.0
info:
  description: Use the Usage Proxy API to list Oracle Support Rewards, view related detailed usage information, and manage users who redeem rewards. For more information, see [Oracle Support Rewards Overview](/iaas/Content/Billing/Concepts/supportrewardsoverview.htm).
  title: Usage Proxy Rewards API
  version: '20190111'
  x-provenance:
    method: harvested
    first_party: true
    publisher: Oracle
    source: https://docs.oracle.com/en-us/iaas/api/specs/923c4c9e7faf08854042f276c1ca058bf5c0d7901ddbf9c52717a1816a0e8d82.yaml
    harvested: '2026-08-04'
    note: Published by Oracle as the contract for the Usage Proxy API OCI service and stored verbatim; API Evangelist added only this provenance block.
  x-evidence:
  - url: https://docs.oracle.com/en-us/iaas/api/specs/index.json
    what: Oracle's own index of every OCI service specification
  - url: https://docs.oracle.com/en-us/iaas/api/specs/923c4c9e7faf08854042f276c1ca058bf5c0d7901ddbf9c52717a1816a0e8d82.yaml
    what: the harvested document for Usage Proxy API
servers:
- url: https://127.0.0.1/20190111
tags:
- name: rewards
paths:
  /subscriptions/{subscriptionId}/products:
    get:
      description: 'Provides product information that is specific to a reward usage period and its usage details.

        '
      operationId: ListProducts
      parameters:
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/UsagePeriodKeyQueryParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/PaginationTokenParam'
      - $ref: '#/components/parameters/PaginationLimitParam'
      - $ref: '#/components/parameters/SortOrderParam'
      - $ref: '#/components/parameters/SortByParam'
      - $ref: '#/components/parameters/ProductTypeParam'
      responses:
        200:
          description: 'The rewards product information for the specific usage period.

            '
          headers:
            opc-next-page:
              description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

                then a partial list might have been returned. Include this value as the `page` parameter for the

                subsequent GET request to get the next batch of items.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductCollection'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Returns the list of products and their corresponding product usage information for a usage period ID.
      tags:
      - rewards
      x-related-resource: '#/definitions/ProductSummary'
  /subscriptions/{subscriptionId}/redeemableUsers:
    delete:
      description: 'Deletes the list of users by email ID that can redeem rewards, for a particular subscription ID.

        '
      operationId: DeleteRedeemableUser
      parameters:
      - $ref: '#/components/parameters/EmailIdQueryParam'
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/IfMatchHeader'
      responses:
        204:
          description: 'The email IDs have been successfully deleted from the list of users that can redeem rewards.

            '
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: delete a list of email id from redeemable email ids list
      tags:
      - rewards
      x-related-resource: '#/definitions/RedeemableUser'
    get:
      description: 'Provides the summarized list of users that can redeem rewards for the given subscription ID.

        '
      operationId: ListRedeemableUsers
      parameters:
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/PaginationTokenParam'
      - $ref: '#/components/parameters/PaginationLimitParam'
      - $ref: '#/components/parameters/SortOrderParam'
      - $ref: '#/components/parameters/SortByParam'
      responses:
        200:
          description: The summarized list of users that can redeem rewards.
          headers:
            opc-next-page:
              description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

                then a partial list might have been returned. Include this value as the `page` parameter for the

                subsequent GET request to get the next batch of items.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemableUserCollection'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - rewards
      x-related-resource: '#/definitions/RedeemableUserSummary'
    post:
      description: 'Adds the summarized list of users that can redeem rewards for a given subscription ID.

        '
      operationId: CreateRedeemableUser
      parameters:
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/UserIdQueryParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/IfMatchHeader'
      - $ref: '#/components/parameters/RetryTokenHeader'
      responses:
        200:
          description: The added summarized list of users that can redeem rewards.
          headers:
            etag:
              description: For optimistic concurrency control. See `if-match`.
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemableUserCollection'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error
          headers:
            etag:
              description: For optimistic concurrency control. See `if-match`.
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Add list of redeemable user summary for a subscription Id
      tags:
      - rewards
      x-related-resource: '#/definitions/RedeemableUser'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRedeemableUserDetails'
        description: 'CreateRedeemableUserDetails information.

          '
        required: true
  /subscriptions/{subscriptionId}/redemptions:
    get:
      description: 'Returns the list of redemptions for the subscription ID.

        '
      operationId: ListRedemptions
      parameters:
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/TimeRedeemedGreaterThanOrEqualToQueryParam'
      - $ref: '#/components/parameters/TimeRedeemedLessThanQueryParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      - $ref: '#/components/parameters/PaginationTokenParam'
      - $ref: '#/components/parameters/PaginationLimitParam'
      - $ref: '#/components/parameters/SortOrderParam'
      - $ref: '#/components/parameters/SortByListRedemptions'
      responses:
        200:
          description: 'The detailed redemption summary list.

            '
          headers:
            opc-next-page:
              description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

                then a partial list might have been returned. Include this value as the `page` parameter for the

                subsequent GET request to get the next batch of items.

                '
              schema:
                type: string
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionCollection'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact

                Oracle about a particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Returns list of redemption for the subscription Id.
      tags:
      - rewards
      x-related-resource: '#/definitions/RedemptionSummary'
  /subscriptions/{subscriptionId}/rewards:
    get:
      description: 'Returns the list of rewards for a subscription ID.

        '
      operationId: ListRewards
      parameters:
      - $ref: '#/components/parameters/TenancyIdQueryParam'
      - $ref: '#/components/parameters/SubscriptionIdPathParam'
      - $ref: '#/components/parameters/RequestIdHeader'
      responses:
        200:
          description: 'The detailed list of rewards information.

            '
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a

                particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardCollection'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        404:
          $ref: '#/components/responses/404'
        412:
          $ref: '#/components/responses/412'
        429:
          $ref: '#/components/responses/429'
        500:
          $ref: '#/components/responses/500'
        default:
          description: Unexpected error.
          headers:
            opc-request-id:
              description: 'Unique Oracle-assigned identifier for the request. If you need to contact Oracle about a

                particular request, please provide the request ID.

                '
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Returns list of rewards for a given subscription Id
      tags:
      - rewards
      x-related-resource: '#/definitions/MonthlyRewardSummary'
components:
  parameters:
    UsagePeriodKeyQueryParam:
      description: The SPM Identifier for the usage period.
      in: query
      name: usagePeriodKey
      required: true
      schema:
        type: string
        maxLength: 32
        minLength: 32
    SubscriptionIdPathParam:
      description: The subscription ID for which rewards information is requested for.
      in: path
      name: subscriptionId
      required: true
      schema:
        type: string
    SortOrderParam:
      description: The sort order to use, which can be ascending (ASC) or descending (DESC).
      in: query
      name: sortOrder
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
    IfMatchHeader:
      description: 'For optimistic concurrency control. In the PUT or DELETE call

        for a resource, set the `if-match` parameter to the value of the

        etag from a previous GET or POST response for that resource.

        The resource will be updated or deleted, only if the etag you

        provide matches the resource''s current etag value.

        '
      in: header
      name: if-match
      required: false
      schema:
        type: string
    EmailIdQueryParam:
      description: The email ID that needs to be deleted.
      in: query
      name: emailId
      required: true
      schema:
        type: string
    SortByParam:
      description: The field to sort by. Supports one sort order.
      in: query
      name: sortBy
      schema:
        type: string
        enum:
        - TIMECREATED
        - TIMESTART
        default: TIMECREATED
    ProductTypeParam:
      description: The field to specify the type of product.
      in: query
      name: producttype
      schema:
        type: string
        enum:
        - ALL
        - ELIGIBLE
        - INELIGIBLE
        default: ALL
    PaginationLimitParam:
      description: The maximum number of items to return in the paginated response.
      in: query
      name: limit
      schema:
        type: integer
        default: 50
        maximum: 1000
        minimum: 1
    RetryTokenHeader:
      description: 'A token that uniquely identifies a request so it can be retried in case of a timeout or

        server error, without risk of executing that same action again. Retry tokens expire after 24

        hours, but can be invalidated before then due to conflicting operations. For example, if a resource

        has been deleted and purged from the system, then a retry of the original creation request

        might be rejected.

        '
      in: header
      name: opc-retry-token
      required: false
      schema:
        type: string
        maxLength: 64
        minLength: 1
    TimeRedeemedGreaterThanOrEqualToQueryParam:
      description: The starting redeemed date filter for the redemption history.
      in: query
      name: timeRedeemedGreaterThanOrEqualTo
      required: false
      x-default-description: 'null'
      schema:
        type: string
        format: date-time
    TimeRedeemedLessThanQueryParam:
      description: The ending redeemed date filter for the redemption history.
      in: query
      name: timeRedeemedLessThan
      required: false
      x-default-description: 'null'
      schema:
        type: string
        format: date-time
    TenancyIdQueryParam:
      description: The OCID of the tenancy.
      in: query
      name: tenancyId
      required: true
      schema:
        type: string
    SortByListRedemptions:
      description: The field to be used only for the list redemptions API. Supports one sort order.
      in: query
      name: sortBy
      schema:
        type: string
        enum:
        - TIMEREDEEMED
        default: TIMEREDEEMED
    PaginationTokenParam:
      description: The value of the 'opc-next-page' response header from the previous call.
      in: query
      name: page
      x-default-description: 'null'
      schema:
        type: string
        maxLength: 512
        minLength: 1
    RequestIdHeader:
      description: Unique, Oracle-assigned identifier for the request. If you need to contact Oracle about a particular request, please provide the request ID.
      in: header
      name: opc-request-id
      schema:
        type: string
    UserIdQueryParam:
      description: The user ID of the person to send a copy of an email.
      in: query
      name: userId
      x-default-description: 'null'
      schema:
        type: string
  schemas:
    RewardCollection:
      description: The response object for the ListRewards API call. Provides information about the subscription rewards.
      properties:
        items:
          description: The monthly summary of rewards.
          items:
            $ref: '#/components/schemas/MonthlyRewardSummary'
          type: array
        summary:
          $ref: '#/components/schemas/RewardDetails'
      required:
      - summary
      type: object
    Error:
      description: Error object model.
      properties:
        code:
          description: A short error code that defines the error, meant for programmatic parsing.
          type: string
        message:
          description: A human-readable error string.
          type: string
      required:
      - code
      - message
      type: object
    CreateRedeemableUserDetails:
      description: The list of new users to be added to the list of users that can redeem rewards.
      properties:
        items:
          description: The list of new users to be added to the list of users that can redeem rewards.
          items:
            $ref: '#/components/schemas/RedeemableUser'
          type: array
      type: object
    RewardDetails:
      description: The overall monthly reward summary.
      properties:
        currency:
          description: The currency unit for the reward amount.
          type: string
        redemptionCode:
          description: The redemption code used in the Billing Center during the reward redemption process.
          type: string
        rewardsRate:
          description: The current Rewards percentage in decimal format.
          format: double
          type: number
        subscriptionId:
          description: The entitlement ID from MQS, which is the same as the subcription ID.
          type: string
        tenancyId:
          description: The OCID of the target tenancy.
          type: string
        totalRewardsAvailable:
          description: The total number of available rewards for a given subscription ID.
          format: float
          type: number
      type: object
    ProductCollection:
      description: A product list.
      properties:
        items:
          description: The list of product rewards summaries.
          items:
            $ref: '#/components/schemas/ProductSummary'
          type: array
      required:
      - items
    RedeemableUser:
      description: The summary of a user that can redeem rewards.
      properties:
        emailId:
          description: The email ID for a user that can redeem rewards.
          type: string
        firstName:
          description: The first name of the user that can redeem rewards.
          type: string
        lastName:
          description: The last name of the user that can redeem rewards.
          type: string
      required:
      - emailId
      type: object
    ProductSummary:
      description: Provides details about product rewards and the usage amount.
      properties:
        earnedRewards:
          description: The earned rewards for the product.
          format: float
          type: number
        isEligibleToEarnRewards:
          description: The boolean parameter to indicate if the product is eligible to earn rewards.
          type: boolean
        productName:
          description: The rate card product name.
          type: string
        productNumber:
          description: The rate card product number.
          type: string
        usageAmount:
          description: The rate card product usage amount.
          format: double
          type: number
    MonthlyRewardSummary:
      description: Object describing the monthly rewards summary for the requested subscription ID.
      properties:
        availableRewards:
          description: The number of rewards available for a specific usage period.
          format: float
          type: number
        earnedRewards:
          description: The number of rewards earned for the specific usage period.
          format: float
          type: number
        eligibleUsageAmount:
          description: 'The eligible usage amount for the usage period.

            '
          format: double
          type: number
        ineligibleUsageAmount:
          description: 'The ineligible usage amount for the usage period.

            '
          format: double
          type: number
        isManual:
          description: The boolean parameter to indicate whether or not the available rewards are manually posted.
          type: boolean
        redeemedRewards:
          description: The number of rewards redeemed for a specific month.
          format: float
          type: number
        timeRewardsEarned:
          description: 'The date and time when rewards accrue.

            '
          format: date-time
          type: string
        timeRewardsExpired:
          description: The date and time when rewards expire.
          format: date-time
          type: string
        timeUsageEnded:
          description: 'The end date and time for the usage period.

            '
          format: date-time
          type: string
        timeUsageStarted:
          description: 'The start date and time for the usage period.

            '
          format: date-time
          type: string
        usageAmount:
          description: 'The usage amount for the usage period.

            '
          format: double
          type: number
        usagePeriodKey:
          description: 'The usage period ID.

            '
          type: string
      type: object
    RedeemableUserCollection:
      description: The summarized list of users that can redeem rewards.
      properties:
        items:
          description: The summarized list of users that can redeem rewards.
          items:
            $ref: '#/components/schemas/RedeemableUserSummary'
          type: array
      required:
      - items
    RedemptionSummary:
      description: The redemption summary for the requested subscription ID and date range.
      properties:
        baseRewards:
          description: The redeemed rewards in the base/subscription currency.
          example: 250.0
          format: float
          type: number
        fxRate:
          description: The exchange rate between the invoice currency and subscription currency.
          example: 1.732
          format: double
          type: number
        invoiceCurrency:
          description: The currency associated with the invoice.
          example: USD
          type: string
        invoiceNumber:
          description: The invoice number against the redemption.
          example: '98647595'
          format: integer
          type: string
        invoiceTotalAmount:
          description: The invoice total amount of the given redemption.
          example: 250.0
          format: double
          type: number
        redeemedRewards:
          description: The redeemed rewards in the invoice currency.
          example: 250.0
          format: float
          type: number
        redemptionCode:
          description: The redemption code used in the Billing Center during the reward redemption process.
          example: wertyuio-12345678-12345678-1234589
          type: string
        redemptionEmail:
          description: The redemption email ID.
          example: test@test.com
          type: string
        timeInvoiced:
          description: The invoice date.
          example: '2007-12-03'
          format: date-time
          type: string
        timeRedeemed:
          description: The redemption date.
          example: '2007-12-03T10:15:30+01:00'
          format: date-time
          type: string
      type: object
    RedeemableUserSummary:
      description: User summary that can redeem rewards.
      properties:
        emailId:
          description: The email ID of the user that can redeem rewards.
          type: string
        firstName:
          description: The first name of the user that can redeem rewards.
          type: string
        lastName:
          description: The last name of the user that can redeem rewards.
          type: string
    RedemptionCollection:
      description: The redemption summary list for the requested subscription ID and date range.
      properties:
        items:
          description: The redemption summary list.
          items:
            $ref: '#/components/schemas/RedemptionSummary'
          type: array
      required:
      - items
x-anchors:
  x-headers:
    opc-next-page:
      description: 'For pagination of a list of items. When paging through a list, if this header appears in the response,

        then a partial list might have been returned. Include this value as the `page` parameter for the

        subsequent GET request to get the next batch of items.

        '
      type: string
    opc-request-id:
      description: 'Unique Oracle-assigned identifier for the request. If you need to contact

        Oracle about a particular request, please provide the request ID.

        '
      type: string
x-oracle-package: com.oracle.pic.usage