SAP BRIM (Billing and Revenue Innovation Management) Subscriptions API

openapi: 3.2.0
info:
  title: SAP BRIM (Billing and Revenue Innovation Management) SAP…
  description: API for managing subscription lifecycle within the SAP BRIM (Billing and Revenue Innovation Management) suite. Supports creation, modification, renewal, suspension, and cancellation of subscriptions across various billing frequencies and subscription models including recurring, usage-based, and hybrid subscriptions.
  version: 1.0.0
  contact:
    name: SAP Support
    email: support@sap.com
    url: https://support.sap.com
  license:
    name: SAP Developer License
    url: https://www.sap.com/about/legal/terms-of-use.html
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
servers:
- url: https://api.sap.com/subscription-billing/v1
  description: SAP API Business Hub - Production
- url: https://sandbox.api.sap.com/subscription-billing/v1
  description: SAP API Business Hub - Sandbox
security:
- OAuth2:
  - read
  - write
- ApiKeyAuth: []
tags:
- name: Subscriptions
  description: Subscription lifecycle management operations
paths:
  /subscriptions:
    get:
      operationId: listSubscriptions
      summary: SAP BRIM (Billing and Revenue Innovation Management) List subscriptions
      description: Retrieves a paginated list of subscriptions. Supports filtering by customer, status, plan, and date range.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Limit'
      - name: customerId
        in: query
        description: Filter by customer identifier
        schema:
          type: string
      - name: status
        in: query
        description: Filter by subscription status
        schema:
          type: string
          enum:
          - ACTIVE
          - SUSPENDED
          - CANCELLED
          - EXPIRED
          - PENDING
          - TRIAL
      - name: planId
        in: query
        description: Filter by subscription plan
        schema:
          type: string
      - name: createdFrom
        in: query
        schema:
          type: string
          format: date
      - name: createdTo
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Subscription'
                  totalCount:
                    type: integer
                  offset:
                    type: integer
                  limit:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Create a subscription
      description: Creates a new subscription for a customer. Associates the subscription with a plan, sets the billing frequency, and initializes the subscription lifecycle.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionCreate'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Conflict with existing subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}:
    get:
      operationId: getSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Get a subscription
      description: Retrieves detailed information about a specific subscription, including its items, billing history, and current status.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    patch:
      operationId: updateSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Update a subscription
      description: Updates an existing subscription. Supports modifying billing details, metadata, and other configurable attributes. Plan changes should use the dedicated change-plan endpoint.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdate'
      responses:
        '200':
          description: Subscription updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      operationId: deleteSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Delete a subscription
      description: Permanently removes a subscription. Only PENDING or CANCELLED subscriptions can be deleted. Active subscriptions must be cancelled first.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '204':
          description: Subscription deleted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}/activate:
    post:
      operationId: activateSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Activate a subscription
      description: Activates a PENDING or SUSPENDED subscription, starting or resuming the billing cycle.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                effectiveDate:
                  type: string
                  format: date
                  description: Date when activation takes effect (defaults to today)
      responses:
        '200':
          description: Subscription activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}/suspend:
    post:
      operationId: suspendSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Suspend a subscription
      description: Temporarily suspends an active subscription. Billing is paused during the suspension period. The subscription can be reactivated later.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reason
              properties:
                reason:
                  type: string
                  description: Reason for suspension
                effectiveDate:
                  type: string
                  format: date
                resumeDate:
                  type: string
                  format: date
                  description: Scheduled date to automatically resume
      responses:
        '200':
          description: Subscription suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}/cancel:
    post:
      operationId: cancelSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Cancel a subscription
      description: Cancels an active or suspended subscription. Supports immediate cancellation or end-of-term cancellation.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - reason
              - cancellationType
              properties:
                reason:
                  type: string
                cancellationType:
                  type: string
                  enum:
                  - IMMEDIATE
                  - END_OF_TERM
                  - SPECIFIC_DATE
                  description: When the cancellation takes effect
                effectiveDate:
                  type: string
                  format: date
                  description: Required when cancellationType is SPECIFIC_DATE
                refundPolicy:
                  type: string
                  enum:
                  - NO_REFUND
                  - PRORATED
                  - FULL
      responses:
        '200':
          description: Subscription cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}/renew:
    post:
      operationId: renewSubscription
      summary: SAP BRIM (Billing and Revenue Innovation Management) Renew a subscription
      description: Manually triggers the renewal of a subscription. Useful for subscriptions that do not auto-renew or for early renewal requests.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                renewalTerm:
                  type: integer
                  description: Number of billing periods for the renewal
                renewalPlanId:
                  type: string
                  description: Optional new plan for the renewal period
      responses:
        '200':
          description: Subscription renewed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /subscriptions/{subscriptionId}/change-plan:
    post:
      operationId: changeSubscriptionPlan
      summary: SAP BRIM (Billing and Revenue Innovation Management) Change subscription plan
      description: Changes the plan associated with a subscription. Handles prorating, upgrade/downgrade logic, and billing adjustments automatically.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - newPlanId
              properties:
                newPlanId:
                  type: string
                effectiveDate:
                  type: string
                  format: date
                prorateCharges:
                  type: boolean
                  default: true
                  description: Whether to prorate charges for the current period
      responses:
        '200':
          description: Plan changed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    Unauthorized:
      description: Authentication required or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    SubscriptionItem:
      type: object
      properties:
        itemId:
          type: string
        productId:
          type: string
        productName:
          type: string
        description:
          type: string
        quantity:
          type: integer
          minimum: 1
        unitPrice:
          $ref: '#/components/schemas/MonetaryAmount'
        totalPrice:
          $ref: '#/components/schemas/MonetaryAmount'
        billingType:
          type: string
          enum:
          - RECURRING
          - ONE_TIME
          - USAGE_BASED
        includedUnits:
          type: integer
          description: Number of units included in the base price
        overageRate:
          type: number
          format: double
          description: Rate per unit above the included quantity
        metadata:
          type: object
          additionalProperties:
            type: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            target:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
    SubscriptionCreate:
      type: object
      required:
      - customerId
      - planId
      properties:
        customerId:
          type: string
        planId:
          type: string
        billingFrequency:
          type: string
          enum:
          - MONTHLY
          - QUARTERLY
          - SEMI_ANNUAL
          - ANNUAL
          - CUSTOM
        startDate:
          type: string
          format: date
          description: Defaults to today if not specified
        endDate:
          type: string
          format: date
        trialPeriodDays:
          type: integer
          minimum: 0
          description: Number of trial days before billing begins
        autoRenew:
          type: boolean
          default: true
        quantity:
          type: integer
          minimum: 1
          default: 1
        paymentMethod:
          type: string
        couponCode:
          type: string
          description: Promotional coupon to apply
        metadata:
          type: object
          additionalProperties:
            type: string
    MonetaryAmount:
      type: object
      required:
      - value
      - currency
      properties:
        value:
          type: number
          format: double
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: ISO 4217 currency code
    SubscriptionUpdate:
      type: object
      properties:
        autoRenew:
          type: boolean
        paymentMethod:
          type: string
        endDate:
          type: string
          format: date
        metadata:
          type: object
          additionalProperties:
            type: string
    Subscription:
      type: object
      properties:
        subscriptionId:
          type: string
          format: uuid
        customerId:
          type: string
        planId:
          type: string
        planName:
          type: string
        status:
          type: string
          enum:
          - ACTIVE
          - SUSPENDED
          - CANCELLED
          - EXPIRED
          - PENDING
          - TRIAL
        billingFrequency:
          type: string
          enum:
          - MONTHLY
          - QUARTERLY
          - SEMI_ANNUAL
          - ANNUAL
          - CUSTOM
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        trialEndDate:
          type: string
          format: date
        currentPeriodStart:
          type: string
          format: date
        currentPeriodEnd:
          type: string
          format: date
        nextBillingDate:
          type: string
          format: date
        autoRenew:
          type: boolean
        renewalCount:
          type: integer
          description: Number of times this subscription has been renewed
        cancellationDate:
          type: string
          format: date
        cancellationReason:
          type: string
        recurringCharge:
          $ref: '#/components/schemas/MonetaryAmount'
        items:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionItem'
        paymentMethod:
          type: string
          description: Identifier of the payment method on file
        metadata:
          type: object
          additionalProperties:
            type: string
        createdAt:
          type: string
          format: date-time
        modifiedAt:
          type: string
          format: date-time
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: Unique identifier of the subscription
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      description: Maximum number of items to return
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    Offset:
      name: offset
      in: query
      description: Number of items to skip for pagination
      schema:
        type: integer
        default: 0
        minimum: 0
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.sap.com/oauth/token
          scopes:
            read: Read access to subscription resources
            write: Write access to subscription resources
    ApiKeyAuth:
      type: apiKey
      in: header
      name: APIKey