openapi: 3.1.0 info: title: Aghanim Server-to-Server Achievements Orders 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: Orders paths: /v1/orders/{order_id}: get: tags: - Orders summary: Get Order description: Returns the order with the latest status. operationId: get_order security: - HTTPBearer: [] parameters: - name: order_id in: path required: true schema: title: Order Id type: string responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrderRead' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - Orders summary: Update Order description: Updates the order. operationId: update_order security: - HTTPBearer: [] parameters: - name: order_id in: path required: true schema: title: Order Id type: string requestBody: required: true content: application/json: schema: title: Update $ref: '#/components/schemas/OrderUpdate' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrderRead' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/orders: post: tags: - Orders summary: Create Order description: "Creates an order for the specified `player_id` and list of `items`.\n\nThe response includes a `checkout_url` that the player should be\nredirected to in order to complete the purchase.\n\nYou can optionally provide:\n- `back_to_game_url`: A universal deep link that appears as a \"Back to Game\"\n button on the checkout page. Typically, this should open the game client.\n- `back_to_store_url`: A web URL that appears as a \"Back to Store\"\n button on the checkout page. Usually links to your store website." operationId: create_order requestBody: content: application/json: schema: title: Create $ref: '#/components/schemas/OrderCreate' required: true responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/OrderCreateResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - HTTPBearer: [] /v1/orders/{order_id}/expire: patch: tags: - Orders summary: Expire Order description: 'Expires the order. The expiration timestamp is set to the current time, which makes the order impossible to pay. Only orders with status `created` or `reattempted` can be expired. Attempting to expire an order in any other status will result in an error.' operationId: expire_order security: - HTTPBearer: [] parameters: - name: order_id in: path required: true schema: title: Order Id type: string responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/orders/{order_id}/refund: post: tags: - Orders summary: Refund Order operationId: refund_order security: - HTTPBearer: [] parameters: - name: order_id in: path required: true schema: title: Order Id type: string requestBody: required: true content: application/json: schema: title: Order Refund $ref: '#/components/schemas/OrderRefund' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: Locale: type: string enum: - cs - de - en - es - fr - fr-CA - hi - id - it - ja - ko - ms - nl - 'no' - pl - pt - pt-BR - ru - sv - th - tr - uk - vi - zh - zh-Hant title: Locale description: Language codes according to ISO 639-1. OrderCreatePlatform: type: string enum: - ios - android - other title: OrderCreatePlatform description: An enumeration. PlayerAttributes: properties: level: type: integer title: Level default: 0 posthog: true platform: $ref: '#/components/schemas/Platform' marketplace: default: none $ref: '#/components/schemas/Marketplace' device_type: $ref: '#/components/schemas/DeviceType' tags: items: $ref: '#/components/schemas/PlayerTag' type: array soft_currency_amount: type: integer title: Soft Currency Amount default: 0 hard_currency_amount: type: integer title: Hard Currency Amount default: 0 appsflyer_id: type: string title: Appsflyer Id appsflyer_app_id: type: string title: Appsflyer App Id appsflyer_meta: type: object title: Appsflyer Meta appsflyer_event_params: type: object title: Appsflyer Event Params appsflyer_customer_user_id: type: string title: Appsflyer Customer User Id adjust_device_id: additionalProperties: type: string type: object title: Adjust Device Id adjust_adid: type: string title: Adjust Adid adjust_app_token: type: string title: Adjust App Token adjust_authorization_token: type: string title: Adjust Authorization Token adjust_purchase_event_token: type: string title: Adjust Purchase Event Token adjust_callback_params: additionalProperties: type: string type: object title: Adjust Callback Params adjust_partner_params: additionalProperties: type: string type: object title: Adjust Partner Params singular_device_id: additionalProperties: type: string type: object title: Singular Device Id singular_app_id: type: string title: Singular App Id devtodev_appid: type: string title: Devtodev Appid devtodev_apikey: type: string title: Devtodev Apikey devtodev_device_id: $ref: '#/components/schemas/DevtodevDeviceId' ga4_client_id: type: string title: Ga4 Client Id description: GA4 web `client_id` from the `_ga` cookie. ga4firebase_app_instance_id: type: string title: Ga4Firebase App Instance Id description: Firebase mobile `app_instance_id` from the SDK. ga4_user_id: type: string maxLength: 256 title: Ga4 User Id description: Partner-set GA4 cross-device `user_id`; falls back to `User.player_id` when unset. type: object title: PlayerAttributes PlayerInfo: properties: attributes: title: Attributes description: The player's attributes. $ref: '#/components/schemas/PlayerAttributes' custom_attributes: type: object title: Custom Attributes description: The player's custom attributes. name: type: string title: Name description: The player's name. avatar_url: type: string title: Avatar Url description: The player's avatar URL. type: object title: PlayerInfo 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. 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 RedirectSettings: properties: mode: description: The redirect mode after a successful payment. `no_redirect` - no automatic redirect, `immediate` - redirect immediately, `delayed` - redirect after delay in `delay_seconds`. default: no_redirect $ref: '#/components/schemas/RedirectMode' delay_seconds: type: number maximum: 300.0 exclusiveMinimum: 0.0 title: Delay Seconds description: The redirect delay in seconds when `mode` is set to `delayed`. If not specified, defaults to 5 seconds. target: description: The target of the redirect. `game` - redirect to the game (`back_to_game_url`), `store` - redirect to the store (`back_to_store_url`). If not specified, the target will be either `game` or `store` whichever URL is available in the order. $ref: '#/components/schemas/RedirectTarget' type: object title: RedirectSettings OrderRewards: properties: available: items: $ref: '#/components/schemas/OrderVirtualCurrencyReward' type: array title: Available type: object required: - available title: OrderRewards 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 Mode: type: string enum: - dark - light - auto title: Mode description: An enumeration. RedirectMode: type: string enum: - no_redirect - immediate - delayed title: RedirectMode description: An enumeration. PublicPaymentMethod: type: string enum: - card - paypal - apple_pay - google_pay - cashapp - klarna - venmo title: PublicPaymentMethod description: Payment methods exposed to customers. Marketplace: type: string enum: - none - app_store - google_play - aghanim - other - one_store - galaxy_store title: Marketplace OrderCreate: properties: items: items: $ref: '#/components/schemas/OrderItemCreate' type: array minItems: 1 title: Items description: A list of items the player wants to purchase. player_id: type: string title: Player Id description: A unique identifier for the player making the purchase. email: type: string format: email title: Email description: The player's email address, used as the billing email address. player_info: title: Player Info description: Additional player information. $ref: '#/components/schemas/PlayerInfo' discount_percent: type: integer maximum: 100.0 minimum: 0.0 title: Discount Percent description: The percentage of discount applied to the order. eligible_for_reward_points: type: integer title: Eligible For Reward Points description: The number of reward points the order is eligible for. eligible_for_loyalty_points: type: integer title: Eligible For Loyalty Points description: The number of loyalty points the order is eligible for. country: type: string pattern: ^[A-Z]{2}$ title: Country description: The two-letter country code (ISO 3166-1 alpha-2) for the order. If not provided, the country will be determined by the IP address of the player when the checkout page is opened. country_locked: type: boolean title: Country Locked description: Whether the order country is locked after creation. If `true`, the player cannot pay from a different country than the one initially specified in the `country` field. redirect_settings: title: Redirect Settings description: The settings for redirecting the player after a successful payment. Depending on the mode, the player will be redirected to either `back_to_game_url` or `back_to_store_url`, if provided. $ref: '#/components/schemas/RedirectSettings' ui_settings: title: Ui Settings description: The UI settings for checkout page. $ref: '#/components/schemas/UISettings' ip_address: type: string format: ipvanyaddress title: Ip Address description: The IP address of the player placing the order. user_agent: type: string title: User Agent description: The User-Agent string representing the player's browser properties, including browser type, version, and operating system locale: description: The player's preferred locale or language. $ref: '#/components/schemas/Locale' return_url: type: string title: Return Url description: 'DEPRECATED: Use `back_to_game_url` or `back_to_store_url` instead. The URL to redirect the player after the purchase.' deprecated: true back_to_game_url: type: string title: Back To Game Url description: The URL to redirect the player back to the game after the purchase. Supports formatting with {order_id}. back_to_store_url: type: string maxLength: 65536 minLength: 1 format: uri title: Back To Store Url description: The URL to redirect the player back to the store. Supports formatting with {order_id}. payment_methods_enabled: items: $ref: '#/components/schemas/PublicPaymentMethod' type: array description: The list of payment methods enabled for the order. coupons_enabled: type: boolean title: Coupons Enabled description: Whether coupons are enabled for the order. metadata: additionalProperties: type: string type: object title: Metadata description: The metadata object structured as key-value pairs to store additional information about the order. price_decimal: type: number maximum: 1000000000.0 minimum: 0.0 title: Price Decimal description: Order price in decimal units. Overrides item price if set. nullable: true currency: description: Order currency (ISO 4217 code). See supported currencies. nullable: true $ref: '#/components/schemas/Currency' currency_preferred: type: boolean title: Currency Preferred description: Prefer the specified currency and ignore country-specific pricing. default: false price_template_id: type: string title: Price Template Id description: The unique identifier for the price template. nullable: true platform: description: The platform of the order. nullable: true $ref: '#/components/schemas/OrderCreatePlatform' expires_at: type: integer title: Expires At description: Order expiration date in Unix epoch time. If not provided, defaults to 3 days from creation. Orders cannot be paid after this date. nullable: true coupon_code: type: string minLength: 1 title: Coupon Code description: A coupon code to apply to the order on creation. Used for creator attribution when the code belongs to a creator program. nullable: true type: object required: - items - player_id title: OrderCreate examples: - player_id: r2d2-c3po items: - sku: crystal Platform: type: string enum: - any - ios - android - other title: Platform HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError DeviceType: type: string enum: - Apple - Android - Unknown - Other title: DeviceType OrderRead: properties: id: type: string title: Id description: The unique ID of the order. receipt_number: type: string title: Receipt Number description: The number of the payment in receipt amount: type: integer title: Amount description: The amount of the order. amount_before_discount: type: integer title: Amount Before Discount description: The amount of the order before discount. currency: description: The currency of the order. $ref: '#/components/schemas/Currency' player_id: type: string title: Player Id description: The unique identifier for the player making the purchase. email: type: string title: Email description: The player's email address. player_info: title: Player Info description: Additional player information. $ref: '#/components/schemas/PlayerInfo' items: items: $ref: '#/components/schemas/OrderItemRead' type: array title: Items description: The list of items the player wants to purchase included bonus items. status: description: The current status of the order. $ref: '#/components/schemas/OrderStatus' created_at: type: integer title: Created At description: Order creation date in Unix epoch time. paid_at: type: integer title: Paid At description: Order payment date in Unix epoch time. metadata: type: object title: Metadata description: The metadata object structured as key-value pairs to store additional information about the order. expires_at: type: integer title: Expires At description: Order expiration date in Unix epoch time (seconds). Orders cannot be paid after this date. checkout_url: type: string maxLength: 2083 minLength: 1 format: uri title: Checkout Url description: The URL to redirect the player to complete the purchase. redirect_settings: title: Redirect Settings description: The settings for redirecting the player after a successful payment. Depending on the mode, the player will be redirected to either `back_to_game_url` or `back_to_store_url`, if provided. $ref: '#/components/schemas/RedirectSettings' ui_settings: title: Ui Settings description: The UI settings for checkout page. $ref: '#/components/schemas/UISettings' coupons_enabled: type: boolean title: Coupons Enabled description: Whether coupons are enabled for the order. applied_reward_points: type: integer title: Applied Reward Points description: The applied reward points for the order that allowed you to receive a discount. coupons: items: $ref: '#/components/schemas/Coupon' type: array title: Coupons description: The list of coupons applied to the order. eligible_for_reward_points: type: integer title: Eligible For Reward Points description: The number of reward points the player is eligible to receive for this order. eligible_for_loyalty_points: type: integer title: Eligible For Loyalty Points description: The number of loyalty points the player is eligible to receive for this order. rewards: title: Rewards description: The virtual currency rewards the player is eligible to receive for this order. $ref: '#/components/schemas/OrderRewards' type: object required: - id - amount - amount_before_discount - currency - player_id - items - status - created_at - checkout_url title: OrderRead examples: - id: ord_XXXXXXX player_id: r2d2-c3po items: - sku: crystal status: paid created_at: 1690000000 paid_at: 1690000100 metadata: key: value checkout_url: https://pay.aghanim.com/order/ord_XXXXXXX RedirectTarget: type: string enum: - game - store title: RedirectTarget description: An enumeration. Item: properties: id: type: string title: Id description: The unique ID of the item. sku: type: string minLength: 1 title: SKU description: Stock Keeping Unit (SKU) identifier. name: type: string title: Name description: The name of the item. source: description: The source of the payment item. $ref: '#/components/schemas/ItemSource' description: type: string title: Description description: The description of the item nullable: true image_url: type: string title: Image Url description: The URL of the image for the item quantity: type: integer exclusiveMinimum: 0.0 title: Quantity description: The quantity of the item. nested_items: items: $ref: '#/components/schemas/Item' type: array title: Nested Items description: Nested items of the bundle. type: object required: - id - sku - name - source - quantity title: Item DevtodevDeviceId: properties: deviceId: type: string title: Deviceid devtodevId: type: integer title: Devtodevid userId: type: string title: Userid advertisingId: type: string title: Advertisingid type: object title: DevtodevDeviceId OrderRefund: properties: reason: type: string title: Reason description: Reason of refund order type: object required: - reason title: OrderRefund OrderStatus: type: string enum: - created - captured - paid - canceled - refunded - refund_requested - reattempted - disputed title: OrderStatus description: An enumeration. OrderItemRead: properties: id: type: string title: Id description: The unique ID of the item. sku: type: string minLength: 1 title: SKU description: Stock Keeping Unit (SKU) identifier. name: type: string title: Name description: The name of the item. source: description: The source of the payment item. $ref: '#/components/schemas/ItemSource' description: type: string title: Description description: The description of the item nullable: true image_url: type: string title: Image Url description: The URL of the image for the item quantity: type: integer exclusiveMinimum: 0.0 title: Quantity description: The quantity of the item. nested_items: items: $ref: '#/components/schemas/Item' type: array title: Nested Items description: Nested items of the bundle. selected_plan_key: type: string title: Selected Plan Key description: The key of the subscription plan to pre-select on the checkout page. Only applicable to subscription SKUs. nullable: true currency: description: The currency of the item. $ref: '#/components/schemas/Currency' price: type: integer title: Price description: The price of the item in minor [currency units](https://docs.aghanim.com/currencies/) price_point: type: integer title: Price Point description: The price point for local prices price_decimal: type: number title: Price Decimal description: price in decimal units type: object required: - id - sku - name - source - quantity - currency title: OrderItemRead OrderVirtualCurrencyReward: properties: type: type: string enum: - virtual_currency title: Type default: virtual_currency name: type: string title: Name virtual_currency_id: type: string title: Virtual Currency Id amount: type: integer title: Amount issue_status: $ref: '#/components/schemas/RewardIssueStatus' icon_url: type: string title: Icon Url sku: type: string title: SKU type: object required: - virtual_currency_id - amount title: OrderVirtualCurrencyReward PlayerTag: type: string enum: - tester title: PlayerTag UISettings: properties: mode: description: The appearance mode for checkout page. `dark` (dark mode), `light` (light mode), or `auto` (follows system preference) $ref: '#/components/schemas/Mode' show_player_info: type: boolean title: Show Player Info description: Whether to display player information on checkout page type: object title: UISettings Coupon: properties: id: type: string title: Id description: The unique ID of the coupon. code: type: string title: Code description: The coupon code. name: type: string title: Name description: The name of the coupon. type: description: The type of the coupon. $ref: '#/components/schemas/CouponType' discount_percent: type: integer title: Discount Percent description: Discount percent for `discount` coupons. bonus_percent: type: integer title: Bonus Percent description: Bonus percent for `bonus` coupons. bonus_fixed: type: integer title: Bonus Fixed description: Fixed bonus quantity for `bonus` coupons. type: object required: - id - code - name - type title: Coupon CouponType: type: string enum: - bonus - discount - free_item - vc - non_benefit - discount_fixed - discount_reward_point title: CouponType description: An enumeration. RewardIssueStatus: type: string enum: - issued - revoked - issue_failed - revoke_failed title: RewardIssueStatus description: An enumeration. OrderUpdate: properties: handled_by_client: type: boolean title: Handled By Client description: Whether the order was handled/consumed by the client or not. type: object title: OrderUpdate OrderItemCreate: properties: sku: type: string minLength: 1 title: SKU description: Stock Keeping Unit (SKU) identifier. name: type: string title: Name description: The name of the item. nullable: true description: type: string title: Description description: The description of the item nullable: 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 nullable: true quantity: type: integer exclusiveMinimum: 0.0 title: Quantity description: The quantity of the item. nullable: true store_key: type: string title: Store Key description: The key of the store where order taking store item for discount and benefits. nullable: true selected_plan_key: type: string title: Selected Plan Key description: The key of the subscription plan to pre-select on the checkout page. Only applicable to subscription SKUs. nullable: true type: object required: - sku title: OrderItemCreate OrderCreateResponse: properties: order_id: type: string title: Order Id description: The unique ID of the created order. checkout_url: type: string maxLength: 2083 minLength: 1 format: uri title: Checkout Url description: The URL to redirect the player to complete the purchase. type: object required: - order_id - checkout_url title: OrderCreateResponse examples: - order_id: ord_XXXXXXX checkout_url: https://pay.aghanim.com/order/ord_XXXXXXX 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.