# Objects
## `Campaign`
The `Campaign` Object contains detailed information about a GrowSurf program.
| Name | Type | Description |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| **id** | `string` | The unique identifier of the program |
| **name** | `string` | The program name |
| **type** | `string` | The program type: `REFERRAL`, `AFFILIATE` |
| **referralCount** | `integer` | The total referral count |
| **participantCount** | `integer` | The total participant count |
| **impressionCoun**t | `integer` | The total number of impressions† |
| **winnerCount** | `integer` | The total number of winners†† |
| **inviteCount** | `integer` | The total number of invites sent by participants |
| **status** | `string` | The program status: `DRAFT`, `IN_PROGRESS`, `COMPLETE`, `DELETED` |
| **currencyISO** | `string` | The program currency as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code (e.g., `USD`, `GBP`) |
| **rewards** | `array` | The list of [Rewards](#reward) associated with the program |
{% hint style="info" %}
† **Impressions** = the collective amount of times participants' unique referral links have been viewed.\
\
†† **Winners** = all participants with at least one approved reward (includes referrers and referred friends).
{% endhint %}
Campaign Object Example
```json
{
"id": "abc123",
"name": "Middle Out Compression Campaign",
"type:" "REFERRAL",
"referralCount": 121,
"participantCount": 199,
"impressionCount": 199,
"winnerCount": 1,
"inviteCount": 237,
"status": "IN_PROGRESS",
"rewards": [
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"order": 1,
"couponCode": "PROMO_20_OFF",
"imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"rewardForTierA": 50,
"rewardForTierB": 100,
"bonusPeriodMessage": "Offering 2x referral bonuses in our promotion period!"
},
// Only for affiliate programs:
"commissionStructure": {
"amount": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 3,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": 12,
"approvalRequired": false,
"percent": 50,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": "USD",
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": "USD",
"introDuration": "REPEATING",
"introDurationInMonths": 2
}
}
]
}
```
***
## `Reward`
The `Reward` Object (also known as `CampaignReward`) contains detailed reward information about a single reward for a program.
{% hint style="info" %}
**Note:** This `Reward` Object is different from a [`ParticipantReward`](#participantreward) Object, which is a reward earned by a participant.
{% endhint %}
| Name | Type | Description |
| ------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **id** | `string` | The unique identifier of the program reward.
You can find this ID from Program Editor > 1. Rewards and clicking the reward.
|
| **title** | `string` | The title of the program reward. Only used for internal purposes and never displayed to participants. |
| **type** | `string` | The reward type: `SINGLE_SIDED`,`DOUBLE_SIDED`,`MILESTONE`, `LEADERBOARD`, `AFFILIATE` |
| **description** | `string` | The reward description for the referrer ([see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfdiiPAfYHybi8E12al%2F-Lfdm98OGtk0q71firGM%2FScreen%20Shot%20on%202019-05-24%20at%2020%3A19%3A46.png?alt=media\&token=4102da68-c465-4270-ba25-8a7724be2821)) |
| **referralDescription** | `string` | The reward description for the referred friend (only applicable for double-sided reward types -- [see image](https://blobscdn.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LeklWo0yn03AhWro2Ux%2F-LfdiiPAfYHybi8E12al%2F-Lfdm98OGtk0q71firGM%2FScreen%20Shot%20on%202019-05-24%20at%2020%3A19%3A46.png?alt=media\&token=4102da68-c465-4270-ba25-8a7724be2821)) |
| **referredRewardUpfront** | `boolean` | Only applies to double-sided rewards. When `true`, the referred friend's reward is delivered upfront as an upfront discount and no [`ParticipantReward`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#participantreward) is created for them when the referral triggers. |
| **isUnlimited** | `boolean` | `true` if this reward can be earned by a single participant an unlimited amount of times |
| **limit** | `integer` | The number of times a participant can earn this reward (this property is overridden if `isUnlimited` is `true`) |
| **conversionsRequired** | `integer` | The number of referrals a participant must make to earn this reward |
| **limitDuration** | `string` | Whether the reward can be earned in total or on a monthly basis.
Options: "IN\_TOTAL", "PER\_MONTH"
|
| **numberOfWinners** | `integer` | The maximum number of total participants that can earn this reward if type is LEADERBOARD.
If limitDuration is PER\_MONTH, this is the manimum number of total participants who can earn the reward in the given month.
|
| **imageUrl** | `string` | The reward image URL |
| **couponCode** | `string` | A coupon code |
| **order** | `integer` | If there are multiple rewards, this represents the order in which the reward should be displayed.
This value is null by default, until set within the Design step of the program editor.
|
| **nextMilestonePrefix** | `string` | The text that can be used for UI purposes that will be displayed in front of a participant's referral count number (e.g., "You are only"). Applicable for milestone rewards (when `type === 'MILESTONE'`). |
| **nextMilestoneSuffix** | `string` | The text that can be used for UI purposes that will be displayed behind a participant's referral count number (e.g., "referrals away from receiving a nice reward!"). Applicable for milestone rewards (when `type === 'MILESTONE'`). |
| **metadata** | `object` | The reward metadata. |
| commissionStructure
Affiliate programs only
| `object` | The reward commission structure. |
Reward Object Example
```json
{
"id": "crew_xyz789",
"type": "DOUBLE_SIDED",
"description": "Refer a friend and get a Pied Piper T-Shirt",
"referralDescription": "Join and receive middle out compression algorithm",
"isUnlimited": false,
"limit": 1,
"conversionsRequired": 1,
"numberOfWinners": 3,
"limitDuration": "IN_TOTAL",
"order": 1,
"couponCode": "PROMO_20_OFF",
"imageUrl": "http://res.cloudinary.com/growsurf/image/upload/v1552764861/development/hxdcjrayfhksvxu5u6oz.png",
"nextMilestonePrefix": "You are only",
"nextMilestoneSuffix": "referrals away from receiving a nice reward!",
"metadata": {
"rewardForTierA": 50,
"rewardForTierB": 100,
"bonusPeriodMessage": "Offering 2x referral bonuses in our promotion period!"
},
// Only for affiliate programs:
"commissionStructure": {
"amount": null,
"event": "SALE",
"type": "PERCENT",
"minPaidReferrals": 3,
"holdDuration": 30,
"duration": "FOREVER",
"durationInMonths": 12,
"approvalRequired": false,
"percent": 50,
"hasMaxAmount": false,
"maxAmount": null,
"maxAmountISO": "USD",
"hasIntro": false,
"introType": null,
"introPercent": null,
"introAmount": null,
"introAmountISO": "USD",
"introDuration": "REPEATING",
"introDurationInMonths": 2
}
}
```
***
## `Participant`
The `Participant` Object contains detailed information about a program participant.
| Name | Type | Description |
| ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `integer` | The unique identifier of the participant |
| **firstName** | `string` | The first name of the participant |
| **lastName** | `string` | The last name of the participant |
| **referralCount** | `integer` | The total number of referrals made by the participant |
| **monthlyReferralCount** | `integer` | The total number of referrals made this month by the participant (resets at the end of the month) |
| **prevMonthlyReferralCount** | `integer` | The total number of referrals made the previous month by the participant. |
| **shareUrl** | `string` | The unique share URL of the participant |
| **email** | `string` | The email of the participant |
| **createdAt** | `timestamp` | The date the participant was added to the program (UTC milliseconds) |
| **fraudRiskLevel** | `string` | A value that represents the integrity of the participant: `LOW`, `MEDIUM`,`HIGH` |
| **fraudReasonCode** | `string` | A value representing the reason for the fraudRiskLevel:
- UNIQUE\_IDENTITY = They have a unique identity (no other participant has the same identity as them).
- DUPLICATE\_EMAIL = Their email is not unique, and is identical with another participant's email (e.g., = ).
- DUPLICATE\_IDENTITY
= Their identity is not unique, and matches that of another participant's.
-
DUPLICATE\_IDENTITY\_EXCESSIVE = Within a small window of time, they had an excessive amount of participants that they referred who also shared the same IP address as them.
- EMAIL\_FRAUD = Their email was found to match that of another participant's when updated in a connected integration (e.g., Stripe, Chargebee, Recurly).
- SIMILAR\_EMAIL = Their browser fingerprint matches another participant's, and their email looks suspiciously similar (e.g., , )
- SIMILAR\_FIRST\_NAME = Their browser fingerprint matches another participant's, and their first name looks suspiciously similar.
- SIMILAR\_LAST\_NAME = Their browser fingerprint matches another participant's, and their last name looks suspiciously similar.
- REFERRAL\_EMAIL\_PATTERN = (Status for a referred person) Their email matched a similar pattern with their referrer's email.
- REFERRAL\_CHAIN\_FRAUD = (Status for both a referrer or referred person) The referred person's email and/or other characteristics matched a similar pattern with other referrals that the referrer made, indicating a fraud ring.
- REFERRAL\_VELOCITY\_FRAUD = (Status for both a referrer or referred person) The referrer made an excessive amount of referrals in a short period of time.
- DOMAIN\_CLUSTERING\_FRAUD = (Status for both a referrer or referred person) The referrer made an excessive amount of referrals who share the same suspicious domain in a short period of time.
- MANUAL\_UPDATE = They were manually marked as a fraudster from the GrowSurf dashboard.
- WHITELISTED = They were allowed to join the program because one of their properties matched a whitelisted value.
- BLACKLIST\_MATCH = They were not allowed to join the program because one of their properties matched a blacklisted value.
- BLOCKED\_IP = They were not allowed to join the program because their IP address was recently blocked by antifraud IP throttling.
- REFERRER\_HIGH\_RISK = They were not allowed to join the program because their referrer was a high-risk fraudster.
|
| **isWinner** | `boolean` | `true` if the participant has earned one or more rewards |
| **shareCount** | `object` | An Object containing various counts representing the number of times the participant has shared their referral link.
For example: email, facebook, pinterest, twitter
|
| **impressionCount** | `integer` | The total number of impressions the participant has made |
| **uniqueImpressionCount** | `integer` | The total number of unique impressions the participant has made |
| **referrals** | `array` | A list of `Participant` IDs who were successfully referred by the participant. The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made). |
| **monthlyReferrals** | `array` | A list of `Participant` IDs who successfully referred by the participant this month (resets at the end of the month). The array will be limited to a size of 100 and will contain the IDs of the most recently referred friends (The last 100 referrals made). |
| **referralSource** | `string` | The source of how the participant joined the program: `PARTICIPANT`, `DIRECT`,`IMPORT`,`MANUAL`, `DELETED_PARTICIPANT`. |
| **referralStatus** | `string` | If the participant was referred, this value represents their referrer's status in receiving the referral credit: CREDIT\_PENDING, CREDIT\_AWARDED, CREDIT\_EXPIRED.
This property is only applicable if the participant was referred into the program.
|
| **referrer** | `object` | An Object containing the participant's referrer information.
This property is only applicable if the participant was referred into the program.
|
| **referredBy** | `string` | The ID of the referrer.
This property is only applicable if the participant was referred into the program.
|
| **rewards** | `array` | A list of program `Reward` IDs that the participant has earned |
| **notes** | `string` | A value containing internal notes about the participant, added via the [GrowSurf Dashboard](https://growsurf.com/dashboard) |
| **metadata** | `object` | An Object containing any custom key-value data, useful when you want to save additional data for the participant (e.g., company, companySize)
Metadata is never used by GrowSurf and usage is optional. Metadata is returned only in REST API calls, and never returned in JavaScript Web API calls. For more information, please see API Guidelines.
|
| **rank** | `integer` | The rank of the participant. |
| **monthlyRank** | `integer` | The monthly rank of the participant.
This rank resets to 0 at the end of each month.
|
| **prevMonthlyRank** | `integer` | The previous monthly rank of the participant.
This rank will not be be returned if the participant did not exist within your program during the previous month.
|
| **vanityKeys** | `array` | The list of vanity keys that the participant has. |
Participant Object Example
```json
{
"id": "f8g9nl",
"firstName": "Gavin",
"lastName": "Belson",
"referralCount": 2,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 0,
"rank": 10001,
"monthlyRank": 20001,
"monthlyRank": -1,
"shareUrl": "https://piedpiper.com?grsf=f8g9nl",
"email": "gavin@hoolie.com",
"createdAt": 1552404738928,
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 10,
"facebook": 1,
"pinterest": 1,
"twitter": 11
},
"impressionCount": 2,
"uniqueImpressionCount": 2,
"inviteCount": 3,
"referrals": [
"i9g2bh",
"xua4sq"
],
"monthlyReferrals": [
"i9g2bh",
"xua4sq"
],
"referralSource": "PARTICIPANT",
"referralStatus": "CREDIT_AWARDED",
"referrer": {
"id": "h8kp6l",
"firstName": "Richard",
"lastName": "Hendricks",
"referralCount": 5,
"monthlyReferralCount": 2,
"prevMonthlyReferralCount": 100,
"rank": 100,
"monthlyRank": 110,
"prevMonthlyRank": 10,
"shareUrl": "https://piedpiper.com?grsf=h8kp6l",
"email": "richard@piedpiper.com",
"createdAt": 1552402661449,
"referralSource": "DIRECT",
"fraudRiskLevel": "LOW",
"fraudReasonCode": "UNIQUE_IDENTIY",
"isWinner": true,
"shareCount": {
"email": 20,
"facebook": 11,
"linkedin": 0,
"pinterest": 3,
"twitter": 12
},
"impressionCount": 14,
"uniqueImpressionCount": 11,
"inviteCount": 12,
"referrals": [
"0dveu7",
"f8g9nl",
"j0hbym",
"m5xm9l",
"w01fil"
],
"monthlyReferrals": [
"m5xm9l",
"w01fil"
]
},
"metadata": {
"company": "Hooli, Inc",
"companySize": 10000
},
"rewards": [
{
"id": "prew_dgaiuk",
"rewardId": "oe1cjt",
"status": "FULFILLED",
"unread": true,
"isReferrer": true,
"isAvailable": true,
"approved": true,
"isFulfilled": true,
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
],
"vanityKeys": [
"gavin-f8g9nl"
]
}
```
***
## `ParticipantReward`
The `ParticipantReward` Object represents a reward that the participant has earned.
{% hint style="info" %}
**Notes:**
* This `ParticipantReward` Object is different from a program [`Reward`](#reward) Object and contains information that is only pertinent to the participant that earned the reward.
* In [Webhooks](https://docs.growsurf.com/automate-rewards/webhooks), `ParticipantReward` Objects will also contain program `Reward` Object details.
{% endhint %}
| Name | Type | Description |
| --------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `string` | The unique identifier of the participant's reward.
This will be different for every new reward that the participant earns. You can find this ID by going to your admin dashboard and viewing the participant's rewards.
|
| **rewardId** | `string` | The ID of the [`CampaignReward`](#reward) that this participant has earned |
| **status** | `string` | The status of the participant's reward: `PENDING`,`FULFILLED` |
| **isReferrer** | `boolean` | true if the participant earned the reward as the referrer.
false if the participant earned the reward as the referred friend (only applicable in double-sided reward types).
|
| **isAvailable** | `boolean` | `true` if the reward is available for participant to claim or redeem |
| **approved** | `boolean` | `true` if the participant's reward has been approved |
| **approvedAt** | `timestamp` | The date and time the participant's reward was approved for this participant (UTC milliseconds). It is `null` for unapproved rewards. |
| **isFulfilled** | `boolean` | `true` if the participant's reward has been fulfilled. |
| **fulfilledAt** | `timestamp` | The date and time the reward was fulfilled for this participant (UTC milliseconds). It is `null` for either unapproved or unfulfilled rewards. |
| **referredId** | `string` | The id of the friend that was referred |
| **referrerId** | `string` | The id of the participant that made the referral |
| **unread** | `boolean` | `false` if the participant has not seen the reward in a GrowSurf window otherwise `false`. |
ParticipantReward Object Example
```json
{
"id": "prew_rr35mg",
"rewardId": "crew_c6w1qo",
"status": "PENDING",
"unread": true,
"approved": false,
"approvedAt": null,
"fulfilledAt": null,
"isReferrer": true,
"isAvailable": false,
"isFulfilled": false,
"referredId": "xh345d",
"referrerId": "f8g9nl"
}
```
***
## `ParticipantCommission`
Affiliate programs only
The `ParticipantCommission` Object contains detailed information about a commission that was generated for a \[referrer] participant in an affiliate program.
{% hint style="success" %}
**Currency Exchange Note:**
If the referral makes a payment in a currency different from your program's currency (`Campaign.currencyISO`), the following foreign currency exchange-related fields can be used to normalize commission data for accounting/reporting purposes: `amountInCampaignCurrency`, `saleAmountInCampaignCurrency`, `exchangeRate`, `campaignCurrencyISO`, and `exchangeRateAt`.\
\
For example, if your campaign's currency is set to `USD` but a referral makes a payment in `CAD`, the generated commission will have `amountInCampaignCurrency` as the `USD` equivalent of the `CAD` payment.
{% endhint %}
| Name | Type | Description |
| -------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id** | `string` | The unique identifier of the participant commission. |
| **referrerId** | `string` | The participant ID of the referrer who earned the commission. |
| **referredId** | `string` | The participant ID of the referred friend (the conversion that triggered the commission). |
| **amount** | `integer` | Commission amount (what the affiliate earned) in the currency’s smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. |
| **currencyISO** | `string` | The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the commission (e.g., `USD`, `GBP`) |
| **saleAmount** | `integer` | The sale amount (from the transaction that the referral paid) in the currency’s smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. |
| **status** | `string` | Current lifecycle state of the commission. Possible values: `PENDING`, `APPROVED`, `PAID`, `REVERSED`. |
| **createdAt** | `timestamp` | UTC timestamp (in milliseconds) when the commission record was created. |
| **approvedAt** | `timestamp` | UTC timestamp (in milliseconds) when the commission was explicitly approved. `null` until the commission transitions to `APPROVED`. |
| **payoutQueuedAt** | `timestamp` | UTC timestamp (in milliseconds) indicating when the commission was queued for payout automation. `null` if it has not been scheduled. |
| **paidAt** | `timestamp` | UTC timestamp (in milliseconds) when the commission was sent in a payout. `null` until the commission transitions to `PAID`. |
| **reversedAt** | `timestamp` | UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). `null` unless the commission transitions to `REVERSED`. |
| **holdDuration** | `integer` | Number of days the commission must age before it can be processed for payout. Defaults to `0` (no hold). |
| **provider** | `string` | Origin of the commission event. Possible values: `stripe`, `api` |
| **amountInCampaignCurrency** | `number` | Commission amount (what the affiliate earned) converted to the program's currency, in the currency’s smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. `null` if the commission is still pending FX conversion. |
| **saleAmountInCampaignCurrency** | `number` | The sale amount (from the transaction that the referral paid) converted to the program's currency, in the currency's smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. `null` if the commission is still pending FX conversion. |
| **exchangeRate** | `number` | The currency exchange rate that was used for conversion. `null` if the commission is still pending FX conversion. |
| **campaignCurrencyISO** | `string` | The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the program that was used in currency conversion (e.g., `USD`, `GBP`). `null` if the commission is still pending FX conversion. |
| **exchangeRateAt** | `timestamp` | UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the commission is still pending FX conversion. |
| **fxError** | `string` | If there was an error with FX conversion, this field will provide the specific details. (Note: GrowSurf will continue to retry FX conversions until successful).
If null, that means FX conversion was successful.
|
ParticipantCommission Object Example
```json
{
"id": "comm_jp1ku7",
"referrerId": "f8g9nl",
"referredId": "xh345d",
"amount": 2500,
"currencyISO": "USD",
"saleAmount": 10000,
"status": "APPROVED",
"createdAt": 1731494175123,
"approvedAt": 1731580575123,
"paidAt": null,
"reversedAt": null,
"payoutQueuedAt": null,
"holdDuration": 7,
"provider": "stripe",
"amountInCampaignCurrency": 2500,
"saleAmountInCampaignCurrency": 10000,
"campaignCurrencyISO": "USD",
"exchangeRateAt": 1731494175123,
"fxError": null
}
```
***
## `ParticipantPayout`
Affiliate programs only
The `ParticipantPayout` Object contains detailed information about a payout that was generated for a participant in an affiliate program.
{% hint style="info" %}
**Note on Upcoming Payouts**: All payouts start with a status of `UPCOMING`, which represents an aggregation of `amount`s from the participant's [`ParticipantCommission`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#participantcommission)s. During this time, if the participant earns more commissions or if any of their commissions get adjusted, their upcoming `ParticipantPayout` will also be adjusted in real-time to reflect those changes.
{% endhint %}
| Name | Type | Description |
| ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **id** | `string` | The unique identifier of the participant payout. |
| **participantId** | `string` | The participant ID of the referrer who earned the payout. |
| **commissionIds** | array | The IDs of the associated [`ParticipantCommission`](https://docs.growsurf.com/developer-tools/rest-api/api-objects#participantcommission)s. |
| **amount** | `integer` | Payout amount in the currency’s smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. |
| **currencyISO** | `string` | The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of the payout (e.g., `USD`, `GBP`) |
| **status** | `string` | Current lifecycle state of the payout. Possible values: `UPCOMING`, `QUEUED`, `ISSUED`, `FAILED`. |
| **provider** | `string` | The payment provider that was used to issue the payout. Possible values: `paypal`. `null` for payouts that have a status of `UPCOMING`. |
| **createdAt** | `timestamp` | UTC timestamp (in milliseconds) when the payout record was created. |
| **issuedAt** | `timestamp` | UTC timestamp (in milliseconds) when the payout was issued. `null` if the payout was not succesfully issued. |
| **failedAt** | `timestamp` | UTC timestamp (in milliseconds) when the payout failed to be issued. `null` if the payout did not fail to be issued. |
| **amountInCampaignCurrency** | `number` | Payout amount converted to the program's currency, in the currency’s smallest denomination (e.g., 100 cents is equal to $1.00, and 100 is equal to ¥100, a zero-decimal currency). Always non-negative. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion. |
| **exchangeRate** | `number` | The currency exchange rate that was used for conversion. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion. |
| **campaignCurrencyISO** | `string` | The [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code of of the program that was used in currency conversion (e.g., `USD`, `GBP`). `null` if the payout status is `UPCOMING` or if it is still pending FX conversion. |
| **exchangeRateAt** | `timestamp` | UTC timestamp (in milliseconds) when the currency exchange rate was received. `null` if the payout status is `UPCOMING` or if it is still pending FX conversion. |
| **fxError** | `string` | If there was an error with FX conversion, this field will provide the specific details. `null` if the payout status is `UPCOMING` or if the FX conversion was successful. |
ParticipantPayout Object Example
```json
{
"id": "po_k11ps9",
"participantId": "f8g9nl",
"commissionIds": [
"comm_jp1ku7",
"comm_a98s7z"
],
"amount": 3600,
"currencyISO": "USD",
"status": "ISSUED",
"createdAt": 1731494295334,
"issuedAt": 1731580575123,
"failedAt": null,
"provider": "paypal",
"amountInCampaignCurrency": 3600,
"campaignCurrencyISO": "USD",
"exchangeRateAt": 1731580575217,
"exchangeRate": 1.0,
"fxError": null
}
```