openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Coupons API
  description: "The Aghanim Server-to-Server API is designed for **backend server integrations only**. Use this API when you need to automate game hub updates from your server-side applications.\n\n\n## OpenAPI Specification\n\nYou can download the [OpenAPI](https://www.openapis.org/) specification for this API at the following link:\n[docs.aghanim.com/openapi.json](https://docs.aghanim.com/openapi.json).\n\n## Changelog\n\nSee the [S2S API Changelog](https://docs.aghanim.com/s2s-api/changelog/) for a history of changes to this API.\n\n## Authentication\n\nAghanim supports two methods of authentication: **Bearer token** and **Basic authentication**.\n\nTo authenticate, you will need your API key, which can be retrieved from\nthe Aghanim Dashboard → [**Game → Integration → API Keys**](https://dashboard.aghanim.com/go/integration/api-keys).\n\n**⚠️ Security Notice**: The S2S API key is **secret** and must be kept secure on your server. Never expose the S2S API key in client-side code, mobile apps, or any public-facing applications.\n\n### Bearer Token Authentication\n\nUse the Bearer method by including an `Authorization` header with the word `Bearer`\nfollowed by your API key. The `Authorization` header in your HTTP request should look like this: `Authorization: Bearer API_KEY`\n\n### Basic Authentication\n\nAlternatively, you can authenticate using Basic authentication. Your API key is used\nas the `username`, and the `password` should be left empty. Send an `Authorization`\nheader with the word `Basic` followed by a base64-encoded string\nin the format `API_KEY:` (note the colon at the end).\n\nThe `Authorization` header should look like this: `Authorization: Basic ZGVtbzpwQDU1dzByZA==`\n\n## Error Codes\n\nAghanim employs standard HTTP response codes to denote the success or failure of an API request.\nBelow is a table detailing error codes.\n\n| Code | Description |\n| ---- | ----------- |\n| 200  | OK          |\n| 400  | Bad request |\n| 401  | Not authenticated |\n| 403  | Not authorized |\n| 404  | Resource not found |\n| 409  | Conflict. Request conflicts with current state of resource |\n| 422  | Validation error |\n| 429  | Too many requests. Rate limit exceeded |\n| 503  | Server unavailable |\n\n### Generic error schema\n\n```json\n{\n  \"detail\": \"string\"\n}\n```\n\n### Validation error schema\n\n```json\n{\n  \"detail\": [\n    {\n      \"loc\": [\n        \"string\",\n        0\n      ],\n      \"msg\": \"string\",\n      \"type\": \"string\"\n    }\n  ]\n}\n```\n\n## Rate Limits\n\nThe Aghanim API has rate limiting in place to avoid overloading and to ensure it remains stable.\nThe allowable rate of requests is capped at 1,000 per minute for every game.\nGame developers who exceed this limit will receive a 429 error code.\n\nTo increase the rate limit, please contact us via [integration@aghanim.com](mailto:integration@aghanim.com).\n\n## Pagination\n\nIn the Aghanim API, pagination is managed through the use of the `limit` and `offset` query parameters.\nThese parameters allow to fine-tune your data retrieval requests by specifying:\n\n- `limit`: the number of records to be returned in a single request.\n- `offset`: indicates the number of records to skip from the start of the dataset.\n"
  contact:
    name: Aghanim
    email: integration@aghanim.com
  version: 2026.07.14
servers:
- url: https://api.aghanim.com/s2s
  description: Production
tags:
- name: Coupons
paths:
  /v1/coupons/user/{user_id}:
    get:
      tags:
      - Coupons
      summary: Get User Coupons
      operationId: get_user_coupons
      security:
      - HTTPBearer: []
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          title: User Id
          type: string
      - 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 User Coupons
                type: array
                items:
                  $ref: '#/components/schemas/UserCouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/coupons:
    get:
      tags:
      - Coupons
      summary: Get Coupons
      description: Returns a list of coupons.
      operationId: get_coupons
      security:
      - HTTPBearer: []
      parameters:
      - name: q
        in: query
        required: false
        schema:
          title: Q
          type: string
      - name: type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/CouponType'
      - name: category_id
        in: query
        required: false
        schema:
          title: Category Id
          type: string
      - name: generated_type
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/CouponGeneratedType'
      - 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 Coupons
                type: array
                items:
                  $ref: '#/components/schemas/CouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Coupons
      summary: Create Coupon
      description: Creates a new coupon.
      operationId: create_coupon
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Create
              $ref: '#/components/schemas/CouponCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Coupons
      summary: Bulk Update Coupon
      operationId: bulk_update_coupon
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Update
              type: array
              items:
                $ref: '#/components/schemas/CouponBulkUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Bulk Update Coupon
                type: array
                items:
                  $ref: '#/components/schemas/CouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/coupons/{coupon_id}:
    get:
      tags:
      - Coupons
      summary: Get Coupon
      description: Returns a single coupon.
      operationId: get_coupon
      security:
      - HTTPBearer: []
      parameters:
      - name: coupon_id
        in: path
        required: true
        schema:
          title: Coupon Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Coupons
      summary: Update Coupon
      description: Updates a coupon.
      operationId: update_coupon
      security:
      - HTTPBearer: []
      parameters:
      - name: coupon_id
        in: path
        required: true
        schema:
          title: Coupon Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Update
              $ref: '#/components/schemas/CouponUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Coupons
      summary: Delete Coupon
      description: Deletes a coupon.
      operationId: delete_coupon
      security:
      - HTTPBearer: []
      parameters:
      - name: coupon_id
        in: path
        required: true
        schema:
          title: Coupon Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CouponUpdate:
      properties:
        free_items:
          title: Free Items
          description: Items granted when the coupon is redeemed
          $ref: '#/components/schemas/CouponFreeItems'
        discount_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Discount Percent
          description: The discount percent for the coupon
        bonus_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Bonus Percent
          description: The bonus percent for the coupon
        bonus_fixed:
          type: integer
          minimum: 1.0
          title: Bonus Fixed
          description: The fixed bonus amount for the coupon
          nullable: true
        discount_amount_usd:
          type: integer
          minimum: 0.0
          title: Discount Amount USD
          description: The discount amount in USD for the coupon
        requirements_expression:
          title: Requirements Expression
          description: The requirement expression for the coupon
          $ref: '#/components/schemas/Expression'
        expires_at:
          type: integer
          title: Expires At
          description: The expiration date of the coupon
        applicable_item_ids:
          items:
            type: string
          type: array
          title: Applicable Item Ids
          description: The applicable item IDs
        category_id:
          type: string
          title: Category Id
          description: The coupon category ID
        min_amount:
          type: integer
          title: Min Amount
          description: Require a minimum order amount to apply the coupon
        max_redemptions:
          type: integer
          title: Max Redemptions
          description: Limit the number of times this code can be redeemed
        max_redemptions_per_user:
          type: integer
          title: Max Redemptions Per User
          description: Limit the number of times a user can redeem the coupon
        is_stackable_with_bonus_coupons:
          type: boolean
          title: Is Stackable With Bonus Coupons
          description: Allow stacking with bonus coupons
        stackable_bonus_limit_percent:
          type: integer
          title: Stackable Bonus Limit Percent
          description: Limit the bonus percent when stacking with bonus coupons
        is_stackable_with_discount_coupons:
          type: boolean
          title: Is Stackable With Discount Coupons
          description: Allow stacking with discount coupons
        stackable_discount_limit_percent:
          type: integer
          title: Stackable Discount Limit Percent
          description: Limit the discount percent when stacking with discount coupons
        store_item_discount_limit_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Store Item Discount Limit Percent
          description: Limit the combined store item and coupon discount percent
        store_item_bonus_limit_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Store Item Bonus Limit Percent
          description: Limit the combined store item and coupon bonus percent
        start_at:
          type: integer
          title: Start At
          description: The timestamp when the coupon becomes valid
        end_at:
          type: integer
          title: End At
          description: The timestamp when the coupon ceases to be valid
        player_ids:
          items:
            type: string
          type: array
          title: Player Ids
          description: The player IDs that can redeem the coupon
        exclude_player_ids:
          items:
            type: string
          type: array
          title: Exclude Player Ids
          description: The player IDs that cannot redeem the coupon
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the coupon
        creator_program:
          title: Creator Program
          description: The creator program for the coupon
          $ref: '#/components/schemas/CreatorProgramUpdate'
      type: object
      title: CouponUpdate
    CreatorProgramBase:
      properties:
        creator_id:
          type: string
          title: Creator Id
          description: The creator ID
        reward:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Reward
          description: The reward for the coupon
        verbal_terms:
          type: string
          title: Verbal Terms
          description: The verbal terms for the creator program
        message:
          type: string
          title: Message
          description: The message for the creator program
        inherits_from_tier:
          type: boolean
          title: Inherits From Tier
          description: When true, revenue share is taken from the creator's current tier instead of `reward`.
          default: false
      type: object
      required:
      - creator_id
      - reward
      - verbal_terms
      - message
      title: CreatorProgramBase
    ItemSource:
      type: string
      enum:
      - order
      - bonus
      - bundle
      - coupon
      - lootbox
      - free_item
      - liveops
      - daily_reward
      - loyalty_reward
      - progression_program
      - rolling_offer
      - pick_one_offer
      title: ItemSource
      description: An enumeration.
    CouponGeneratedType:
      type: string
      enum:
      - campaign
      - receipt
      title: CouponGeneratedType
      description: An enumeration.
    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
    ItemRarityRead:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: Name of the item rarity
        color_background_badge:
          type: string
          title: Color Background Badge
          description: Background color of the badge with this rarity
        id:
          type: string
          title: Id
      type: object
      required:
      - name
      - id
      title: ItemRarityRead
    ItemRead:
      properties:
        name:
          type: string
          title: Name
          description: The name of the item
        description:
          type: string
          title: Description
          description: The description of the item
          nullable: true
        highlights:
          title: Highlights
          description: Localized benefit descriptions shown for the item
          nullable: true
          $ref: '#/components/schemas/Highlights'
        price:
          type: integer
          title: Price
          description: The price of the item in minor [currency units](https://docs.aghanim.com/currencies/). The system will automatically adjust this to the closest available price point. If you want to set a specific price point, use `price_template_id` instead.
        price_point:
          type: integer
          maximum: 5000000.0
          exclusiveMinimum: 0.0
          title: Price Point
          description: The price point for local prices `DEPRECATED`
        price_template_id:
          type: string
          title: Price Template Id
          description: The ID of the price template
        reward_points_price:
          type: integer
          title: Reward Points Price
          description: The reward points price for local prices
        currency:
          description: The currency of the item
          $ref: '#/components/schemas/Currency'
        sku:
          type: string
          maxLength: 255
          title: SKU
          description: The SKU of the item
          unique: true
        image_url:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Image Url
          description: The URL of the image for the item
        image_url_apple:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url Apple
          description: The Apple-specific URL of the image for the item
          deprecated: true
        icon_url:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Icon Url
          description: The URL of the icon for the item
        icon_url_apple:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Icon Url Apple
          description: The Apple-specific URL of the icon for the item
          deprecated: true
        image_url_featured:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Image Url Featured
          description: The URL of the image for the item in the featured card
        image_url_featured_apple:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url Featured Apple
          description: The Apple-specific URL of the image for the item in the featured card
          deprecated: true
        background_image_url:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Background Image Url
          description: The URL of the background image for the item
        background_image_url_apple:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Background Image Url Apple
          description: The Apple-specific URL of the background image for the item
          deprecated: true
        background_image_color:
          type: string
          title: Background Image Color
          description: The color of the background image for the item
        featured_card_background_image_url:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Featured Card Background Image Url
          description: The URL of the featured card background image for the item
        featured_card_background_image_url_apple:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Featured Card Background Image Url Apple
          description: The Apple-specific URL of the featured card background image for the item
          deprecated: true
        type:
          description: The type of the item
          $ref: '#/components/schemas/ItemType'
        view_option:
          description: Controls the store appearance of the item
          default: default
          $ref: '#/components/schemas/ItemViewOption'
        quantity:
          type: integer
          maximum: 1e+18
          minimum: 1.0
          title: Quantity
          description: The quantity of the item
          default: 1
        is_stackable:
          type: boolean
          title: Is Stackable
          description: Whether the item is stackable
        is_currency:
          type: boolean
          title: Is Currency
          description: Whether the item is a currency.
        position:
          type: integer
          title: Position
          description: Position of the item in list
        categories:
          items:
            type: string
          type: array
          title: Categories
          description: The list of category IDs
        duration:
          type: integer
          title: Duration
          description: Item's in-game action in seconds
        enable_reward_points_redemption:
          type: boolean
          title: Enable Reward Points Redemption
          description: Allows using Reward Points on purchase
        nested_items:
          items:
            $ref: '#/components/schemas/NestedItem'
          type: array
          title: Nested Items
          description: The child items of the bundle
        id:
          type: string
          title: Id
          description: The unique identifier of the item
        properties:
          items:
            $ref: '#/components/schemas/ItemPropertyRelationRead'
          type: array
          title: Properties
          description: The item properties
        source:
          default: order
          $ref: '#/components/schemas/ItemSource'
        rarity_id:
          type: string
          title: Rarity Id
          description: The rarity id of the item
        item_rarity:
          $ref: '#/components/schemas/ItemRarityRead'
        discount_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Discount Percent
          description: The discount percent for the item
        bonus_percent:
          type: integer
          minimum: 0.0
          title: Bonus Percent
          description: The bonus percent for the item
        is_custom:
          type: boolean
          title: Is Custom
          default: false
        created_at:
          type: number
          title: Created At
          description: The timestamp of when the item was created
        modified_at:
          type: number
          title: Modified At
          description: The timestamp of when the item was modified
        archived_at:
          type: number
          title: Archived At
          description: The timestamp of when the item was archived
        price_minor_unit:
          type: integer
          title: Price Minor Unit
        price_decimal:
          type: number
          title: Price Decimal
        fallback_item_id:
          type: string
          title: Fallback Item Id
          description: The item that will be given as fallback if the main item can't be given to the player
        fallback_item_quantity:
          type: integer
          title: Fallback Item Quantity
          description: The quantity of the fallback item
        meta:
          type: object
          title: Meta
        model_type:
          type: string
          enum:
          - ItemRead
          title: Model Type
          default: ItemRead
        nested_items_read:
          items:
            $ref: '#/components/schemas/ItemRead'
          type: array
          title: Nested Items Read
        fallback_item:
          $ref: '#/components/schemas/ItemRead'
        comment:
          type: string
          title: Comment
          description: Internal comment for this item
        is_system:
          type: boolean
          title: Is System
          description: If true, this item will be skipped when sending webhooks
          nullable: true
      type: object
      required:
      - name
      - currency
      - sku
      - type
      - is_stackable
      - is_currency
      - id
      - created_at
      title: ItemRead
    Currency:
      type: string
      enum:
      - USD
      - EUR
      - AED
      - AFN
      - ALL
      - AMD
      - ANG
      - AOA
      - ARS
      - AUD
      - AWG
      - AZN
      - BAM
      - BBD
      - BDT
      - BGN
      - BHD
      - BIF
      - BMD
      - BND
      - BOB
      - BRL
      - BSD
      - BTN
      - BWP
      - BYN
      - BZD
      - CAD
      - CDF
      - CHF
      - CLP
      - CNY
      - COP
      - CRC
      - CUP
      - CVE
      - CZK
      - DJF
      - DKK
      - DOP
      - DZD
      - EGP
      - ERN
      - ETB
      - FJD
      - FKP
      - GBP
      - GEL
      - GHS
      - GIP
      - GMD
      - GNF
      - GTQ
      - GYD
      - HKD
      - HNL
      - HTG
      - HUF
      - IDR
      - ILS
      - INR
      - IQD
      - IRR
      - ISK
      - JMD
      - JOD
      - JPY
      - KES
      - KGS
      - KHR
      - KMF
      - KPW
      - KRW
      - KWD
      - KYD
      - KZT
      - LAK
      - LBP
      - LKR
      - LRD
      - LSL
      - LYD
      - MAD
      - MDL
      - MGA
      - MKD
      - MMK
      - MNT
      - MOP
      - MRU
      - MUR
      - MVR
      - MWK
      - MXN
      - MYR
      - MZN
      - NAD
      - NGN
      - NIO
      - NOK
      - NPR
      - NZD
      - OMR
      - PAB
      - PEN
      - PGK
      - PHP
      - PKR
      - PLN
      - PYG
      - QAR
      - RON
      - RSD
      - RUB
      - RWF
      - SAR
      - SBD
      - SCR
      - SDG
      - SEK
      - SGD
      - SHP
      - SLE
      - SOS
      - SRD
      - SSP
      - STN
      - SVC
      - SYP
      - SZL
      - THB
      - TJS
      - TMT
      - TND
      - TOP
      - TRY
      - TTD
      - TWD
      - TZS
      - UAH
      - UGX
      - UYU
      - UZS
      - VED
      - VES
      - VND
      - VUV
      - WST
      - XAF
      - XCD
      - XCG
      - XOF
      - XPF
      - YER
      - ZAR
      - ZMW
      - ZWG
      - ZWL
      - RP
      - VC
      title: Currency
    Token:
      properties:
        type:
          $ref: '#/components/schemas/TokenType'
        value:
          title: Value
      type: object
      required:
      - type
      title: Token
    ItemType:
      type: string
      enum:
      - item
      - currency
      - bundle
      - lootbox
      - subscription
      - virtual_currency
      title: ItemType
      description: An enumeration.
    CouponCreate:
      properties:
        free_items:
          title: Free Items
          description: Items granted when the coupon is redeemed
          $ref: '#/components/schemas/CouponFreeItems'
        discount_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Discount Percent
          description: The discount percent for the coupon
        bonus_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Bonus Percent
          description: The bonus percent for the coupon
        bonus_fixed:
          type: integer
          minimum: 1.0
          title: Bonus Fixed
          description: The fixed bonus amount for the coupon
          nullable: true
        discount_amount_usd:
          type: integer
          minimum: 0.0
          title: Discount Amount USD
          description: The discount amount in USD for the coupon
        requirements_expression:
          title: Requirements Expression
          description: The requirement expression for the coupon
          $ref: '#/components/schemas/Expression'
        expires_at:
          type: integer
          title: Expires At
          description: The expiration date of the coupon
        applicable_item_ids:
          items:
            type: string
          type: array
          title: Applicable Item Ids
          description: The applicable item IDs
        category_id:
          type: string
          title: Category Id
          description: The coupon category ID
        min_amount:
          type: integer
          title: Min Amount
          description: Require a minimum order amount to apply the coupon
        max_redemptions:
          type: integer
          title: Max Redemptions
          description: Limit the number of times this code can be redeemed
        max_redemptions_per_user:
          type: integer
          title: Max Redemptions Per User
          description: Limit the number of times a user can redeem the coupon
        is_stackable_with_bonus_coupons:
          type: boolean
          title: Is Stackable With Bonus Coupons
          description: Allow stacking with bonus coupons
        stackable_bonus_limit_percent:
          type: integer
          title: Stackable Bonus Limit Percent
          description: Limit the bonus percent when stacking with bonus coupons
        is_stackable_with_discount_coupons:
          type: boolean
          title: Is Stackable With Discount Coupons
          description: Allow stacking with discount coupons
        stackable_discount_limit_percent:
          type: integer
          title: Stackable Discount Limit Percent
          description: Limit the discount percent when stacking with discount coupons
        store_item_discount_limit_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Store Item Discount Limit Percent
          description: Limit the combined store item and coupon discount percent
        store_item_bonus_limit_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Store Item Bonus Limit Percent
          description: Limit the combined store item and coupon bonus percent
        start_at:
          type: integer
          title: Start At
          description: The timestamp when the coupon becomes valid
        end_at:
          type: integer
          title: End At
          description: The timestamp when the coupon ceases to be valid
        player_ids:
          items:
            type: string
          type: array
          title: Player Ids
          description: The player IDs that can redeem the coupon
        exclude_player_ids:
          items:
            type: string
          type: array
          title: Exclude Player Ids
          description: The player IDs that cannot redeem the coupon
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the coupon
        code:
          type: string
          maxLength: 20
          title: Code
          description: The code of the coupon
        type:
          description: The type of the coupon
          $ref: '#/components/schemas/CouponType'
        creator_program:
          title: Creator Program
          description: The creator program for the coupon
          $ref: '#/components/schemas/CreatorProgramBase'
      type: object
      required:
      - name
      - code
      - type
      title: CouponCreate
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Expression:
      properties:
        tokens:
          items:
            $ref: '#/components/schemas/Token'
          type: array
          title: Tokens
        variables:
          items:
            $ref: '#/components/schemas/MathExpression'
          type: array
          title: Variables
      type: object
      title: Expression
    CouponBulkUpdate:
      properties:
        id:
          type: string
          title: Id
        category_id:
          type: string
          title: Category Id
          description: The coupon category ID
      type: object
      required:
      - id
      - category_id
      title: CouponBulkUpdate
    CouponFreeItems:
      properties:
        items:
          items:
            $ref: '#/components/schemas/CouponFreeItem'
          type: array
          maxItems: 100
          title: Items
          description: Items granted when the coupon is redeemed
      type: object
      title: CouponFreeItems
      description: API wrapper for the `free_items` JSONB column, mirroring the storage shape.
    NestedItem:
      properties:
        id:
          type: string
          title: Id
        count:
          type: integer
          title: Count
        sku:
          type: string
          title: SKU
        is_featured:
          type: boolean
          title: Is Featured
        meta:
          type: object
          title: Meta
        image_url:
          type: string
          maxLength: 65536
          minLength: 1
          format: uri
          title: Image Url
        view_type:
          $ref: '#/components/schemas/NestedItemViewType'
      type: object
      title: NestedItem
    HighlightItem:
      properties:
        image_url:
          type: string
          title: Image Url
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
      type: object
      title: HighlightItem
    UserCouponRead:
      properties:
        free_items:
          title: Free Items
          description: Items granted when the coupon is redeemed
          $ref: '#/components/schemas/CouponFreeItems'
        discount_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Discount Percent
          description: The discount percent for the coupon
        bonus_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Bonus Percent
          description: The bonus percent for the coupon
        bonus_fixed:
          type: integer
          minimum: 1.0
          title: Bonus Fixed
          description: The fixed bonus amount for the coupon
          nullable: true
        discount_amount_usd:
          type: integer
          minimum: 0.0
          title: Discount Amount USD
          description: The discount amount in USD for the coupon
        requirements_expression:
          title: Requirements Expression
          description: The requirement expression for the coupon
          $ref: '#/components/schemas/Expression'
        expires_at:
          type: integer
          title: Expires At
          description: The expiration date of the coupon
        applicable_item_ids:
          items:
            type: string
          type: array
          title: Applicable Item Ids
          description: The applicable item IDs
        category_id:
          type: string
          title: Category Id
          description: The coupon category ID
        min_amount:
          type: integer
          title: Min Amount
          description: Require a minimum order amount to apply the coupon
        max_redemptions:
          type: integer
          title: Max Redemptions
          description: Limit the number of times this code can be redeemed
        max_redemptions_per_user:
          type: integer
          title: Max Redemptions Per User
          description: Limit the number of times a user can redeem the coupon
        is_stackable_with_bonus_coupons:
          type: boolean
          title: Is Stackable With Bonus Coupons
          description: Allow stacking with bonus coupons
        stackable_bonus_limit_percent:
          type: integer
          title: Stackable Bonus Limit Percent
          description: Limit the bonus percent when stacking with bonus coupons
        is_stackable_with_discount_coupons:
          type: boolean
          title: Is Stackable With Discount Coupons
          description: Allow stacking with discount coupons
        stackable_discount_limit_percent:
          type: integer
          title: Stackable Discount Limit Percent
          description: Limit the discount percent when stacking with discount coupons
        store_item_discount_limit_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Store Item Discount Limit Percent
          description: Limit the combined store item and coupon discount percent
        store_item_bonus_limit_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Store Item Bonus Limit Percent
          description: Limit the combined store item and coupon bonus percent
        start_at:
          type: integer
          title: Start At
          description: The timestamp when the coupon becomes valid
        end_at:
          type: integer
          title: End At
          description: The timestamp when the coupon ceases to be valid
        player_ids:
          items:
            type: string
          type: array
          title: Player Ids
          description: The player IDs that can redeem the coupon
        exclude_player_ids:
          items:
            type: string
          type: array
          title: Exclude Player Ids
          description: The player IDs that cannot redeem the coupon
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the coupon
        code:
          type: string
          maxLength: 20
          title: Code
          description: The code of the coupon
        type:
          description: The type of the coupon
          $ref: '#/components/schemas/CouponType'
        id:
          type: string
          title: Id
          description: The unique identifier of the coupon
        creator_program:
          title: Creator Program
          description: The creator program for the coupon
          $ref: '#/components/schemas/CreatorProgramBase'
        current_balance_usd:
          type: integer
          title: Current Balance USD
          description: The current balance in USD for fixed discount coupon type
        items:
          items:
            $ref: '#/components/schemas/ItemRead'
          type: array
          title: Items
          description: All items granted by the coupon, in the same order as `free_items.items`.
        redeemed_at:
          type: integer
          title: Redeemed At
        order_item_id:
          type: string
          title: Order Item Id
      type: object
      required:
      - name
      - code
      - type
      - id
      title: UserCouponRead
    ItemViewOption:
      type: string
      enum:
      - default
      - skeleton
      title: ItemViewOption
      description: An enumeration.
    Highlights:
      properties:
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        items:
          items:
            $ref: '#/components/schemas/HighlightItem'
          type: array
          title: Items
      type: object
      required:
      - items
      title: Highlights
    ItemPropertyConfigString:
      properties:
        property_type:
          type: string
          enum:
          - string
          title: Property Type
          default: string
      type: object
      title: ItemPropertyConfigString
    ItemPropertyConfigNumber:
      properties:
        property_type:
          type: string
          enum:
          - number
          title: Property Type
          default: number
      type: object
      title: ItemPropertyConfigNumber
    MathExpression:
      properties:
        tokens:
          items:
            $ref: '#/components/schemas/Token'
          type: array
          title: Tokens
        name:
          type: string
          title: Name
      type: object
      required:
      - name
      title: MathExpression
    ItemPropertyConfigRange:
      properties:
        property_type:
          type: string
          enum:
          - range
          title: Property Type
          default: range
        max:
          type: integer
          title: Max
        min:
          type: integer
          title: Min
          default: 0
      type: object
      required:
      - max
      title: ItemPropertyConfigRange
    ItemPropertyRelationRead:
      properties:
        property_id:
          type: string
          title: Property Id
        data:
          $ref: '#/components/schemas/ItemPropertyRelationData'
        position:
          type: integer
          title: Position
        id:
          type: string
          title: Id
        item_id:
          type: string
          title: Item Id
        item_property:
          $ref: '#/components/schemas/ItemPropertyRead'
      type: object
      required:
      - property_id
      - position
      - id
      - item_id
      - item_property
      title: ItemPropertyRelationRead
    CouponFreeItem:
      properties:
        item_id:
          type: string
          title: Item Id
          description: The item ID to grant when the coupon is redeemed
        quantity:
          type: integer
          minimum: 1.0
          title: Quantity
          description: Quantity granted when the coupon is redeemed
      type: object
      required:
      - item_id
      - quantity
      title: CouponFreeItem
    NestedItemViewType:
      type: string
      enum:
      - separated
      title: NestedItemViewType
      description: An enumeration.
    CouponType:
      type: string
      enum:
      - bonus
      - discount
      - free_item
      - vc
      - non_benefit
      - discount_fixed
      - discount_reward_point
      title: CouponType
      description: An enumeration.
    ItemPropertyRead:
      properties:
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the property
        description:
          type: string
          maxLength: 512
          title: Description
          description: The description of the property
        icon_url:
          anyOf:
          - type: string
            maxLength: 65536
            minLength: 1
            format: uri
          - type: string
            enum:
            - ''
          title: Icon Url
          description: The URL of the icon for the property
        config:
          oneOf:
          - $ref: '#/components/schemas/ItemPropertyConfigRange'
          - $ref: '#/components/schemas/ItemPropertyConfigNumber'
          - $ref: '#/components/schemas/ItemPropertyConfigString'
          title: Config
          description: The config of the property
          discriminator:
            propertyName: property_type
            mapping:
              range: '#/components/schemas/ItemPropertyConfigRange'
              number: '#/components/schemas/ItemPropertyConfigNumber'
              string: '#/components/schemas/ItemPropertyConfigString'
        id:
          type: string
          title: Id
          description: The unique identifier of the property
      type: object
      required:
      - name
      - config
      - id
      title: ItemPropertyRead
    CouponRead:
      properties:
        free_items:
          title: Free Items
          description: Items granted when the coupon is redeemed
          $ref: '#/components/schemas/CouponFreeItems'
        discount_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Discount Percent
          description: The discount percent for the coupon
        bonus_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Bonus Percent
          description: The bonus percent for the coupon
        bonus_fixed:
          type: integer
          minimum: 1.0
          title: Bonus Fixed
          description: The fixed bonus amount for the coupon
          nullable: true
        discount_amount_usd:
          type: integer
          minimum: 0.0
          title: Discount Amount USD
          description: The discount amount in USD for the coupon
        requirements_expression:
          title: Requirements Expression
          description: The requirement expression for the coupon
          $ref: '#/components/schemas/Expression'
        expires_at:
          type: integer
          title: Expires At
          description: The expiration date of the coupon
        applicable_item_ids:
          items:
            type: string
          type: array
          title: Applicable Item Ids
          description: The applicable item IDs
        category_id:
          type: string
          title: Category Id
          description: The coupon category ID
        min_amount:
          type: integer
          title: Min Amount
          description: Require a minimum order amount to apply the coupon
        max_redemptions:
          type: integer
          title: Max Redemptions
          description: Limit the number of times this code can be redeemed
        max_redemptions_per_user:
          type: integer
          title: Max Redemptions Per User
          description: Limit the number of times a user can redeem the coupon
        is_stackable_with_bonus_coupons:
          type: boolean
          title: Is Stackable With Bonus Coupons
          description: Allow stacking with bonus coupons
        stackable_bonus_limit_percent:
          type: integer
          title: Stackable Bonus Limit Percent
          description: Limit the bonus percent when stacking with bonus coupons
        is_stackable_with_discount_coupons:
          type: boolean
          title: Is Stackable With Discount Coupons
          description: Allow stacking with discount coupons
        stackable_discount_limit_percent:
          type: integer
          title: Stackable Discount Limit Percent
          description: Limit the discount percent when stacking with discount coupons
        store_item_discount_limit_percent:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Store Item Discount Limit Percent
          description: Limit the combined store item and coupon discount percent
        store_item_bonus_limit_percent:
          type: integer
          maximum: 1000.0
          minimum: 0.0
          title: Store Item Bonus Limit Percent
          description: Limit the combined store item and coupon bonus percent
        start_at:
          type: integer
          title: Start At
          description: The timestamp when the coupon becomes valid
        end_at:
          type: integer
          title: End At
          description: The timestamp when the coupon ceases to be valid
        player_ids:
          items:
            type: string
          type: array
          title: Player Ids
          description: The player IDs that can redeem the coupon
        exclude_player_ids:
          items:
            type: string
          type: array
          title: Exclude Player Ids
          description: The player IDs that cannot redeem the coupon
        name:
          type: string
          maxLength: 255
          title: Name
          description: The name of the coupon
        code:
          type: string
          maxLength: 20
          title: Code
          description: The code of the coupon
        type:
          description: The type of the coupon
          $ref: '#/components/schemas/CouponType'
        id:
          type: string
          title: Id
          description: The unique identifier of the coupon
        creator_program:
          title: Creator Program
          description: The creator program for the coupon
          $ref: '#/components/schemas/CreatorProgramBase'
        current_balance_usd:
          type: integer
          title: Current Balance USD
          description: The current balance in USD for fixed discount coupon type
        items:
          items:
            $ref: '#/components/schemas/ItemRead'
          type: array
          title: Items
          description: All items granted by the coupon, in the same order as `free_items.items`.
      type: object
      required:
      - name
      - code
      - type
      - id
      title: CouponRead
    CreatorProgramUpdate:
      properties:
        verbal_terms:
          type: string
          title: Verbal Terms
          description: The verbal terms for the creator program
        message:
          type: string
          title: Message
          description: The message for the creator program
        reward:
          type: integer
          maximum: 100.0
          minimum: 0.0
          title: Reward
          description: The reward for the coupon
        inherits_from_tier:
          type: boolean
          title: Inherits From Tier
          description: When true, revenue share is taken from the creator's current tier instead of `reward`.
      type: object
      title: CreatorProgramUpdate
    TokenType:
      type: string
      enum:
      - attribute
      - custom_attribute
      - event_attribute
      - custom_event_attribute
      - operator
      - number
      - date
      - string
      - boolean
      - list
      - variable
      - virtual_currency
      title: TokenType
    ItemPropertyRelationData:
      properties:
        value:
          anyOf:
          - type: number
          - type: integer
          - type: string
          title: Value
      type: object
      title: ItemPropertyRelationData
  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.