🎯Challenges
This page provides an exhaustive description of all the routes available for managing challenges. Each route is explained, with its parameters, required headers, possible responses and examples of use
➡️ Get all challenges from a location
➡️ Activate location challenge
💡 Models
Challenge
id
string
Unique ID for the challenge
✅
fyre_id
string
Unique Location ID in Fyre system
✅
brand_id
string
Unique ID of the brand
✅
brand_name
string
Name of the brand
✅
title
string
Title of the challenge
✅
description
string
Description of the challenge
✅
contact_email
string
Brand contact email
✅
logo_url
string
Logo URL in storage
❌
banner_url
string
Banner URL in storage
❌
terms_and_conditions
Array<string>
Terms and conditions
❌
terms_and_conditions_url
string
URL to term and conditions document
❌
start_date
string
Challenge start date format ISO 8601
✅
end_date
string
Challenge end date format ISO 8601
✅
sales
{
[referential_ref: string]: LocationChallengeSalesProduct
}
A map of product level sales data for this challenge. Each key represents a product id. Each value contains the current sales progress for that specific product, including quantity and revenue during the challenge period. For uplift challenges, the object also includes the quantity and revenue from the same period last year, which serve as the baseline for calculating the uplift.
❌
accepted_at
string
Date when the challenge was accepted format ISO 8601
❌
completed_at
string
Date when the challenge was completed format ISO 8601
❌
published_at
string
Date when the challenge was published format ISO 8601
❌
created_at
string
Date when the challenge was created format ISO 8601
✅
updated_at
string
Date when the challenge was updated format ISO 8601
❌
ChallengeGoalType Enum
amount
The goal is to reach a specific revenue amount during the challenge period. The challenge is completed when the location generates at least the target revenue
quantity
The goal is to reach a specific quantity sold during the challenge period. The challenge is completed when the location sells at least the target number of units
uplift
The goal is to achieve growth compared to the same period from the previous year. When the challenge type is uplift, the target represents a percentage increase. The location must sell the required percentage more in quantity than it did during the same period last year. The challenge is completed when the current period quantity is at least N percent higher than the quantity from the matching period a year earlier.
ChallengeProduct
referential_ref
string
ID of the product in brands system
✅
name
string
Name of the product
✅
image_url
string
Image URL of the product
❌
LocationChallengeStatus Enum
published
Challenge status is set as "published" once the brand published it
accepted
Challenge status is set as "accepted" if location has accepted to participate in a challenge
completed
Challenge status is set as "completed" if location has reached the challenge goal
expired
The challenge status is set to "expired" if the challenge has ended, the location did not meet the goal in time, or the location did not participate in the challenge.
disabled
The challenge status is set to "disabled" when the brand has published the challenge, but the location's access has been revoked.
LocationChallengeGoals
quantity
number
The target quantity the location needs to reach during the challenge period. This value is used when the challenge goal type is quantity or uplift.
❌
revenue
number
The target revenue the location needs to reach during the challenge period. This value is only used when the challenge goal type is amount.
❌
LocationChallengeSalesProduct
quantity
number
The total number of units sold for this product during the active challenge period
✅
revenue
number
The total revenue generated by this product during the active challenge period.
✅
previous_quantity
number
The total number of units sold for this product during the same period last year. This value is used as the baseline for uplift challenges, where the location must sell more units than this historical benchmark.
❌
previous_revenue
number
The total revenue generated by this product during the same period last year. This field can be used for analytics, visualisations, or reporting. It is not used for current challenge validation unless the challenge logic explicitly references revenue uplift.
❌
LocationChallengesFilterInput
status
Array<LocationChallengeStatus>
When provided, it will return only challenges that match the specified status.
❌
brand_id
Array<string>
When provided, it will return only challenges that were published by a speicifc brand
❌
📩 Get all challenges from a location
This route enables you to retrieve the challenges linked to a specific location. It provides a detailed list of all current challenges, along with their descriptions, statuses, and other relevant details.
GET https://api.fyre.app/api/v1/locations/{fyre_id}/challenges
Requires permission:
challenges.list
Route Params⬇️
Query Params
filter
LocationChallengesFilterInput
If provided, it will filter the location challenges by status and/or brand.
❌
📤 Responses
📖 Route Params Example
📩 Get a location challenge
This route allows you to retrieve details of a specific challenge linked to a location. By accessing this route, you will obtain full information on the challenge, such as its status, requirements and the results associated with the location concerned.
GET https://api.fyre.app/api/v1/locations/{fyre_id}/challenges/{challenge_id}
Requires permission:
challenges.read
Route Params⬇️
📤 Responses
📖 Params example
📫 Activate location challenge
This route allows you to accept a challenge associated with a specific location. Once accepted, the challenge will begin tracking sales for that location in real time
POSThttps://api.fyre.app/api/v1/locations/{fyre_id}/challenges/{challenge_id}/activate
Requires permission:
challenges.accept
Payload ⬇️
📤 Responses
📖 Payload example
Last updated