> ## Documentation Index > Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt > Use this file to discover all available pages before exploring further. # Claim Referee Incentive Exchange an inbound referral id for the referee incentive — a discount voucher code you can display to the referred shopper. Use this when a shopper arrives at your storefront or app with an `ll_ref_id` query parameter, which is how our referral links identify who referred them. The `referral_id` is the value of that `ll_ref_id` parameter. The `ip_address` must be the referred shopper's own address — the one that reached your server, never your server's — as it powers referral fraud detection. Pass `referee_email` whenever you know the shopper's email. It binds the voucher to them, and it's what allows self-referrals and referrals of existing program members to be rejected (`invalid_referee`). If the referrer isn't an enrolled member, the email is required, and you'll receive a `referee_email_required` error until you supply it — collect the shopper's email and retry. It's safe to retry: claiming again with the same referral and referee returns the same code rather than issuing a new one. To present the offer alongside the code ("Get 10% off your first order, up to \$30"), use the `referee_incentive` object from [Get Configuration](../configuration/get-configuration), which carries localized display text and the structured discount details. When the shopper later places their first order using the voucher, the referral completes automatically — the shopper is linked to their referrer and your referral rule triggers. See the [referrals guide](/headless-api/guides/referrals) for the end-to-end flow. ## OpenAPI ````yaml headless-api/2025-06/openapi.json POST /headless/2025-06/{site_id}/referrals/referee_incentive openapi: 3.1.1 info: title: LoyaltyLion Headless API version: 2025-06 servers: - url: https://api.loyaltylion.com security: [] tags: - name: configuration - name: customers - name: referrals - name: rewards - name: rules paths: /headless/2025-06/{site_id}/referrals/referee_incentive: post: tags: - referrals operationId: referrals.claimRefereeIncentive parameters: - name: site_id in: path required: true schema: type: number description: Your LoyaltyLion Site ID requestBody: description: Body content: application/json: schema: $ref: '#/components/schemas/ReferralsClaimRefereeIncentiveRequestBody' responses: '200': description: >- The incentive was claimed. Repeating the request with the same `referral_id` and `referee_email` returns the same code. `kind` discriminates this from any further success outcome added later — switch on it rather than assuming a code is present content: application/json: schema: $ref: '#/components/schemas/ClaimRefereeIncentiveIncentive' '400': $ref: '#/components/responses/ClientErrorBadRequest' '401': description: '401' content: application/json: schema: type: object properties: error: type: object properties: message: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false required: - error additionalProperties: false '403': description: '403' content: application/json: schema: type: object properties: error: type: object properties: message: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false required: - error additionalProperties: false '422': description: '422' content: application/json: schema: type: object properties: error: oneOf: - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorRefereeEmailRequired - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorInvalidReferee - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorReferralsNotEnabled - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorInvalidReferralId - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorReferralCapReached - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorFraudDetected - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorNoVouchersAvailable - $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorVoucherAllocationFailed type: object discriminator: propertyName: code mapping: referee_email_required: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorRefereeEmailRequired invalid_referee: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorInvalidReferee referrals_not_enabled: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorReferralsNotEnabled invalid_referral_id: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorInvalidReferralId referral_cap_reached: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorReferralCapReached fraud_detected: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorFraudDetected no_vouchers_available: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorNoVouchersAvailable voucher_allocation_failed: $ref: >- #/components/schemas/ClaimRefereeIncentiveErrorVoucherAllocationFailed required: - error additionalProperties: false '429': description: '429' content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - rate_limited required: - code additionalProperties: false required: - error additionalProperties: false security: - ProgramApiKey: - write_customers components: schemas: ReferralsClaimRefereeIncentiveRequestBody: type: object properties: referral_id: type: string minLength: 1 description: >- The referral the shopper arrived with. This is the value of the `ll_ref_id` query parameter on the URL the referral link redirects to example: jRq0X referee_email: description: >- The email address of the shopper claiming the incentive. Pass it whenever you know it: it binds the voucher to that shopper, and it is what lets us reject a shopper who is referring themselves or who is already a member of the program It is only *required* when the referrer is not enrolled in the program. A request that needs it and omits it is rejected with `referee_email_required`, so you can retry with the address once you have collected it example: referee@example.com type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ ip_address: anyOf: - type: string format: ipv4 pattern: >- ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$ - type: string format: ipv6 pattern: >- ^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$ description: >- The IP address of the shopper claiming the incentive — the one that reached your server, not your server's own. It is what detects referral fraud when the program restricts referrals to distinct IP addresses, and it is the bucket we would rate-limit an individual shopper on Send a single address. A forwarded-for list is rejected: take the client entry from it yourself example: 203.0.113.42 user_agent: description: >- The user agent of the shopper claiming the incentive, recorded alongside the referral for fraud analysis. Send `null` where the caller genuinely has none, such as a native mobile app type: - string - 'null' required: - referral_id - ip_address - user_agent additionalProperties: false ClaimRefereeIncentiveIncentive: type: object properties: kind: type: string const: incentive incentive: type: object properties: code: type: string description: The discount code the shopper redeems at checkout example: LL-XYA3816 required: - code additionalProperties: false required: - kind - incentive additionalProperties: false description: >- The incentive was claimed. Repeating the request with the same `referral_id` and `referee_email` returns the same code. `kind` discriminates this from any further success outcome added later — switch on it rather than assuming a code is present ClaimRefereeIncentiveErrorRefereeEmailRequired: type: object properties: code: type: string const: referee_email_required required: - code additionalProperties: false title: Referee email required description: >- The referrer is not enrolled in the program, so a voucher can only be issued once it can be bound to the shopper claiming it. Collect their email address and repeat the request with `referee_email` set — unlike the other codes here, this one is not terminal ClaimRefereeIncentiveErrorInvalidReferee: type: object properties: code: type: string const: invalid_referee required: - code additionalProperties: false title: Invalid referee description: >- The shopper identified by `referee_email` cannot claim this referral — they are the referrer, or they are already a member of the program. Referral incentives are for new shoppers ClaimRefereeIncentiveErrorReferralsNotEnabled: type: object properties: code: type: string const: referrals_not_enabled required: - code additionalProperties: false title: Referrals not enabled description: >- This site has no active referral rule, so it cannot issue referral incentives ClaimRefereeIncentiveErrorInvalidReferralId: type: object properties: code: type: string const: invalid_referral_id message: type: string required: - code - message additionalProperties: false title: Invalid referral ID description: >- The `referral_id` could not be read, or does not belong to a customer in this program ClaimRefereeIncentiveErrorReferralCapReached: type: object properties: code: type: string const: referral_cap_reached required: - code additionalProperties: false title: Referral cap reached description: >- The referrer has hit the referral rule's reward cap, and the rule is configured to stop issuing incentives once that happens ClaimRefereeIncentiveErrorFraudDetected: type: object properties: code: type: string const: fraud_detected required: - code additionalProperties: false title: Fraud detected description: >- The program only accepts referrals between distinct IP addresses, and the `ip_address` you supplied matches the referrer's ClaimRefereeIncentiveErrorNoVouchersAvailable: type: object properties: code: type: string const: no_vouchers_available required: - code additionalProperties: false title: No vouchers available description: >- Your program issues referral incentives from a pool of codes you upload, and the pool is empty. Upload more codes to resume issuing incentives ClaimRefereeIncentiveErrorVoucherAllocationFailed: type: object properties: code: type: string const: voucher_allocation_failed message: type: string required: - code - message additionalProperties: false title: Voucher allocation failed description: >- We could not issue a voucher for this referral. The message describes why responses: ClientErrorBadRequest: description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: message: type: string details: type: object additionalProperties: type: string required: - message required: - error securitySchemes: ProgramApiKey: type: http scheme: bearer description: >- An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a `Bearer` token in the `Authorization` header ````