openapi: 3.0.3
info:
  title: Roku External Control Protocol (ECP) Apps Subscription API
  version: '1.0'
  description: 'The External Control Protocol (ECP) is an HTTP-based API exposed on port 8060 of every Roku

    streaming device on the local network. It enables third-party applications, mobile remote-control

    apps, automated testing systems, and home-automation hubs to discover Roku devices via SSDP,

    inject simulated remote-control key presses, launch installed apps with deep-link parameters,

    query device state, and retrieve diagnostic information.


    The protocol is plain HTTP/1.1 (no TLS) and is intended for trusted local-network use only.

    Most control operations require the user to enable "Control by mobile apps" on the device.

    Additional diagnostic endpoints (chanperf, sgnodes, registry, etc.) are gated behind Roku

    Developer Mode.

    '
  contact:
    name: Roku Developer Program
    url: https://developer.roku.com
  x-generated-from: documentation
  x-source-url: https://developer.roku.com/docs/developer-program/dev-tools/external-control-api.md
servers:
- url: http://{rokuDeviceIp}:8060
  description: A Roku device on the local network
  variables:
    rokuDeviceIp:
      default: 192.168.1.100
      description: The IPv4 address of the Roku device, discovered via SSDP
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:
    Error:
      type: object
      properties:
        status:
          type: string
        errorCode:
          type: integer
        errorMessage:
          type: string
    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
    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'