AffiliateBase Affiliate Coupons API

openapi: 3.2.0
info:
  title: AffiliateBase API v1 Affiliate Coupons API
  version: 1.0.0
  description: 'Source-aligned OpenAPI contract for AffiliateBase `/api/v1` endpoints.


    Authentication: one of Bearer token, Basic API key auth, or `X-Api-Key`.

    Account context: required via `account_id` query param or `X-Account-Id` header.

    Write endpoints accept JSON request bodies and Rails-style form-encoded parameters;

    responses are JSON encoded. List endpoints use consistent `data` and

    `pagination` envelopes.


    Rate limits: 45 requests per 30 seconds per credential and 180 per 30 seconds per

    IP address, applied before authentication. A throttled request returns HTTP `429`

    with error code `TOO_MANY_REQUESTS` and `RateLimit-Limit`, `RateLimit-Remaining`,

    `RateLimit-Reset`, and `Retry-After` headers (sent on `429` responses only).


    Error codes: `MISSING_ACCOUNT_ID` (400), `INVALID_PARAMETER` (400), `UNAUTHORIZED` (401),

    `FORBIDDEN` (403), `NOT_FOUND` (404), `VALIDATION_ERROR` (422), `TOO_MANY_REQUESTS` (429).

    Payout endpoints also return operation-specific `422` codes: `PAYOUT_EXECUTION_FAILED`,

    `PAYOUT_RUN_CREATE_FAILED`, `PAYOUT_RUN_EXECUTION_FAILED`, `PAYOUT_RUN_REMEDIATION_FAILED`,

    `PAYOUT_EXPORT_CREATE_FAILED`, `PAYOUT_EXPORT_DOWNLOAD_FAILED`, `PAYOUT_EXPORT_DELETE_FAILED`,

    and `PAYOUT_EXPORT_SETTLEMENT_FAILED`.'
servers:
- url: https://app.affiliatebase.io
security:
- bearerAuth: []
- basicAuth: []
- apiKeyAuth: []
tags:
- name: Affiliate Coupons
paths:
  /api/v1/affiliates/{affiliate_id}/coupon:
    get:
      tags:
      - Affiliate Coupons
      operationId: getAffiliateCoupon
      summary: Get affiliate coupon
      parameters:
      - $ref: '#/components/parameters/AccountIdQuery'
      - $ref: '#/components/parameters/AccountIdHeader'
      - name: affiliate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Coupon payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '400':
          $ref: '#/components/responses/MissingAccountId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Affiliate Coupons
      operationId: createAffiliateCoupon
      summary: Create/ensure affiliate coupon
      parameters:
      - $ref: '#/components/parameters/AccountIdQuery'
      - $ref: '#/components/parameters/AccountIdHeader'
      - name: affiliate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: Optional explicit coupon token for promo-code migration from another platform or known-code setup.
                dry_run:
                  type: boolean
                  description: Preview the coupon creation impact without creating or syncing a coupon.
                idempotency_key:
                  type: string
                  description: Replays the prior create result for this affiliate when reused within the write window.
      responses:
        '201':
          description: Coupon created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Coupon'
        '200':
          description: Dry-run preview or idempotent replay
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Coupon'
                - $ref: '#/components/schemas/CouponWriteDryRun'
        '400':
          $ref: '#/components/responses/MissingAccountId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    patch:
      tags:
      - Affiliate Coupons
      operationId: regenerateAffiliateCoupon
      summary: Regenerate affiliate coupon
      parameters:
      - $ref: '#/components/parameters/AccountIdQuery'
      - $ref: '#/components/parameters/AccountIdHeader'
      - name: affiliate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: Optional explicit replacement token for the regenerated affiliate coupon.
                dry_run:
                  type: boolean
                  description: Preview regeneration impact without archiving or creating a coupon.
                idempotency_key:
                  type: string
                  description: Replays the prior regenerate result for this affiliate when reused within the write window.
      responses:
        '200':
          description: Coupon regenerated
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/Coupon'
                - $ref: '#/components/schemas/CouponWriteDryRun'
        '400':
          $ref: '#/components/responses/MissingAccountId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      tags:
      - Affiliate Coupons
      operationId: deleteAffiliateCoupon
      summary: Archive affiliate coupon
      parameters:
      - $ref: '#/components/parameters/AccountIdQuery'
      - $ref: '#/components/parameters/AccountIdHeader'
      - name: affiliate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                  description: Preview archive impact without archiving or deactivating the coupon.
                idempotency_key:
                  type: string
                  description: Replays the prior archive result for this affiliate when reused within the write window.
      responses:
        '204':
          description: Coupon archived
        '200':
          description: Dry-run archive preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponWriteDryRun'
        '400':
          $ref: '#/components/responses/MissingAccountId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/affiliates/{affiliate_id}/coupon/sync:
    post:
      tags:
      - Affiliate Coupons
      operationId: syncAffiliateCoupon
      summary: Sync coupon with provider
      parameters:
      - $ref: '#/components/parameters/AccountIdQuery'
      - $ref: '#/components/parameters/AccountIdHeader'
      - name: affiliate_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                force:
                  type: boolean
                  description: Force provider sync even when an existing external promotion code is present.
                dry_run:
                  type: boolean
                  description: Preview sync impact without calling the provider.
                idempotency_key:
                  type: string
                  description: Replays the prior sync result for this coupon when reused within the write window.
      responses:
        '200':
          description: Sync succeeded
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CouponSyncResponse'
                - $ref: '#/components/schemas/CouponWriteDryRun'
        '202':
          description: Sync accepted/skipped
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CouponSyncResponse'
        '400':
          $ref: '#/components/responses/MissingAccountId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /api/v1/affiliates/{affiliate_id}/promo_codes:
    parameters:
    - $ref: '#/components/parameters/AccountIdQuery'
    - $ref: '#/components/parameters/AccountIdHeader'
    - name: affiliate_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      tags:
      - Affiliate Coupons
      operationId: listAffiliatePromoCodes
      summary: List assigned codes or search the connected Stripe account
      description: Requires affiliate_coupons.read. With q, returns exact-code candidates; with discounts=true, returns valid Stripe discounts. Otherwise lists up to 100 assignments, newest first, including stopped assignments. The legacy singular coupon endpoint remains the campaign default.
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: discounts
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: promo_codes, candidates, or discounts array
          content:
            application/json:
              schema:
                type: object
                properties:
                  promo_codes:
                    type: array
                    items:
                      $ref: '#/components/schemas/AffiliatePromoCode'
                  candidates:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
                  discounts:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
    post:
      tags:
      - Affiliate Coupons
      operationId: assignAffiliatePromoCode
      summary: Preview or execute assignment or creation of an affiliate promo code
      description: Requires affiliate_coupons.write. dry_run defaults to true. Import fresh-reads an exact Stripe promotion-code ID and makes no Stripe mutation. mode=create creates a code using an existing Stripe coupon. Reuse the same Idempotency-Key after timeouts; a changed payload returns IDEMPOTENCY_CONFLICT. Customer-restricted and already-owned codes are rejected. No transfers, reactivation or historical backfill.
      parameters:
      - name: Idempotency-Key
        in: header
        description: Required for execution; stable per requested operation, at most 200 characters.
        schema:
          type: string
          maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                  - import
                  - create
                  default: import
                stripe_promotion_code_id:
                  type: string
                  description: Required for import.
                code:
                  type: string
                  maxLength: 500
                  pattern: ^[A-Za-z0-9-]+$
                  description: Required for create; preserved exactly.
                stripe_coupon_id:
                  type: string
                  description: Required for create.
                dry_run:
                  type: boolean
                  default: true
                idempotency_key:
                  type: string
                  maxLength: 200
      responses:
        '200':
          description: Assignment, replayed assignment, or dry_run preview; assignment is not verified conversion proof.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AffiliatePromoCode'
                - type: object
                  required:
                  - dry_run
                  - preview
                  properties:
                    dry_run:
                      type: boolean
                    preview:
                      type: object
                      additionalProperties: true
                    stripe_write:
                      type: boolean
        '422':
          description: Stable code and error fields. Includes CODE_ALREADY_ASSIGNED, CUSTOMER_RESTRICTED, OPERATION_PENDING, RECONCILIATION_REQUIRED and IDEMPOTENCY_CONFLICT. Retry uncertain operations with the original key only.
  /api/v1/affiliates/{affiliate_id}/promo_codes/{id}:
    parameters:
    - $ref: '#/components/parameters/AccountIdQuery'
    - $ref: '#/components/parameters/AccountIdHeader'
    - name: affiliate_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    - name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    patch:
      tags:
      - Affiliate Coupons
      operationId: refreshAffiliatePromoCode
      summary: Preview or refresh observed Stripe availability
      description: Requires affiliate_coupons.write. Set dry_run=false to persist the current provider observation. Stripe is read only.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Assignment and current provider preview
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePromoCode'
    delete:
      tags:
      - Affiliate Coupons
      operationId: stopAffiliatePromoCode
      summary: Preview or stop tracking new redemptions
      description: Requires affiliate_coupons.write. Set dry_run=false to stop tracking locally. Keeps the code redeemable in Stripe, retains history and established customer attribution. Repeated stops return the same stopped assignment. Available after Stripe disconnects.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dry_run:
                  type: boolean
                  default: true
      responses:
        '200':
          description: Assignment with stopped_at and stripe_discount_unchanged=true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AffiliatePromoCode'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      - code
      properties:
        error:
          type: string
        code:
          type: string
        details:
          oneOf:
          - type: 'null'
          - type: object
            additionalProperties: true
          - type: array
            items:
              type: string
    CouponWriteDryRun:
      type: object
      properties:
        dry_run:
          type: boolean
          enum:
          - true
        notice:
          type: string
        context:
          type: object
          additionalProperties: true
        impact:
          type: object
          additionalProperties: true
    AffiliatePromoCode:
      type: object
      properties:
        id:
          type: string
          format: uuid
        affiliate_id:
          type: string
          format: uuid
        campaign_id:
          type: string
          format: uuid
        code:
          type: string
          description: Exact customer-facing Stripe code text.
        tracking_token:
          type: string
          description: Opaque compatibility identifier; do not display as the redemption code.
        stripe_promotion_code_id:
          type: string
        stripe_coupon_id:
          type: string
        stripe_account_id:
          type: string
        livemode:
          type: boolean
        management:
          type: string
          enum:
          - imported
          - created
        assigned_at:
          type: string
          format: date-time
        stopped_at:
          type: string
          format: date-time
          nullable: true
        provider_status:
          type: string
          enum:
          - unknown
          - active
          - unavailable
        provider_checked_at:
          type: string
          format: date-time
          nullable: true
        discount:
          type: object
          additionalProperties: true
        restrictions:
          type: object
          nullable: true
          additionalProperties: true
        expires_at:
          type: integer
          nullable: true
        replayed:
          type: boolean
        dry_run:
          type: boolean
    CouponSyncResponse:
      allOf:
      - $ref: '#/components/schemas/Coupon'
      - type: object
        properties:
          sync:
            type: object
            additionalProperties: true
            properties:
              success:
                type: boolean
              skipped:
                type: boolean
              status:
                type: string
              reason:
                type: string
              error:
                type: string
              external_id:
                type: string
              replayed:
                type: boolean
    Coupon:
      type: object
      properties:
        id:
          type: string
          format: uuid
        affiliate_id:
          type: string
          format: uuid
        campaign_id:
          type: string
          format: uuid
        token:
          type: string
        external_id:
          oneOf:
          - type: 'null'
          - type: string
        sync_status:
          type: string
          enum:
          - pending
          - synced
          - skipped
          - failed
        sync_attempted_at:
          oneOf:
          - type: 'null'
          - type: string
            format: date-time
        synced_at:
          oneOf:
          - type: 'null'
          - type: string
            format: date-time
        sync_error_code:
          oneOf:
          - type: 'null'
          - type: string
        sync_error_message:
          oneOf:
          - type: 'null'
          - type: string
        leads:
          type: integer
        conversions:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          oneOf:
          - type: 'null'
          - type: string
            format: date-time
  responses:
    Forbidden:
      description: Authenticated but not authorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            code: FORBIDDEN
    TooManyRequests:
      description: API rate limit exceeded
      headers:
        RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests allowed in the current window.
        RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining in the current window.
        RateLimit-Reset:
          schema:
            type: integer
          description: Seconds until the current rate limit window resets.
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many API requests. Please retry shortly.
            code: TOO_MANY_REQUESTS
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not found
            code: NOT_FOUND
    ValidationError:
      description: Validation or state-transition error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation failed
            code: VALIDATION_ERROR
    MissingAccountId:
      description: Missing account context
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Account ID is required
            code: MISSING_ACCOUNT_ID
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid API Secret.
            code: UNAUTHORIZED
  parameters:
    AccountIdHeader:
      name: X-Account-Id
      in: header
      required: false
      schema:
        type: string
        format: uuid
      description: Account context header. Required unless `account_id` query param is supplied.
    AccountIdQuery:
      name: account_id
      in: query
      required: false
      schema:
        type: string
        format: uuid
      description: Account context. Required unless `X-Account-Id` is supplied.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
    basicAuth:
      type: http
      scheme: basic
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key