FirstPromoter Rewards API

openapi: 3.2.0
info:
  title: FirstPromoter Admin Rewards API
  version: 1.0.0
  description: Admin API endpoints for managing rewards in FirstPromoter
servers:
- url: https://api.firstpromoter.com/api/v2/company
  description: Staging server
security:
- BearerAuth: []
tags:
- name: Rewards
paths:
  /rewards:
    get:
      summary: Get available rewards
      tags:
      - Rewards
      description: "Get available rewards for current company \n <Tip>**HTTP Request** <br/>`GET https://api.firstpromoter.com/api/v2/company/rewards`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: query
        name: scope
        schema:
          type: string
          enum:
          - promoters
          - referrals
        description: Scope of the rewards
      responses:
        '200':
          description: List of rewards
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Reward'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid params
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create reward
      tags:
      - Rewards
      description: "Create rewards for current company \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/rewards`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - is_promoter_reward
              - schemas
              properties:
                name:
                  type: string
                  description: Name of the reward
                is_promoter_reward:
                  type: boolean
                  description: Whether the reward is for promoters or referrals
                promoter_reward_type:
                  type: string
                  enum:
                  - sale
                  - tier
                  - target
                  - custom
                  description: Type of promoter reward. Required only for promoter rewards.
                tier_reward_mode:
                  type: string
                  enum:
                  - tier_commission_mode
                  - tier_override_mode
                  - tier_net_override_mode
                  description: Mode of tier reward. Required only for tier rewards.
                tier_level:
                  type: integer
                  description: Level of tier reward. Required only for tier rewards. Must be greater than or equal to 2.
                coupon:
                  type: string
                  description: Coupon code associated with the reward
                hide_reward:
                  type: boolean
                  description: Whether to hide the reward
                duration:
                  type: string
                  enum:
                  - once
                  - forever
                  - repeating
                  description: Duration type of the reward
                duration_in_months:
                  type: integer
                  description: Duration in months. Required when duration is 'repeating'.
                max_redemptions:
                  type: integer
                  description: Maximum number of redemptions allowed
                should_create_provider_coupon:
                  type: boolean
                  description: Whether to create a provider coupon
                new_customers_only:
                  type: boolean
                  description: Whether the reward is only for new customers
                provider_coupon_id:
                  type: string
                  description: ID of the provider coupon
                schemas:
                  type: array
                  description: Reward schemas
                  items:
                    type: object
                    required:
                    - unit
                    - amount
                    - flat_amount
                    properties:
                      unit:
                        type: string
                        enum:
                        - cash
                        - free_months
                        - credits
                        - points
                        - mon_discount
                        - discount_per
                        description: Unit of the reward
                      amount:
                        type: number
                        description: Amount of the reward
                      flat_amount:
                        type: boolean
                        description: Whether the amount is flat or percentage
                      rules:
                        type: array
                        description: Rules for the reward schema
                        items:
                          type: object
                          required:
                          - type
                          - condition
                          - value
                          - operator
                          properties:
                            type:
                              type: string
                              enum:
                              - customer_sales_count
                              - customer_age_in_months
                              - promoter_campaign_customers_count
                              - promoter_campaign_revenue
                              description: Type of the rule
                            condition:
                              type: string
                              enum:
                              - less than
                              - less than or equal to
                              - equal to
                              - greater than or equal to
                              - greater than
                              - multiple of
                              description: Condition of the rule
                            filter_by:
                              type: string
                              enum:
                              - price
                              - null
                              description: Filter by attribute
                            value:
                              type: number
                              description: Value for the condition
                            operator:
                              type: string
                              enum:
                              - and
                              - or
                              description: Logical operator to combine with other rules
      responses:
        '200':
          description: Reward created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rewards/{id}:
    put:
      summary: Update reward
      tags:
      - Rewards
      description: "Update reward for current company \n <Tip>**HTTP Request** <br/>`PUT https://api.firstpromoter.com/api/v2/company/rewards/{id}`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: ID of the reward to update
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the reward
                is_promoter_reward:
                  type: boolean
                  description: Whether the reward is for promoters or referrals
                promoter_reward_type:
                  type: string
                  enum:
                  - sale
                  - tier
                  - target
                  - custom
                  description: Type of promoter reward
                tier_reward_mode:
                  type: string
                  enum:
                  - tier_commission_mode
                  - tier_override_mode
                  - tier_net_override_mode
                  description: Mode of tier reward. Required only for tier rewards.
                tier_level:
                  type: integer
                  description: Level of tier reward. Required only for tier rewards.
                coupon:
                  type: string
                  description: Coupon code associated with the reward
                hide_reward:
                  type: boolean
                  description: Whether to hide the reward
                duration:
                  type: string
                  enum:
                  - once
                  - forever
                  - repeating
                  description: Duration type of the reward
                duration_in_months:
                  type: integer
                  description: Duration in months. Required when duration is 'repeating'.
                max_redemptions:
                  type: integer
                  description: Maximum number of redemptions allowed
                should_create_provider_coupon:
                  type: boolean
                  description: Whether to create a provider coupon
                new_customers_only:
                  type: boolean
                  description: Whether the reward is only for new customers
                provider_coupon_id:
                  type: string
                  description: ID of the provider coupon
                schemas:
                  type: array
                  description: Reward schemas
                  items:
                    type: object
                    properties:
                      unit:
                        type: string
                        enum:
                        - cash
                        - free_months
                        - credits
                        - points
                        - mon_discount
                        - discount_per
                        description: Unit of the reward
                      amount:
                        type: number
                        description: Amount of the reward
                      flat_amount:
                        type: boolean
                        description: Whether the amount is flat or percentage
                      rules:
                        type: array
                        description: Rules for the reward schema
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - customer_sales_count
                              - customer_age_in_months
                              - promoter_campaign_customers_count
                              - promoter_campaign_revenue
                              description: Type of the rule
                            condition:
                              type: string
                              enum:
                              - less than
                              - less than or equal to
                              - equal to
                              - greater than or equal to
                              - greater than
                              - multiple of
                              description: Condition of the rule
                            filter_by:
                              type: string
                              enum:
                              - price
                              - null
                              description: Filter by attribute
                            value:
                              type: number
                              description: Value for the condition
                            operator:
                              type: string
                              enum:
                              - and
                              - or
                              description: Logical operator to combine with other rules
      responses:
        '200':
          description: Reward updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /rewards/{id}/hide:
    post:
      summary: Hide reward
      tags:
      - Rewards
      description: "Hide reward for current company \n <Tip>**HTTP Request** <br/>`POST https://api.firstpromoter.com/api/v2/company/rewards/{id}/hide`</Tip>"
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - in: path
        name: id
        required: true
        schema:
          type: integer
        description: ID of the reward to hide
      responses:
        '200':
          description: Reward hidden successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    AccountId:
      name: Account-ID
      in: header
      required: true
      description: Account identifier that specifies which account is making the request
      schema:
        type: string
        example: acc_123456
  schemas:
    Reward:
      type: object
      properties:
        id:
          type: integer
          description: Id of the reward
        name:
          type: string
          description: Name of the reward
        is_promoter_reward:
          type: boolean
          description: Whether the reward is for promoters or referrals
        promoter_reward_type:
          type: string
          enum:
          - sale
          - tier
          - target
          - null
          description: Type of promoter reward
        coupon:
          type:
          - string
          - 'null'
          description: Coupon code associated with the reward
        editable:
          type: boolean
          description: Whether the reward is editable
        hide_reward:
          type:
          - boolean
          - 'null'
          description: Whether the reward is hidden
        provider_coupon_id:
          type:
          - string
          - 'null'
          description: ID of the provider coupon
        duration:
          type:
          - string
          - 'null'
          enum:
          - once
          - forever
          - repeating
          - null
          description: Duration type of the reward
        duration_in_months:
          type:
          - integer
          - 'null'
          description: Duration in months
        max_redemptions:
          type:
          - integer
          - 'null'
          description: Maximum number of redemptions allowed
        new_customers_only:
          type: boolean
          description: Whether the reward is only for new customers
        created_at:
          type: string
          format: date-time
          description: Date and time when the reward was created
        updated_at:
          type: string
          format: date-time
          description: Date and time when the reward was last updated
        provider:
          type: string
          description: Provider of the reward
        tier_reward_mode:
          type:
          - string
          - 'null'
          enum:
          - tier_commission_mode
          - tier_override_mode
          - tier_net_override_mode
          - null
          description: Mode of tier reward
        tier_level:
          type:
          - integer
          - 'null'
          description: Level of tier reward
        schemas:
          type: array
          description: Reward schemas
          items:
            type: object
            properties:
              unit:
                type: string
                enum:
                - cash
                - free_months
                - credits
                - points
                - mon_discount
                - discount_per
                description: Unit of the reward
              amount:
                type: number
                description: Amount of the reward
              flat_amount:
                type: boolean
                description: Whether the amount is flat or percentage
              rules:
                type: array
                description: Rules for the reward schema
                items:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - customer_sales_count
                      - customer_age_in_months
                      - promoter_campaign_customers_count
                      - promoter_campaign_revenue
                      description: Type of the rule
                    condition:
                      type: string
                      enum:
                      - less than
                      - less than or equal to
                      - equal to
                      - greater than or equal to
                      - greater than
                      - multiple of
                      description: Condition of the rule
                    filter_by:
                      type:
                      - string
                      - 'null'
                      description: Filter by attribute
                    value:
                      type: number
                      description: Value for the condition
                    operator:
                      type: string
                      enum:
                      - and
                      - or
                      description: Logical operator to combine with other rules
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
          example: forbidden
    ValidationError:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          description: Validation errors
          additionalProperties:
            type: array
            items:
              type: string
        code:
          type: string
          description: Error code
          example: invalid_record
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Access token passed as a Bearer token in the Authorization header
    accountId:
      type: apiKey
      in: header
      name: Account-ID
      description: Account ID required with bearer token