FirstPromoter Rewards API - 4 operation(s) on the admin (api/v2/company) surface, from FirstPromoter's own published OpenAPI definition (3.0.0) indexed in https://docs.firstpromoter.com/llms.txt.
openapi: 3.0.0
info:
title: FirstPromoter Admin API - Rewards
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: []
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
nullable: true
description: Coupon code associated with the reward
editable:
type: boolean
description: Whether the reward is editable
hide_reward:
type: boolean
nullable: true
description: Whether the reward is hidden
provider_coupon_id:
type: string
nullable: true
description: ID of the provider coupon
duration:
type: string
enum:
- once
- forever
- repeating
- null
nullable: true
description: Duration type of the reward
duration_in_months:
type: integer
nullable: true
description: Duration in months
max_redemptions:
type: integer
nullable: true
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
enum:
- tier_commission_mode
- tier_override_mode
- tier_net_override_mode
- null
nullable: true
description: Mode of tier reward
tier_level:
type: integer
nullable: true
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
nullable: true
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