Roku Subscription API

openapi: 3.2.0
info:
  title: Roku Pay Web Services Subscription API
  version: '1.0'
  description: 'Roku Pay Web Services provide server-to-server APIs for billing, subscription management,

    transaction validation, and entitlement checks for monetized Roku channels. Use these endpoints

    to verify that a Roku user holds a valid entitlement to your content, to issue refunds, to update

    billing cycles, and to grant service credits. All endpoints require a Roku-issued Partner API

    Key.


    Roku Pay handles payment processing, subscription state, and tax calculation on behalf of the

    publisher; channels query these endpoints from their authentication backends rather than from

    BrightScript directly.

    '
  contact:
    name: Roku Pay Support
    url: https://developer.roku.com/docs/developer-program/roku-pay/overview.md
  x-generated-from: documentation
  x-source-url: https://developer.roku.com/dev/docs/roku-web-service
servers:
- url: https://apipub.roku.com/listen/transaction-service.svc
  description: Roku Pay production transaction service
security:
- PartnerAPIKey: []
tags:
- name: Subscription
  description: Subscription lifecycle management
paths:
  /cancel-subscription:
    post:
      operationId: cancelSubscription
      summary: Roku Cancel Subscription
      description: Terminates a Roku Pay subscription. After cancellation the entitlement remains active until the end of the current billing period.
      tags:
      - Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSubscriptionRequest'
      responses:
        '200':
          description: Cancellation status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResult'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /refund-subscription:
    post:
      operationId: refundSubscription
      summary: Roku Refund Subscription
      description: Issues a partial or full refund against a Roku Pay subscription.
      tags:
      - Subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundSubscriptionRequest'
      responses:
        '200':
          description: Refund result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResult'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    RefundSubscriptionRequest:
      type: object
      required:
      - partnerAPIKey
      - rokuCustomerId
      - transactionId
      x-schema-source: documentation
      properties:
        partnerAPIKey:
          type: string
        rokuCustomerId:
          type: string
        transactionId:
          type: string
        refundAmount:
          type: number
          format: float
          description: If omitted, a full refund is issued.
        currency:
          type: string
        reason:
          type: string
    Error:
      type: object
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          type: string
    CancelSubscriptionRequest:
      type: object
      required:
      - partnerAPIKey
      - rokuCustomerId
      - productCode
      x-schema-source: documentation
      properties:
        partnerAPIKey:
          type: string
        rokuCustomerId:
          type: string
        productCode:
          type: string
        cancellationDate:
          type: string
          format: date-time
        reason:
          type: string
    SubscriptionResult:
      type: object
      x-schema-source: documentation
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          type: string
        rokuCustomerId:
          type: string
        productCode:
          type: string
        effectiveDate:
          type: string
          format: date-time
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    PartnerAPIKey:
      type: apiKey
      in: query
      name: partnerAPIKey
      description: 'Roku-issued Partner API Key. For GET endpoints the key is included in the URL path; for

        POST endpoints it is included in the request body. Channels obtain this key from the Roku

        Developer Dashboard.

        '