Ctrlk
Help CenterSystem StatusContact SupportYour Dashboard →
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Objects

The Team object

Attributes

The team bound to the API key or OAuth connection.

namestringRequired

The team's display name.

Example: Pied Piper
verificationStatusstring · enumRead-onlyRequired

GrowSurf team verification state. VERIFIED is required before a program can send participant emails.

Example: VERIFIEDPossible values:
verificationRequestedAtinteger · int64 · nullableRead-onlyRequired

When team verification was last requested, as a Unix timestamp in milliseconds.

Example: 1719792000000

The Team object

{
  "name": "Pied Piper",
  "verificationStatus": "VERIFIED",
  "verificationRequestedAt": 1719792000000
}

The Campaign object

Attributes

Detailed information about a GrowSurf program.

idstringRead-onlyRequired

The unique identifier of the program.

Example: abc123
namestringRequired

The program name (internal only, never exposed to participants).

Example: Middle Out Compression Campaign
typestring · enumRequired

The program type.

Example: REFERRALPossible values:
referralCountintegerRead-onlyRequired

The total referral count.

Example: 121
participantCountintegerRead-onlyRequired

The total participant count.

Example: 199
impressionCountintegerRead-onlyRequired

The total number of impressions — the collective number of times participants' unique referral links have been viewed.

Example: 199
inviteCountintegerRead-onlyRequired

The total number of invites sent by participants.

Example: 237
winnerCountintegerRead-onlyRequired

The total number of winners — all participants with at least one approved reward (includes referrers and referred friends).

Example: 1
currencyISOstring · min: 3 · max: 3 · nullableOptional

The program currency as an ISO 4217 code (e.g., USD, GBP).

Example: USD
statusstring · enumRequired

The program status.

Example: IN_PROGRESSPossible values:

The Campaign object

{
  "id": "abc123",
  "name": "Middle Out Compression Campaign",
  "type": "REFERRAL",
  "referralCount": 121,
  "participantCount": 199,
  "impressionCount": 199,
  "inviteCount": 237,
  "winnerCount": 1,
  "currencyISO": "USD",
  "status": "IN_PROGRESS",
  "rewards": [
    {
      "id": "crew_xyz789",
      "type": "DOUBLE_SIDED",
      "title": "Pied Piper T-Shirt",
      "isVisible": true,
      "description": "Refer a friend and get a Pied Piper T-Shirt",
      "referralDescription": "Join and receive middle out compression algorithm",
      "referredRewardUpfront": false,
      "isUnlimited": false,
      "limit": 1,
      "conversionsRequired": 1,
      "numberOfWinners": 3,
      "limitDuration": "IN_TOTAL",
      "imageUrl": "https://example.com/reward-image.png",
      "couponCode": "PROMO_20_OFF",
      "order": 1,
      "nextMilestonePrefix": "You are only",
      "nextMilestoneSuffix": "referrals away from receiving a nice reward!",
      "metadata": {
        "company": "Hooli, Inc",
        "companySize": 10000
      },
      "commissionStructure": {
        "amount": null,
        "amountISO": null,
        "event": "SALE",
        "type": "PERCENT",
        "minPaidReferrals": 2,
        "holdDuration": 30,
        "duration": "FOREVER",
        "durationInMonths": null,
        "approvalRequired": false,
        "percent": 25,
        "hasMaxAmount": false,
        "maxAmount": null,
        "maxAmountISO": null,
        "hasIntro": false,
        "introType": null,
        "introPercent": null,
        "introAmount": null,
        "introAmountISO": null,
        "introDuration": null,
        "introDurationInMonths": null
      },
      "referralCouponCode": "WELCOME_20_OFF",
      "value": {
        "fairMarketValueUSD": 25,
        "isTaxReportable": true
      },
      "referredValue": {
        "fairMarketValueUSD": 25,
        "isTaxReportable": true
      }
    }
  ]
}

The Reward object

Attributes

A single campaign reward (also known as a CampaignReward). This is different from a ParticipantReward, which is a reward earned by a participant.

idstringRead-onlyRequired

The unique identifier of the campaign reward. You can find this ID from Program Editor > 1. Rewards and clicking the reward.

Example: crew_xyz789
typestring · enumRequired

The reward type.

Example: DOUBLE_SIDEDPossible values:
titlestring · nullableOptional

The reward title (internal only, never exposed to participants).

Example: Pied Piper T-Shirt
isVisiblebooleanOptional

Whether the reward is enabled. When false, the reward is disabled: it is no longer awarded, and it is hidden from participants, including those who already earned it. Set true for the reward to be visible and awardable.

Example: true
descriptionstring · nullableOptional

The reward description shown to the referrer.

Example: Refer a friend and get a Pied Piper T-Shirt
referralDescriptionstring · nullableOptional

The reward description shown to the referred friend (only applicable for double-sided reward types).

Example: Join and receive middle out compression algorithm
referredRewardUpfrontbooleanOptional

Only applies to double-sided rewards. When true, the referred friend's reward is delivered upfront as a discount and no ParticipantReward is created for them when the referral triggers.

Example: false
isUnlimitedbooleanRequired

true if this reward can be earned by a single participant an unlimited number of times.

Example: false
limitinteger · nullableOptional

The number of times a participant can earn this reward (overridden when isUnlimited is true). -1 represents an unlimited reward in REST responses.

Example: 1
conversionsRequiredinteger · nullableOptional

The number of referrals a participant must make to earn this reward.

Example: 1
numberOfWinnersinteger · nullableOptional

The maximum number of winners. Only applies to LEADERBOARD rewards. When limitDuration is PER_MONTH, this many top referrers win each month; otherwise this many win in total.

Example: 3
limitDurationstring,null · enum · nullableOptional

Whether the reward can be earned in total, on a monthly basis, or on a yearly basis.

Example: IN_TOTALPossible values:
imageUrlstring · nullableOptional

The reward image URL.

Example: https://example.com/reward-image.png
couponCodestring · nullableOptional

A static coupon code shown to the referrer in the reward-won email and webhook. Display text only; GrowSurf does not create or validate it in any billing system. If the program has a connected billing integration (Stripe, Chargebee, or Recurly) that issues a coupon for the referral, that issued code is shown instead.

Example: PROMO_20_OFF
orderinteger · nullableOptional

If there are multiple rewards, the order in which the reward should be displayed. null by default until set within the Design step of the program editor.

Example: 1
nextMilestonePrefixstring · nullableOptional

Text displayed in front of a participant's referral count for UI purposes (e.g., "You are only"). Applicable for milestone rewards (when type is MILESTONE).

Example: You are only
nextMilestoneSuffixstring · nullableOptional

Text displayed after a participant's referral count for UI purposes (e.g., "referrals away from receiving a nice reward!"). Applicable for milestone rewards (when type is MILESTONE).

Example: referrals away from receiving a nice reward!
referralCouponCodestring · nullableOptional

A static coupon code shown to the referred friend in the reward-won email and webhook (double-sided rewards). Same caveats as couponCode: display text only, not created or validated in any billing system, and superseded by a connected billing integration's issued coupon when one exists.

Example: WELCOME_20_OFF

The Reward object

{
  "id": "crew_xyz789",
  "type": "DOUBLE_SIDED",
  "title": "Pied Piper T-Shirt",
  "isVisible": true,
  "description": "Refer a friend and get a Pied Piper T-Shirt",
  "referralDescription": "Join and receive middle out compression algorithm",
  "referredRewardUpfront": false,
  "isUnlimited": false,
  "limit": 1,
  "conversionsRequired": 1,
  "numberOfWinners": 3,
  "limitDuration": "IN_TOTAL",
  "imageUrl": "https://example.com/reward-image.png",
  "couponCode": "PROMO_20_OFF",
  "order": 1,
  "nextMilestonePrefix": "You are only",
  "nextMilestoneSuffix": "referrals away from receiving a nice reward!",
  "metadata": {
    "company": "Hooli, Inc",
    "companySize": 10000
  },
  "commissionStructure": {
    "amount": null,
    "amountISO": null,
    "event": "SALE",
    "type": "PERCENT",
    "minPaidReferrals": 2,
    "holdDuration": 30,
    "duration": "FOREVER",
    "durationInMonths": null,
    "approvalRequired": false,
    "percent": 25,
    "hasMaxAmount": false,
    "maxAmount": null,
    "maxAmountISO": null,
    "hasIntro": false,
    "introType": null,
    "introPercent": null,
    "introAmount": null,
    "introAmountISO": null,
    "introDuration": null,
    "introDurationInMonths": null
  },
  "referralCouponCode": "WELCOME_20_OFF",
  "value": {
    "fairMarketValueUSD": 25,
    "isTaxReportable": true
  },
  "referredValue": {
    "fairMarketValueUSD": 25,
    "isTaxReportable": true
  }
}

The Webhook object

Attributes

A program webhook's configuration (payload URL, subscribed events, enabled state) plus read-only delivery-health fields.

idstringRead-onlyRequired

The webhook id (primary for the program's primary webhook).

Example: primary
payloadUrlstring · nullableOptional

The URL that receives webhook deliveries.

Example: https://piedpiper.com/growsurf/webhook
isEnabledbooleanRequired

Whether deliveries to this webhook are enabled.

Example: true
autoDisabledDueToFailuresbooleanRead-onlyRequired

Read-only. Whether GrowSurf auto-disabled this webhook after repeated delivery failures.

Example: false
failureCountintegerRead-onlyRequired

Read-only. Consecutive delivery failures.

Example: 0
lastFailureAtinteger · int64 · nullableRead-onlyOptional

Read-only. When the last delivery failure occurred, as a Unix timestamp in milliseconds.

The Webhook object

{
  "id": "primary",
  "payloadUrl": "https://piedpiper.com/growsurf/webhook",
  "events": [
    "NEW_PARTICIPANT_ADDED",
    "PARTICIPANT_REACHED_A_GOAL"
  ],
  "isEnabled": true,
  "autoDisabledDueToFailures": false,
  "failureCount": 0,
  "lastFailureAt": null
}

The Participant object

Attributes

Detailed information about a program participant.

idstringRead-onlyRequired

The unique identifier of the participant.

Example: f8g9nl
firstNamestring · nullableOptional

The first name of the participant.

Example: Gavin
lastNamestring · nullableOptional

The last name of the participant.

Example: Belson
emailstringRequired

The email of the participant.

Example: gavin@hooli.com
paypalEmailAddressstring · emailOptional

The PayPal email address on file for the participant, used for affiliate or PayPal reward payouts.

Example: gavin@hooli.com
referralCountintegerRead-onlyRequired

The total number of referrals made by the participant.

Example: 2
monthlyReferralCountintegerRead-onlyRequired

The total number of referrals made this month by the participant (resets at the end of the month).

Example: 2
prevMonthlyReferralCountintegerRead-onlyOptional

The total number of referrals made the previous month by the participant.

Example: 0
rankintegerRead-onlyRequired

The rank of the participant.

Example: 10001
monthlyRankintegerRead-onlyRequired

The monthly rank of the participant. This rank resets to 0 at the end of each month.

Example: 20001
prevMonthlyRankintegerRead-onlyOptional

The previous monthly rank of the participant. Not returned if the participant did not exist in your program during the previous month.

Example: 24000
shareUrlstringRead-onlyRequired

The unique share URL of the participant.

Example: https://piedpiper.com?grsf=gavin-f8g9nl
createdAtinteger · int64Read-onlyOptional

The date the participant was added to the program (UTC milliseconds).

Example: 1552404738928
referralSourcestring · enumRead-onlyOptional

The source of how the participant joined the program.

Example: PARTICIPANTPossible values:
referralStatusstring · enumOptional

If the participant was referred, the referrer's status in receiving the referral credit. Only applicable if the participant was referred into the program.

Example: CREDIT_AWARDEDPossible values:
referredBystringOptional

The ID of the referrer. Only applicable if the participant was referred into the program.

Example: h8kp6l
fraudRiskLevelstring · enumRead-onlyOptional

A value that represents the integrity of the participant.

Example: LOWPossible values:
fraudReasonCodestringRead-onlyOptional

The reason for the participant's fraudRiskLevel:

  • UNIQUE_IDENTITY — They have a unique identity (no other participant has the same identity).
  • DUPLICATE_EMAIL — Their email is not unique and is identical to another participant's email (e.g., gavin@hooli.com = gavin+1@hooli.com).
  • DUPLICATE_IDENTITY — Their identity (fingerprint or mobile instance ID) is not unique and matches another participant's.
  • DUPLICATE_IDENTITY_EXCESSIVE — Within a small window of time, they had an excessive number of referred participants who also shared the same IP address.
  • EMAIL_FRAUD — Their email was found to match another participant's when updated in a connected billing or payment integration.
  • SIMILAR_EMAIL — Their browser fingerprint matches another participant's and their email looks suspiciously similar.
  • 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 to their referrer's email.
  • REFERRAL_CHAIN_FRAUD — (Status for a referrer or referred person) Their characteristics matched a pattern with other referrals the referrer made, indicating a fraud ring.
  • REFERRAL_VELOCITY_FRAUD — (Status for a referrer or referred person) The referrer made an excessive number of referrals in a short period of time.
  • DOMAIN_CLUSTERING_FRAUD — (Status for a referrer or referred person) The referrer made an excessive number of referrals sharing 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 an allowed value.
  • BLACKLIST_MATCH — They were not allowed to join the program because one of their properties matched a blocked 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.
Example: UNIQUE_IDENTITY
isWinnerbooleanRead-onlyOptional

true if the participant has earned one or more rewards.

Example: true
impressionCountintegerRead-onlyOptional

The total number of impressions the participant has made.

Example: 2
uniqueImpressionCountintegerRead-onlyOptional

The total number of unique impressions the participant has made.

Example: 2
inviteCountintegerRead-onlyOptional

The total number of invites the participant has sent.

Example: 3
referralsstring[]Read-onlyOptional

A list of Participant IDs who were successfully referred by the participant. Limited to the 100 most recently referred friends.

Example: ["i9g2bh","xua4sq"]
monthlyReferralsstring[]Read-onlyOptional

A list of Participant IDs successfully referred by the participant this month (resets at the end of the month). Limited to the 100 most recent.

Example: ["i9g2bh","xua4sq"]
ipAddressstring · nullableOptional

The IP address associated with the participant, used for anti-fraud matching.

Example: 127.0.0.1
fingerprintstring · nullableOptional

The browser fingerprint associated with the participant, used for anti-fraud matching.

Example: cfb163bd47ba666c52cb932c521e47f4
mobileInstanceIdstring · nullableOptional

App-install scoped mobile identifier used for anti-fraud matching when provided by native mobile apps. The official mobile SDKs generate this as a lowercase UUID. Not stored when strict GDPR/CCPA mode is enabled.

Example: 5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1
notesstring · nullableOptional

Internal notes about the participant, added via the GrowSurf Dashboard.

Example: This is obviously our competitor trying out our product!
unsubscribedbooleanOptional

true if the participant has unsubscribed from program emails.

Example: false
vanityKeysstring[]Optional

The list of vanity keys that the participant has.

Example: ["gavin-f8g9nl"]
unreadCommissionsCountintegerRead-onlyOptional

Affiliate programs only. The number of commissions the participant has not yet viewed.

Example: 1
unreadPayoutsCountintegerRead-onlyOptional

Affiliate programs only. The number of payouts the participant has not yet viewed.

Example: 0
isNewbooleanRead-onlyOptional

Whether this participant was newly created by the request. Returned by participant creation calls; false when the participant already existed.

Example: false

The Participant object

{
  "id": "f8g9nl",
  "firstName": "Gavin",
  "lastName": "Belson",
  "email": "gavin@hooli.com",
  "paypalEmailAddress": "gavin@hooli.com",
  "referralCount": 2,
  "monthlyReferralCount": 2,
  "prevMonthlyReferralCount": 0,
  "rank": 10001,
  "monthlyRank": 20001,
  "prevMonthlyRank": 24000,
  "shareUrl": "https://piedpiper.com?grsf=gavin-f8g9nl",
  "createdAt": 1552404738928,
  "referralSource": "PARTICIPANT",
  "referralStatus": "CREDIT_AWARDED",
  "referredBy": "h8kp6l",
  "fraudRiskLevel": "LOW",
  "fraudReasonCode": "UNIQUE_IDENTITY",
  "isWinner": true,
  "shareCount": {
    "email": 10,
    "facebook": 1,
    "pinterest": 1,
    "twitter": 11
  },
  "impressionCount": 2,
  "uniqueImpressionCount": 2,
  "inviteCount": 3,
  "referrals": [
    "i9g2bh",
    "xua4sq"
  ],
  "monthlyReferrals": [
    "i9g2bh",
    "xua4sq"
  ],
  "referrer": {
    "id": "h8kp6l",
    "firstName": "Richard",
    "lastName": "Hendricks",
    "email": "richard@piedpiper.com",
    "referralCount": 12,
    "monthlyReferralCount": 3,
    "prevMonthlyReferralCount": 5,
    "rank": 5,
    "monthlyRank": 2,
    "prevMonthlyRank": 4,
    "shareUrl": "https://piedpiper.com?grsf=richard-h8kp6l",
    "createdAt": 1549812440000,
    "referralSource": "PARTICIPANT",
    "referralStatus": "CREDIT_AWARDED",
    "fraudRiskLevel": "LOW",
    "fraudReasonCode": "UNIQUE_IDENTITY",
    "isWinner": true,
    "shareCount": {
      "email": 3,
      "facebook": 5,
      "twitter": 2,
      "copyRefLink": 7
    },
    "impressionCount": 340,
    "uniqueImpressionCount": 210,
    "inviteCount": 8,
    "referrals": [
      "f8g9nl"
    ],
    "monthlyReferrals": [
      "f8g9nl"
    ],
    "ipAddress": "203.0.113.10",
    "fingerprint": "9d4c1f2ab8e35d7c6a1b0e9f8d7c6b5a",
    "metadata": {
      "company": "Hooli, Inc",
      "companySize": 10000
    },
    "unsubscribed": false
  },
  "ipAddress": "127.0.0.1",
  "fingerprint": "cfb163bd47ba666c52cb932c521e47f4",
  "mobileInstanceId": "5f7d0f4c-3e7c-4aa9-8c41-d81d998f0bb1",
  "metadata": {
    "company": "Hooli, Inc",
    "companySize": 10000
  },
  "notes": "This is obviously our competitor trying out our product!",
  "unsubscribed": false,
  "rewards": [
    {
      "id": "prew_rr35mg",
      "rewardId": "crew_c6w1qo",
      "status": "FULFILLED",
      "unread": true,
      "approved": false,
      "approvedAt": null,
      "fulfilledAt": null,
      "isReferrer": true,
      "isAvailable": false,
      "isFulfilled": false,
      "referredId": "xh345d",
      "referrerId": "f8g9nl",
      "commissionStructure": {
        "amount": null,
        "amountISO": null,
        "event": "SALE",
        "type": "PERCENT",
        "minPaidReferrals": 2,
        "holdDuration": 30,
        "duration": "FOREVER",
        "durationInMonths": null,
        "approvalRequired": false,
        "percent": 25,
        "hasMaxAmount": false,
        "maxAmount": null,
        "maxAmountISO": null,
        "hasIntro": false,
        "introType": null,
        "introPercent": null,
        "introAmount": null,
        "introAmountISO": null,
        "introDuration": null,
        "introDurationInMonths": null
      }
    }
  ],
  "vanityKeys": [
    "gavin-f8g9nl"
  ],
  "unreadCommissionsCount": 1,
  "unreadPayoutsCount": 0,
  "isNew": false,
  "allMatchingFraudsters": [],
  "payoutSettings": {
    "requiredActions": [
      "TAX_INFO"
    ]
  }
}

The ParticipantCommission object

Attributes

Affiliate programs only. A commission generated for a (referrer) participant in an affiliate program.

idstringRead-onlyRequired

The unique identifier of the participant commission.

Example: comm_abc123
referrerIdstringRead-onlyRequired

The participant ID of the referrer who earned the commission.

Example: f8g9nl
referredIdstringRead-onlyRequired

The participant ID of the referred friend (the conversion that triggered the commission).

Example: h8kp6l
amountinteger · nullableRead-onlyRequired

Commission amount (what the affiliate earned) in the currency's smallest denomination (e.g., 100 cents equals $1.00 USD, and 100 equals ¥100 for a zero-decimal currency). Always non-negative when present; null if it could not be computed.

Example: 1000
saleAmountinteger · nullableRead-onlyRequired

The sale amount from the transaction the referral paid, in the currency's smallest denomination. Always non-negative when present; null for commissions whose provider does not report a sale amount.

Example: 10000
currencyISOstringRead-onlyRequired

The ISO 4217 currency code of the commission (e.g., USD, GBP).

Example: USD
statusstring · enumRead-onlyRequired

Current lifecycle state of the commission.

Example: PENDINGPossible values:
approvedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the commission was approved. null until the commission transitions to APPROVED.

paidAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the commission was sent in a payout. null until the commission transitions to PAID.

reversedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the commission was reversed (for example, due to a refund or chargeback). null unless the commission transitions to REVERSED.

holdDurationinteger · nullableRead-onlyOptional

Number of days the commission must age before it can be processed for payout. Defaults to 0 (no hold).

Example: 30
payoutQueuedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the commission was queued for payout. null if it has not been scheduled.

providerstring · nullableRead-onlyOptional

Origin of the commission event. For example, stripe or api.

Example: stripe
createdAtinteger · int64Read-onlyRequired

UTC timestamp (in milliseconds) when the commission record was created.

Example: 1591546112223
amountInCampaignCurrencyinteger · nullableRead-onlyOptional

Commission amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. null if the commission is still pending FX conversion.

Example: 1000
saleAmountInCampaignCurrencyinteger · nullableRead-onlyOptional

The sale amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. null if the commission is still pending FX conversion.

Example: 10000
exchangeRatenumber · nullableRead-onlyOptional

The currency exchange rate used for conversion. null if the commission is still pending FX conversion.

campaignCurrencyISOstring · nullableRead-onlyOptional

The ISO 4217 currency code of the program used in currency conversion (e.g., USD, GBP). null if the commission is still pending FX conversion.

Example: USD
exchangeRateAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the currency exchange rate was received. null if the commission is still pending FX conversion.

fxErrorstring · nullableRead-onlyOptional

If there was an error with FX conversion, the specific details. null if conversion was successful.

The ParticipantCommission object

{
  "id": "comm_abc123",
  "referrerId": "f8g9nl",
  "referredId": "h8kp6l",
  "amount": 1000,
  "saleAmount": 10000,
  "currencyISO": "USD",
  "status": "PENDING",
  "approvedAt": null,
  "paidAt": null,
  "reversedAt": null,
  "holdDuration": 30,
  "payoutQueuedAt": null,
  "provider": "stripe",
  "createdAt": 1591546112223,
  "amountInCampaignCurrency": 1000,
  "saleAmountInCampaignCurrency": 10000,
  "exchangeRate": null,
  "campaignCurrencyISO": "USD",
  "exchangeRateAt": null,
  "fxError": null
}

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.

The ParticipantPayout object

Attributes

Affiliate programs only. A payout generated for a participant in an affiliate program. All payouts start with a status of UPCOMING, which represents an aggregation of the participant's ParticipantCommission amounts, and is adjusted in real time as commissions change.

idstringRead-onlyRequired

The unique identifier of the participant payout.

Example: po_k11ps9
participantIdstringRead-onlyRequired

The participant ID of the referrer who earned the payout.

Example: f8g9nl
commissionIdsstring[]Read-onlyRequired

The IDs of the associated ParticipantCommissions.

Example: ["comm_jp1ku7","comm_a98s7z"]
amountintegerRead-onlyRequired

Payout amount in the currency's smallest denomination (e.g., 100 cents equals $1.00 USD, and 100 equals ¥100 for a zero-decimal currency). Always non-negative.

Example: 3600
currencyISOstringRead-onlyRequired

The ISO 4217 currency code of the payout (e.g., USD, GBP).

Example: USD
statusstring · enumRead-onlyRequired

Current lifecycle state of the payout.

Example: ISSUEDPossible values:
createdAtinteger · int64Read-onlyRequired

UTC timestamp (in milliseconds) when the payout record was created.

Example: 1635638400000
queuedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the payout was queued for processing (status QUEUED). null until the payout is queued.

Example: 1635681600000
issuedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the payout was issued. null if the payout was not successfully issued.

Example: 1635724800000
failedAtinteger · nullableRead-onlyOptional

UTC timestamp (in milliseconds) when the payout failed to be issued. null if the payout did not fail to be issued.

providerstring · nullableRead-onlyOptional

The payment provider used to issue the payout (e.g., paypal). null for payouts with a status of UPCOMING.

Example: paypal
amountInCampaignCurrencyinteger · nullableRead-onlyOptional

Payout amount converted to the program's currency, in the currency's smallest denomination. Always non-negative. null if the payout status is UPCOMING or if it is still pending FX conversion.

Example: 3600
campaignCurrencyISOstring · nullableRead-onlyOptional

The ISO 4217 currency code of the program used in currency conversion (e.g., USD, GBP). null if the payout status is UPCOMING or if it is still pending FX conversion.

Example: USD
exchangeRateAtinteger · nullableRead-onlyOptional

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.

Example: 1635638400000
exchangeRatenumber · nullableRead-onlyOptional

The currency exchange rate used for conversion. null if the payout status is UPCOMING or if it is still pending FX conversion.

Example: 1
fxErrorstring · nullableRead-onlyOptional

If there was an error with FX conversion, the specific details. null if the payout status is UPCOMING or if the FX conversion was successful.

The ParticipantPayout object

{
  "id": "po_k11ps9",
  "participantId": "f8g9nl",
  "commissionIds": [
    "comm_jp1ku7",
    "comm_a98s7z"
  ],
  "amount": 3600,
  "currencyISO": "USD",
  "status": "ISSUED",
  "createdAt": 1635638400000,
  "queuedAt": 1635681600000,
  "issuedAt": 1635724800000,
  "failedAt": null,
  "provider": "paypal",
  "amountInCampaignCurrency": 3600,
  "campaignCurrencyISO": "USD",
  "exchangeRateAt": 1635638400000,
  "exchangeRate": 1,
  "fxError": null
}

Last updated

Was this helpful?