> ## Documentation Index > Fetch the complete documentation index at: https://developers.appstle.com/llms.txt > Use this file to discover all available pages before exploring further. # Accept a referral invite > Records that a friend accepted a customer's referral invite. This is the Public API equivalent of the storefront widget's referral claim, for headless storefronts that can't use the theme widget. **The headless referral flow:** 1. Get the referring customer's link from `GET /api/external/customer-loyalty` (`referralLink`). 2. The link lands on `https:///?appstle_referral=true&appstle_referral_code=`. Read `appstle_referral_code` from the landing URL, collect the friend's email, and send both here. 3. For order-based referral programs, the referral completes when the friend places a qualifying order with that same email. No further API call is needed. 4. Show the referring customer's referrals with `GET /api/external/customer-referrals`. Call this from your server. Never expose your API key in browser code. **Headless stores:** order-based referral rewards and referral emails need the Appstle app embed enabled in the store's published Online Store theme, even when shoppers never see that theme. **What happens:** - The same checks as the storefront widget apply: invalid token, self-referral, an email that was already referred, an inactive referral program, and the referral program's customer-tag restrictions all return 400. - On success, a PENDING referral is created and any reward configured to be given on acceptance is issued. - Reward discount codes are not returned in the response (`discountCode` is always empty). They're emailed to each customer, and only when the Appstle app embed is enabled in the store's theme. - `existingCustomer` is true when the email already belongs to a store customer. - When no referral program is active, the 400 response's message reads "Invalid request, token not found." ## OpenAPI ````yaml /loyalty/admin-api-swagger.json post /api/external/referral-accept openapi: 3.0.1 info: description: '' title: Admin APIs version: 0.0.1 servers: - url: https://loyalty-admin.appstle.com security: [] tags: - description: >- Admin APIs for enrolling customers into the loyalty program, retrieving customer loyalty details, and updating profile information such as birth date. name: Customer Enrollment & Profile - description: >- Admin APIs for managing customer point balances, transaction history, point earning rules, top customers leaderboard, and approving pending transactions. name: Points & Earn Rules - description: >- Admin APIs for redeeming customer points, managing redemption rules, and validating or updating discount codes generated through loyalty redemptions. name: Redemptions & Discount Codes - description: >- Admin APIs for retrieving storefront widget label translations consumed by the loyalty widget on the merchant's storefront. name: Storefront Widgets & Labels paths: /api/external/referral-accept: post: tags: - Referrals summary: Accept a referral invite description: > Records that a friend accepted a customer's referral invite. This is the Public API equivalent of the storefront widget's referral claim, for headless storefronts that can't use the theme widget. **The headless referral flow:** 1. Get the referring customer's link from `GET /api/external/customer-loyalty` (`referralLink`). 2. The link lands on `https:///?appstle_referral=true&appstle_referral_code=`. Read `appstle_referral_code` from the landing URL, collect the friend's email, and send both here. 3. For order-based referral programs, the referral completes when the friend places a qualifying order with that same email. No further API call is needed. 4. Show the referring customer's referrals with `GET /api/external/customer-referrals`. Call this from your server. Never expose your API key in browser code. **Headless stores:** order-based referral rewards and referral emails need the Appstle app embed enabled in the store's published Online Store theme, even when shoppers never see that theme. **What happens:** - The same checks as the storefront widget apply: invalid token, self-referral, an email that was already referred, an inactive referral program, and the referral program's customer-tag restrictions all return 400. - On success, a PENDING referral is created and any reward configured to be given on acceptance is issued. - Reward discount codes are not returned in the response (`discountCode` is always empty). They're emailed to each customer, and only when the Appstle app embed is enabled in the store's theme. - `existingCustomer` is true when the email already belongs to a store customer. - When no referral program is active, the 400 response's message reads "Invalid request, token not found." operationId: externalAcceptReferralOffer parameters: - description: API key for authentication in: header name: X-API-Key required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ReferralAcceptRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ReferralAcceptResponse' description: Referral accepted '400': content: application/json: schema: $ref: '#/components/schemas/ReferralAcceptResponse' description: >- Referral not accepted - missing token or email, invalid token, self-referral, already referred, inactive referral program, or the customer isn't eligible. `message` gives the reason; `errorKey` is SELF_REFERRAL or ALREADY_REFERRED for those two cases. '401': description: Unauthorized - Invalid or missing X-API-Key '403': description: Forbidden - the API key is read-only security: - X-API-Key: [] components: schemas: ReferralAcceptRequest: description: >- The referral token from the link (`appstle_referral_code`) and the friend's email properties: email: description: Email address of the friend accepting the referral example: friend@example.com type: string token: description: 'Referral token: the last part of the referrer''s `referralLink`' example: abc123def456ghij type: string required: - email - token type: object ReferralAcceptResponse: properties: discountCode: description: Always empty. Reward codes are emailed to the customers instead. type: string errorKey: description: >- Stable code for some failures: `SELF_REFERRAL` or `ALREADY_REFERRED`. Empty on success and on other failures. type: string existingCustomer: description: >- On success, `true` when the email already belonged to a customer of the store type: boolean id: description: Always empty. The referral record ID isn't returned. format: int64 type: integer message: description: Result message in English, such as "Referral accepted successfully." type: string status: description: >- `SUCCESS` when the referral was accepted, `FAILED` when it was refused enum: - SUCCESS - FAILED type: string type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.