> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerodash.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Create free rounds bonus code

> Attaches a bonus code to an existing campaign for one specific player.

`userId` must be the same `accountId` your [Player authorization](/api-reference/callbacks/player) callback returns, and `currencyCode` must match the campaign currency.

`maxRounds` has to be defined either here or on the campaign — if neither sets it, the request is rejected.



## OpenAPI

````yaml api-reference/customer.json POST /api/v1/free-rounds/campaigns/codes
openapi: 3.1.0
info:
  title: Zero-Dash Customer API
  version: 1.0.0
  summary: >-
    Server-to-server API that operators call to list games, launch sessions and
    manage free rounds.
  description: >-
    Endpoints that **you (the operator) call on Zero-Dash**.


    Every request is authenticated with an HMAC-SHA512 signature over
    `apiPath|timestamp|data`. See [Request signature](/security/signature) for
    the algorithm and ready-made clients.


    All endpoints are RESTful, accept and return JSON, and are served over HTTPS
    with a valid TLS certificate.
  contact:
    name: Zero-Dash Integrations
    email: info@zerodash.studio
servers:
  - url: https://{host}
    description: The exact host is assigned to you during onboarding.
    variables:
      host:
        default: api.zerodash.studio
        description: >-
          Base host provided by Zero-Dash. A separate staging host is issued for
          certification.
security:
  - operatorId: []
    signature: []
    timestamp: []
tags:
  - name: Games
    description: Discover the game catalogue and open a player session.
  - name: Free Rounds
    description: Create and inspect free round campaigns and bonus codes.
paths:
  /api/v1/free-rounds/campaigns/codes:
    post:
      tags:
        - Free Rounds
      summary: Create free rounds bonus code
      description: >-
        Attaches a bonus code to an existing campaign for one specific player.


        `userId` must be the same `accountId` your [Player
        authorization](/api-reference/callbacks/player) callback returns, and
        `currencyCode` must match the campaign currency.


        `maxRounds` has to be defined either here or on the campaign — if
        neither sets it, the request is rejected.
      operationId: createFreeRoundsBonusCode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBonusCodeRequest'
            example:
              campaignCode: XMAS-2026
              userId: player1
              currencyCode: USD
              bonusCode: CODE1234
              maxRounds: 1
      responses:
        '201':
          description: Created. No response body.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateBonusCodeRequest:
      type: object
      required:
        - campaignCode
        - userId
        - currencyCode
        - bonusCode
      properties:
        campaignCode:
          type: string
          description: Campaign this bonus code belongs to.
        userId:
          type: string
          description: >-
            Player account ID. Must match the `accountId` returned by your
            Player authorization callback.
          examples:
            - player1
        currencyCode:
          type: string
          description: Player currency. Must equal the campaign currency.
          examples:
            - USD
        bonusCode:
          type: string
          description: Unique bonus code generated by you.
          examples:
            - CODE1234
        maxRounds:
          type: integer
          minimum: 1
          description: >-
            Rounds granted by this code. Required when the campaign does not
            define `maxRounds`.
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable explanation of the failure.
  responses:
    BadRequest:
      description: Invalid request payload or query format.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: invalid currency code
    Unauthorized:
      description: >-
        Missing, malformed, stale or mismatched signature — or a source IP
        outside your allowlist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: invalid signature
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: internal error
  securitySchemes:
    operatorId:
      type: apiKey
      in: header
      name: X-Operator
      description: Your operator identifier, issued by Zero-Dash during onboarding.
    signature:
      type: apiKey
      in: header
      name: X-Zd-Signature
      description: >-
        Hex-encoded `HMAC-SHA512(apiPath|timestamp|data, secretKey)`. See
        [Request signature](/security/signature).
    timestamp:
      type: apiKey
      in: header
      name: X-Zd-Timestamp
      description: >-
        Unix time in **milliseconds**, and the exact value signed. Requests
        older than 5 minutes are rejected.

````