> ## Documentation Index > Fetch the complete documentation index at: https://docs.scaleo.io/llms.txt > Use this file to discover all available pages before exploring further. # Create commission plan > Creates a new commission plan with CPA, RevShare, CPL, CPC, FlatFee, and/or LotBasedFee entities. Each commission block (cpa, rev_share, cpl, cpc) requires `enabled: true` to activate, `type` to select the calculation method, and `commission` with the format matching the type. The flat_fee block has its own structure with `commission`, `period`, and `start_date`. Past dates are accepted for `flat_fee.commission.start_date`. Commission types disabled in company settings cannot be submitted. Dependent features are validated independently: `cpa.hold_period` follows the CPA hold-period setting, `cpl.hold_period` follows the CPL hold-period setting, `cap` follows the CPA cap setting, and `high_roller_policy_*` follows the RevShare setting. Deleted affiliates in `assigned_to` are ignored instead of triggering validation errors. **Important**: `product` is the offer ID. Do NOT use the format `{payout, revenue, currency}` — it creates a plan with empty (null) commission data. Always use `{enabled, type, commission}` format. ## OpenAPI ````yaml /brand.bundled.yaml post /api/v2/network/commission-plan openapi: 3.1.0 info: title: Scaleo Brand API version: 0.1.1 summary: REST API for external integrations with the Scaleo affiliate platform. contact: name: Scaleo Support email: support@scaleo.io description: > The Scaleo Public API gives external systems the same capabilities as the dashboard, organised by user role — **Affiliate** and **Manager** — plus shared reference data. Use the sidebar guides to get started: | Guide | Covers | |---|---| | [Authentication](#tag/Authentication) | API keys, role scoping | | [Errors](#tag/Errors) | Response envelope, error codes | | [Pagination](#tag/Pagination) | List params, pagination headers | | [Versioning](#tag/Versioning) | Version prefix, compatibility | | [Conventions](#tag/Conventions) | Timestamps, IDs, currencies | ## Quick start Authenticate with your API key using the `X-API-Key` HTTP header (preferred): ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The legacy `api-key` query parameter is still accepted but **deprecated** — see [Authentication](#tag/Authentication) for migration details. Every response uses a consistent JSON envelope: ```json { "message": "OK", "success": true, "info": { } } ``` `success` is `true` for 2xx responses and `false` for errors. See [Errors](#tag/Errors) for the full format and error codes. ## Roles | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Affiliate | `/api/v2/affiliate/...` | Each API key is bound to one role and cannot call endpoints of another role. servers: - url: https://{domain} description: Customer-specific deployment. variables: domain: default: operator.scaletrk.com description: Your Scaleo instance domain. security: - ApiKeyHeaderAuth: [] - ApiKeyAuth: [] tags: - name: Overview x-displayName: Overview description: > The Scaleo Public API exposes the same data and operations available in the web dashboard, organised by user role — **Affiliate** and **Manager** — plus a small set of shared resources. It is a REST API. All endpoints accept and return JSON, except for binary download endpoints (invoice PDFs, creative assets) which return raw file data. ## What you can do | Role | Capabilities | |---|---| | **Affiliates** | Offers, campaigns, payouts, click/conversion stats. | | **Managers** | Full administration: affiliates, offers, billing, tracking, reporting. | | **All roles** | Shared reference data — countries, categories, tags, tiers. | ## URL conventions | URL prefix | Role | |---|---| | `/api/v2/network/...` | Manager | | `/api/v2/affiliate/...` | Affiliate | `{id}` in paths is a numeric resource ID. All timestamps are ISO 8601 UTC. ## Where to start 1. Read **Authentication** in the sidebar and obtain an API key. 2. Read **Errors** to understand the response envelope. 3. Try `GET /api/v2/affiliate/profile` (or the equivalent for your role) to verify your key works. 4. Browse the role-scoped sections for the endpoints relevant to your integration. ## Support For integration support, contact your account manager or [support@scaleo.io](mailto:support@scaleo.io). - name: Authentication x-displayName: Authentication description: > All Public API requests are authenticated with an **API key**. Pass it in the `X-API-Key` HTTP request header — this is the **preferred** method: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile X-API-Key: YOUR_KEY ``` The user account that owns the key must have `api_status` enabled. ## Deprecated: `api-key` query parameter The `api-key` URL query parameter is still accepted for backwards compatibility but is **deprecated** and will be removed in a future release: ``` GET https://your-domain.scaleo.io/api/v2/affiliate/profile?api-key=YOUR_KEY ``` :::warning Deprecated Migrate to the `X-API-Key` header. Support for the `api-key` query parameter will be removed approximately 6 months after this notice. ::: ## Role scoping Each API key is bound to a specific user role and **cannot** call endpoints outside that role: | Role | Endpoint prefix | |---|---| | Manager | `/api/v2/network/...` | | Affiliate | `/api/v2/affiliate/...` | Calling an endpoint with the wrong role's key returns `403 Forbidden`. ## Where to find your key * **Affiliate** — dashboard → **Profile → API**. * **Manager** — admin panel → **Users → Managers → {user} → API**. Keys can be regenerated at any time. Regeneration invalidates the previous key immediately. ## Security best practices :::tip The `X-API-Key` header keeps your API key out of URLs, request logs, and browser history — always prefer the header over the query parameter. ::: * Use **HTTPS** only — HTTP does not protect the key in transit. * If a key is leaked, rotate it from the dashboard immediately. * For server-to-server integrations, store keys in a secrets manager (e.g. AWS Secrets Manager, HashiCorp Vault) rather than in source control. - name: Errors x-displayName: Errors description: > Every Public API response uses the same JSON envelope regardless of whether the request succeeded: ```json { "message": "OK", "success": true, "info": { } } ``` | Field | Description | |---|---| | `message` · string | Human-readable result summary. | | `success` · boolean | `true` for 2xx, `false` for errors. | | `info` · object | Payload. Omitted when the response carries no data. | :::info The HTTP status code is the authoritative signal. `success` is a convenience for clients that cannot easily inspect HTTP status codes. ::: ## Standard error responses | HTTP status | When you see it | |---|---| | `400 Bad Request` | Invalid JSON, unknown parameter, or malformed request. | | `401 Unauthorized` | Missing or invalid API key (`X-API-Key` header or `api-key` query param), or `api_status` disabled. | | `403 Forbidden` | Key is valid but belongs to a different role. | | `404 Not Found` | Resource not found or not visible to this account. | | `422 Unprocessable Entity` | Validation failed — see `info.errors`. | | `500 Internal Server Error` | Server-side problem. Retry with backoff. | ## Validation errors (422) When validation fails the server returns `422`. Each key in `info.errors` is the failing field name; the value is an array of error strings: ```json { "message": "Validation error", "success": false, "info": { "errors": { "email": ["Email cannot be blank."], "currency": ["Currency must be a valid ISO code."] } } } ``` ## Retry guidance * `4xx` — client problem, fix the request before retrying. * `5xx` — transient server problem. Retry with exponential backoff (start 1 s, max 60 s, add 0–25% jitter). * `GET` and `PUT` on a known resource are always safe to retry. - name: Pagination x-displayName: Pagination description: > List endpoints support consistent query parameters for pagination, filtering, and sorting. ## Pagination parameters | Parameter | Default / Max | |---|---| | `page` · integer | default `1` | | `perPage` · integer | default `10`, max `1000` | :::info Pagination metadata is in response headers, not in the body. ::: Paginated responses carry metadata in **HTTP response headers**: | Header | Value | |---|---| | `X-Pagination-Current-Page` | Current page number | | `X-Pagination-Total-Count` | Total items across all pages | | `X-Pagination-Page-Count` | Total number of pages | | `X-Pagination-Per-Page` | Page size used for this request | Example response for a list endpoint: ```json { "message": "Affiliates List", "success": true, "info": { "affiliates": [] } } ``` With HTTP headers: ``` X-Pagination-Current-Page: 2 X-Pagination-Total-Count: 137 X-Pagination-Page-Count: 7 X-Pagination-Per-Page: 20 ``` ## Sorting | Parameter | Values | |---|---| | `sortField` | endpoint-specific field name | | `sortDirection` | `asc` (default) \| `desc` | ``` GET /api/v2/network/affiliates?sortField=created_at&sortDirection=desc&page=1&perPage=50 ``` ## Filtering | Parameter | Meaning | |---|---| | `field=value` | Exact match — e.g. `status=1` | | `field[]=v1&field[]=v2` | Match any value — e.g. `country[]=US&country[]=GB` | | `field_from` / `field_to` | Date or numeric range | | `q` | Full-text search | ## Date format All date and datetime filters accept ISO 8601. If no timezone is given, UTC is assumed. * Date only: `2026-01-20` * Datetime UTC: `2026-01-20T13:45:00Z` - name: Versioning x-displayName: Versioning description: > The Public API uses a path-based version prefix. | Version | Status | Prefix | |---|---|---| | **v2** | Stable, default | `/api/v2/...` | ## Compatibility policy * **Additive changes** (new fields, new endpoints) can appear without notice. Clients must tolerate unknown fields. * **Breaking changes** require a new major version, announced with a minimum 6-month deprecation window. * **Bug fixes** that alter response shape are treated as breaking. - name: Conventions x-displayName: Conventions description: > Conventions used across the entire Public API. ## Time and dates All timestamps are **ISO 8601 in UTC** unless explicitly noted: ``` 2026-01-20T13:45:00Z ``` Date-only fields (report ranges, billing periods) use `YYYY-MM-DD`. ## Identifiers * Resource IDs are positive integers. * Country IDs use **GeoNames** numeric IDs: `6252001` (US), `2635167` (GB). Full list: `GET /api/v2/common/lists/countries`. ## Currencies and monetary values * Currency codes follow **ISO 4217**: `USD`, `EUR`, `GBP`. * Monetary amounts have up to 4 decimal places: `12.5000`. Display rounding is the client's responsibility. ## Status values Many resources use a numeric `status` field: | Value | Meaning | |---|---| | `1` | Active | | `2` | Disabled / Inactive | | `3` | Pending review | | `4` | Rejected | Per-endpoint documentation lists the exact allowed values and any resource-specific additions. ## Booleans JSON booleans are always native `true` / `false`. Some legacy filters accept `1` / `0` as a fallback — prefer native booleans. ## Null and empty values * Optional fields absent from the record are returned as `null`, not omitted. * Empty collections are returned as `[]` (arrays) or `{}` (objects). * In `POST` / `PUT` bodies: sending `null` clears the field; omitting the key keeps the current value (unless noted in the endpoint description). ## Localisation Display strings (offer names, descriptions, creative captions) are returned in the network's configured primary language. There is no per-request locale override. - name: Affiliate / Profile x-displayName: Profile description: View and update affiliate account profile and basic info. - name: Affiliate / Dashboard x-displayName: Dashboard description: Aggregated network summary for the affiliate dashboard. - name: Affiliate / Campaigns x-displayName: Campaigns description: Manage tracking campaigns associated with offers. - name: Affiliate / Postbacks x-displayName: Postbacks description: Configure server-to-server postback URLs for conversion tracking. - name: Affiliate / Activity Log x-displayName: Activity Log description: Affiliate-scoped activity and audit log. - name: Affiliate / Billing / Balances x-displayName: Balances description: View affiliate balances and submit payout requests. - name: Affiliate / Billing / Invoices x-displayName: Invoices description: List affiliate invoices and download invoice PDFs. - name: Affiliate / Billing / Payment Methods x-displayName: Payment Methods description: Manage affiliate payment methods and supported currencies. - name: Affiliate / Billing / Preferences x-displayName: Billing Preferences description: View and update affiliate billing preferences. - name: Affiliate / Statistics / Reports x-displayName: Reports description: Aggregated statistics with flat and tree breakdowns. - name: Affiliate / Statistics / Clicks x-displayName: Clicks description: Click statistics and report options. - name: Affiliate / Statistics / Conversions x-displayName: Conversions description: Conversion statistics and report options. - name: Affiliate / Statistics / Players Operator x-displayName: Players (Operator) description: Export player data for operator integrations. - name: Affiliate / Statistics / Traders Broker x-displayName: Traders (Broker) description: Export trader data for broker integrations. - name: Manager / Dashboard x-displayName: Dashboard description: Top affiliates and top offers summaries for the network dashboard. - name: Manager / Activity Log x-displayName: Activity Log description: Network-wide activity and audit log. - name: Manager / Auth Tools x-displayName: Auth Tools description: Login link generation, 2FA login links, and password reset utilities. - name: Manager / Affiliates / Management x-displayName: Affiliates description: Create, list, view, and update affiliate accounts and filters. - name: Manager / Affiliates / Postbacks x-displayName: Affiliate Postbacks description: Manage postbacks at the affiliate level. - name: Manager / Affiliates / Promo Codes x-displayName: Promo Codes description: Manage affiliate promo codes individually or in bulk. - name: Manager / Campaigns x-displayName: Campaigns description: Manage tracking campaigns at the network level. - name: Manager / Billing x-displayName: Billing description: Network-level billing settings and payment methods. - name: Manager / Billing / Affiliate Billing x-displayName: Affiliate Billing description: Affiliate billing — balances, invoices, payment methods, preferences. - name: Manager / Billing / Commission Plans x-displayName: Commission Plans description: Create and assign commission plans to affiliates. - name: Manager / Statistics / Reports x-displayName: Reports description: Aggregated statistics — flat and tree breakdowns, columns config. - name: Manager / Statistics / Clicks x-displayName: Clicks description: Network-level click statistics. - name: Manager / Statistics / Conversions x-displayName: Conversions description: Network-level conversion statistics, including status changes. - name: Manager / Statistics / Logs x-displayName: Logs description: Raw click logs and inbound/outbound postback logs. - name: Manager / Tracking / Clicks x-displayName: Clicks description: Server-side click tracking — single and batch insert. - name: Manager / Tracking / Conversions x-displayName: Conversions description: Server-side conversion tracking and conversion lookups. - name: Manager / Tracking / Events x-displayName: Events description: Custom event updates. - name: Manager / Tracking / Promo Codes x-displayName: Promo Code Tracking description: Server-side promo-code tracking endpoints. - name: Manager / Statistics / Events x-displayName: Events description: >- Raw event-level data — registrations, deposits, withdrawals, bets, wins, and other industry-specific events. - name: Manager / Statistics / Players (Operator) x-displayName: Players (Operator) description: Network-level export of player data for operator integrations. - name: Manager / Statistics / Traders (Broker) x-displayName: Traders (Broker) description: Network-level export of trader data for broker integrations. - name: Common / Lists x-displayName: Reference Lists description: >- Static reference data — countries, categories, tags, tiers, traffic sources. paths: /api/v2/network/commission-plan: post: tags: - Manager / Billing / Commission Plans summary: Create commission plan description: > Creates a new commission plan with CPA, RevShare, CPL, CPC, FlatFee, and/or LotBasedFee entities. Each commission block (cpa, rev_share, cpl, cpc) requires `enabled: true` to activate, `type` to select the calculation method, and `commission` with the format matching the type. The flat_fee block has its own structure with `commission`, `period`, and `start_date`. Past dates are accepted for `flat_fee.commission.start_date`. Commission types disabled in company settings cannot be submitted. Dependent features are validated independently: `cpa.hold_period` follows the CPA hold-period setting, `cpl.hold_period` follows the CPL hold-period setting, `cap` follows the CPA cap setting, and `high_roller_policy_*` follows the RevShare setting. Deleted affiliates in `assigned_to` are ignored instead of triggering validation errors. **Important**: `product` is the offer ID. Do NOT use the format `{payout, revenue, currency}` — it creates a plan with empty (null) commission data. Always use `{enabled, type, commission}` format. operationId: postV2_networkCommissionPlan requestBody: required: true content: application/json: schema: type: object required: - title - product properties: title: type: string description: Commission plan name. status: type: integer description: Status ID (e.g. 1=active). product: type: integer description: Offer ID. currency: type: - string - 'null' description: >- Currency code (e.g. USD, EUR). Only accepted when native_currency_commissions global setting is ON. Null or omitted = Brand Currency. traffic_source_ids: type: - array - 'null' description: >- Traffic source IDs. Multi-select. `null` is accepted and treated as an empty array. items: type: integer traffic_approaches_ids: type: - array - 'null' description: >- Traffic approaches IDs. `null` is accepted and treated as an empty array. items: type: integer assigned_to: type: array items: type: integer description: >- Affiliate IDs. Deleted affiliates are ignored during validation and are not persisted. is_default: type: boolean description: Whether this is the default commission plan for the offer. is_exclusive: type: boolean description: Whether this plan is exclusive to assigned affiliates. internal_notes: type: string description: Internal notes for this commission plan. assign_to_landing_page: type: integer description: 1=all, 2=specific. landing_pages: type: array items: type: integer description: Offer URL IDs. available_on_marketplace: type: boolean geo: type: object properties: allowed: type: array items: type: integer denied: type: array items: type: integer cpa: type: object properties: enabled: type: boolean type: type: integer description: >- 1=Flat, 2=FlatByCountries, 3=Progressive, 4=ProgressiveByCountries, 6=FlatByProduct. commission: description: Format depends on `type`. See schema descriptions. oneOf: - $ref: '#/components/schemas/CommissionFlat' - $ref: '#/components/schemas/CommissionFlatByCountries' - $ref: '#/components/schemas/CommissionProgressive' - $ref: >- #/components/schemas/CommissionProgressiveByCountries - $ref: '#/components/schemas/CommissionFlatByProduct' qualifications: type: array items: type: object hold_period: type: integer rev_share: type: object properties: enabled: type: boolean type: type: integer description: >- 1=Flat, 2=FlatByCountries, 3=Progressive, 4=ProgressiveByCountries, 6=FlatByProduct. commission: description: Format depends on `type`. See schema descriptions. oneOf: - $ref: '#/components/schemas/CommissionFlat' - $ref: '#/components/schemas/CommissionFlatByCountries' - $ref: '#/components/schemas/CommissionProgressive' - $ref: >- #/components/schemas/CommissionProgressiveByCountries - $ref: '#/components/schemas/CommissionFlatByProduct' qualifications: type: array items: type: object based_on: type: integer description: >- 1=GGR (Gaming), 2=NGR (Gaming), 3=Revenue (Finance). Available values depend on platform vertical setting. negative_carryover: type: integer description: >- 1=Discard, 3=Deduct from Balance. Available when platform vertical is configured. high_roller_policy_enabled: type: boolean high_roller_policy_metric_type: type: integer high_roller_policy_winbin_threshold: type: number custom_fee_config: type: - object - 'null' description: >- Custom Admin Fee override per product. RevShare type only. properties: enabled: type: boolean description: Enable custom admin fee. Off by default. products: type: array description: >- Product fee rows. At least one required when enabled. items: type: object required: - fee properties: products: type: - array - 'null' description: >- Array of product IDs, or null for catch-all (All Other Products). Only one catch-all row allowed. items: type: integer fee: type: number minimum: 0 description: >- Admin fee as percentage (e.g. 10 = 10%). Must be >= 0. No duplicate product IDs across rows. cpl: type: object properties: enabled: type: boolean type: type: integer description: >- 1=Flat, 2=FlatByCountries, 3=Progressive, 4=ProgressiveByCountries, 6=FlatByProduct. commission: description: Format depends on `type`. See schema descriptions. oneOf: - $ref: '#/components/schemas/CommissionFlat' - $ref: '#/components/schemas/CommissionFlatByCountries' - $ref: '#/components/schemas/CommissionProgressive' - $ref: >- #/components/schemas/CommissionProgressiveByCountries - $ref: '#/components/schemas/CommissionFlatByProduct' hold_period: type: integer cpc: type: object properties: enabled: type: boolean type: type: integer description: >- 1=Flat, 2=FlatByCountries, 3=Progressive, 4=ProgressiveByCountries, 6=FlatByProduct. commission: description: Format depends on `type`. See schema descriptions. oneOf: - $ref: '#/components/schemas/CommissionFlat' - $ref: '#/components/schemas/CommissionFlatByCountries' - $ref: '#/components/schemas/CommissionProgressive' - $ref: >- #/components/schemas/CommissionProgressiveByCountries - $ref: '#/components/schemas/CommissionFlatByProduct' flat_fee: type: object description: >- Fixed recurring or one-time fee. Does NOT use `type` — always the same structure. properties: enabled: type: boolean commission: $ref: '#/components/schemas/FlatFeeCommission' lot_based_fee: type: object risk_management: type: object properties: enabled: type: boolean method: type: string event: type: string percentage: type: integer pattern: type: string conditions: type: array items: type: object example: title: string product: 1 status: 1 currency: USD traffic_source_ids: - 1 traffic_approaches_ids: - 1 assigned_to: - 1 responses: '201': description: Commission plan created. content: application/json: schema: type: object properties: status: type: string example: success code: type: integer example: 200 name: type: string example: OK message: type: string info: type: object description: Created commission plan details. '422': description: >- Validation error or attempt to use a commission type disabled in company settings. content: application/json: schema: type: object properties: status: type: string example: error code: type: integer example: 422 name: type: string example: Unprocessable Entity message: type: string info: type: object properties: errors: type: object components: schemas: CommissionFlat: type: object description: type=1. Fixed amount or percentage. required: - commission properties: commission: type: number CommissionFlatByCountries: type: object description: >- type=2. Different rates per country group. Countries identified by geoname_id (e.g. 6252001=US, 2635167=GB). properties: countries: type: array items: type: object required: - countries - commission properties: countries: type: array items: type: integer description: Array of geoname_id values. commission: type: number other: type: number description: Rate for countries not listed above. CommissionProgressive: type: object description: type=3. Progressive scale — rate increases as metric grows. required: - range_bands_by - range properties: range_bands_by: type: integer description: >- Metric ID from platform's CommissionPlanRangeBands table (e.g. conversions count, revenue sum). Platform-specific. range: type: array items: $ref: '#/components/schemas/ProgressiveRange' CommissionProgressiveByCountries: type: object description: type=4. Progressive scale per country group. required: - range_bands_by properties: range_bands_by: type: integer description: >- Metric ID from platform's CommissionPlanRangeBands table. Platform-specific. countries: type: array items: type: object properties: countries: type: array items: type: integer description: Array of geoname_id values. range: type: array items: $ref: '#/components/schemas/ProgressiveRange' other: type: array items: $ref: '#/components/schemas/ProgressiveRange' description: Progressive scale for countries not listed above. CommissionFlatByProduct: type: object description: type=6. Different rates per product group. properties: products: type: array items: type: object required: - products - commission properties: products: type: array items: type: integer description: Array of product IDs. commission: type: number other: type: number description: Rate for products not listed above. FlatFeeCommission: type: object description: >- Commission structure for flat_fee block. Does NOT use `type` — always this format. required: - commission - period - start_date properties: commission: type: number period: type: integer description: 1=one_time, 2=monthly, 3=yearly. start_date: type: string format: date description: YYYY-MM-DD. Past dates are accepted. ProgressiveRange: type: object description: Single range band in a progressive commission scale. required: - from - commission properties: from: type: integer to: type: integer description: Omit for the last (open-ended) range. commission: type: number securitySchemes: ApiKeyHeaderAuth: type: apiKey in: header name: X-API-Key description: >- Preferred authentication method. Pass the API key in the `X-API-Key` HTTP request header. The user account must have `api_status` enabled. ApiKeyAuth: type: apiKey in: query name: api-key description: >- Deprecated. Pass the API key as the `api-key` query parameter. Supported for backwards compatibility — migrate to the `X-API-Key` header instead. ````