Aghanim Stores API

openapi: 3.1.0
info:
  title: Aghanim Server-to-Server Achievements Stores 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: Stores
paths:
  /v1/stores/store/{store_item_id}:
    get:
      tags:
      - Stores
      summary: Get Store By Store Item
      operationId: get_store_by_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_item_id
        in: path
        required: true
        schema:
          title: Store Item Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/stores:
    get:
      tags:
      - Stores
      summary: Get Stores
      operationId: get_stores
      security:
      - HTTPBearer: []
      parameters:
      - name: search_string
        in: query
        required: false
        schema:
          title: Search String
          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 Stores
                type: array
                items:
                  $ref: '#/components/schemas/StoreReadStat'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Stores
      summary: Create Store
      operationId: create_store
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Create
              $ref: '#/components/schemas/StoreCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Stores
      summary: Bulk Delete Stores
      description: Deletes multiple stores.
      operationId: bulk_delete_stores
      security:
      - HTTPBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Delete
              type: array
              items:
                $ref: '#/components/schemas/StoreBulkDelete'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/stores/{store_id}:
    get:
      tags:
      - Stores
      summary: Get Store
      operationId: get_store
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Stores
      summary: Update Store
      operationId: update_store
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Update
              $ref: '#/components/schemas/StoreUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Stores
      summary: Delete Store
      operationId: delete_store
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/user/{user_id}:
    get:
      tags:
      - Stores
      summary: Get User Store Items
      operationId: get_user_store_items
      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 Store Items
                type: array
                items:
                  $ref: '#/components/schemas/UserStoreItem'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/campaign/{campaign_id}:
    get:
      tags:
      - Stores
      summary: Get Campaign Store Items
      operationId: get_campaign_store_items
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          title: Campaign Id
          type: string
      - name: only_purchased
        in: query
        required: false
        schema:
          title: Only Purchased
          default: false
          type: boolean
      - 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 Campaign Store Items
                type: array
                items:
                  $ref: '#/components/schemas/VirtualStoreItemUser'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/report:
    get:
      tags:
      - Stores
      summary: Get Virtual SKU Stat
      operationId: get_virtual_sku_stat
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: query
        required: false
        schema:
          title: Campaign Id
          type: string
      - name: user_id
        in: query
        required: false
        schema:
          title: User Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualSKUStat'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/{store_id}:
    get:
      tags:
      - Stores
      summary: Get Store Items
      operationId: get_store_items
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Get Store Items
                type: array
                items:
                  $ref: '#/components/schemas/StoreItemRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Stores
      summary: Create Store Item
      operationId: create_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Create
              $ref: '#/components/schemas/StoreItemCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreItemRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Stores
      summary: Bulk Update Store Items
      description: Updates multiple store items.
      operationId: bulk_update_store_items
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Update
              type: array
              items:
                $ref: '#/components/schemas/StoreItemBulkUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Bulk Update Store Items
                type: array
                items:
                  $ref: '#/components/schemas/StoreItemRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Stores
      summary: Bulk Delete Store Items
      description: Deletes multiple store items.
      operationId: bulk_delete_store_items
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Bulk Delete
              type: array
              items:
                $ref: '#/components/schemas/StoreItemBulkDelete'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items:
    get:
      tags:
      - Stores
      summary: Get All Store Items
      operationId: get_all_store_items
      security:
      - HTTPBearer: []
      parameters:
      - name: ids
        in: query
        required: false
        schema:
          title: Ids
          description: Optional comma separated list of ids
          type: string
        description: Optional comma separated list of ids
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Get All Store Items
                type: array
                items:
                  $ref: '#/components/schemas/StoreItemRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/{store_id}/batch:
    post:
      tags:
      - Stores
      summary: Batch Create Store Item
      operationId: batch_create_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Items Create
              $ref: '#/components/schemas/ItemsCreate'
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/{store_id}/{store_item_id}:
    put:
      tags:
      - Stores
      summary: Update Store Item
      operationId: update_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      - name: store_item_id
        in: path
        required: true
        schema:
          title: Store Item Id
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Update
              $ref: '#/components/schemas/StoreItemUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreItemRead'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Stores
      summary: Delete Store Item
      operationId: delete_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_item_id
        in: path
        required: true
        schema:
          title: Store Item Id
          type: string
      - name: store_id
        in: path
        required: true
        schema:
          title: Store Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/store_items/virtual/{store_item_id}:
    delete:
      tags:
      - Stores
      summary: Delete Virtual Store Item
      operationId: delete_virtual_store_item
      security:
      - HTTPBearer: []
      parameters:
      - name: store_item_id
        in: path
        required: true
        schema:
          title: Store Item Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    VirtualCurrencySettings:
      properties:
        rate:
          type: number
          exclusiveMinimum: 0.0
          title: Rate
          default: 1.0
        enabled_for_checkout:
          type: boolean
          title: Enabled For Checkout
          default: false
        reward_active:
          type: boolean
          title: Reward Active
          default: false
        reward_percentage:
          type: number
          minimum: 0.0
          title: Reward Percentage
          default: 0.0
        excluded_sales_channels:
          items:
            $ref: '#/components/schemas/OrderSourceType'
          type: array
        price_source:
          default: local_price
          $ref: '#/components/schemas/VCPriceSource'
        allow_non_secure_auth:
          type: boolean
          title: Allow Non Secure Auth
          default: false
      type: object
      title: VirtualCurrencySettings
    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
    StoreWebhookSettings:
      properties:
        webhook_id:
          type: string
          title: Webhook Id
        cache_period_type:
          $ref: '#/components/schemas/PeriodType'
        cache_period_value:
          type: integer
          title: Cache Period Value
      type: object
      required:
      - webhook_id
      title: StoreWebhookSettings
    RotationType:
      type: string
      enum:
      - random
      - random_by_weight
      - round_robin
      title: RotationType
      description: An enumeration.
    SubscriptionOffer:
      properties:
        key:
          type: string
          title: Key
          description: The unique key of the offer
        name:
          type: string
          title: Name
          description: The display name of the offer
        description:
          type: string
          title: Description
          description: The description of the offer
        discount_percent:
          type: integer
          title: Discount Percent
          description: The discount percentage for the offer
        eligibility_rules:
          items:
            $ref: '#/components/schemas/SubscriptionOfferEligibility'
          type: array
          description: The list of eligibility rules for the offer
        grace_extension:
          type: integer
          title: Grace Extension
          description: The grace period extension in days
        trial_extension:
          type: integer
          title: Trial Extension
          description: The trial period extension in days
        activation_limits:
          type: integer
          title: Activation Li

# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aghanim/refs/heads/main/openapi/aghanim-stores-api-openapi.yml