Aghanim Players' Subscriptions API

openapi: 3.2.0
info:
  title: Aghanim Server-to-Server Players' Subscriptions API
  description: The Aghanim Server-to-Server API is designed for **backend server integrations only**.
  contact:
    name: Aghanim
    email: integration@aghanim.com
  version: 2026.07.14
servers:
- url: https://api.aghanim.com/s2s
  description: Production
tags:
- name: Players' Subscriptions
paths:
  /v1/players/{player_id}/subscriptions:
    get:
      tags:
      - Players' Subscriptions
      summary: Get Subscriptions
      description: Retrieve subscriptions for a player.
      operationId: get_player_subscriptions
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: effective
        in: query
        required: false
        schema:
          title: Effective
          description: Filter by effective status. True for effective only, False for non-effective only, None for all.
          type: boolean
        description: Filter by effective status. True for effective only, False for non-effective only, None for all.
      - name: limit
        in: query
        required: false
        schema:
          title: Limit
          description: A limit on the number of objects to be returned
          default: 10
          type: integer
        description: A limit on the number of objects to be returned
      - name: offset
        in: query
        required: false
        schema:
          title: Offset
          description: The number of objects to skip
          type: integer
        description: The number of objects to skip
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Get Player Subscriptions
                type: array
                items:
                  $ref: '#/components/schemas/aghanim__s2s__player__subscription__schemas__SubscriptionRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/players/{player_id}/subscriptions/{subscription_id}:
    delete:
      tags:
      - Players' Subscriptions
      summary: Cancel Player Subscriptions
      description: Cancel a players's subscription.
      operationId: cancel_player_subscriptions
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: subscription_id
        in: path
        required: true
        schema:
          title: Subscription Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/players/{player_id}/subscriptions/{subscription_id}/reactivate:
    post:
      tags:
      - Players' Subscriptions
      summary: Reactivate Player Subscription
      description: 'Reactivate a player''s subscription.


        Depending on the current subscription state:

        - reactivates the existing subscription if it is not in a terminal state,

        - creates a new subscription if the previous one has ended,

        - or does nothing if the subscription is already active.'
      operationId: reactivate_player_subscription
      security:
      - HTTPBearer: []
      parameters:
      - name: player_id
        in: path
        required: true
        schema:
          title: Player Id
          type: string
      - name: subscription_id
        in: path
        required: true
        schema:
          title: Subscription Id
          type: string
      responses:
        '200':
          description: Subscription reactivated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivatedSubscription'
        '201':
          description: New subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReactivatedSubscription'
        '204':
          description: Subscription already active.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ReactivatedSubscription:
      properties:
        id:
          type: string
          title: Id
          description: Resulting subscription ID.
        status:
          description: Resulting subscription status.
          $ref: '#/components/schemas/SubscriptionStatus'
      type: object
      required:
      - id
      - status
      title: ReactivatedSubscription
    Offer:
      properties:
        key:
          type: string
          title: Key
          description: Offer unique key.
        name:
          type: string
          title: Name
          description: Offer display name.
      type: object
      required:
      - key
      title: Offer
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    aghanim__s2s__player__subscription__schemas__SubscriptionRead:
      properties:
        sku:
          type: string
          title: SKU
          description: Subscription unique SKU.
        id:
          type: string
          title: Id
          description: Unique identifier for this subscription instance. Use this ID to track and manage the subscription throughout its lifecycle.
        name:
          type: string
          title: Name
          description: Subscription display name.
        order_id:
          type: string
          title: Order Id
          description: Order ID where the subscription was originally activated. Use this to correlate with order webhooks.
        status:
          description: Subscription status.
          $ref: '#/components/schemas/SubscriptionStatus'
        created_at:
          type: integer
          title: Created At
          description: Subscription creation date in Unix epoch time (seconds).
        updated_at:
          type: integer
          title: Updated At
          description: Subscription last update date in Unix epoch time (seconds). Null if the subscription has not been updated.
        effective_until:
          type: integer
          title: Effective Until
          description: The date until which the subscription is effective in Unix epoch time (seconds) representing when the subscription benefits should remain accessible.
        metadata:
          type: object
          title: Metadata
          description: Custom key-value pairs attached to the subscription. Null if no metadata is set.
        plan:
          title: Plan
          description: Selected plan for the subscription.
          $ref: '#/components/schemas/Plan'
      type: object
      required:
      - sku
      - id
      - name
      - order_id
      - status
      - created_at
      - plan
      title: SubscriptionRead
    SubscriptionStatus:
      type: string
      enum:
      - trial
      - active
      - grace
      - canceled
      - locked
      - ended
      - expired
      - paused
      - pending
      title: SubscriptionStatus
      description: An enumeration.
    Plan:
      properties:
        key:
          type: string
          title: Key
          description: Plan unique key within subscription.
        name:
          type: string
          title: Name
          description: Plan display name.
        offer:
          title: Offer
          description: Offer applied to the plan. Null if no offer is applied.
          $ref: '#/components/schemas/Offer'
      type: object
      required:
      - key
      - name
      title: Plan
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      description: Refer to the [Authentication](https://docs.aghanim.com/api-reference/) section for instructions on obtaining an API key and use it as the `Bearer` token.