Referral page

Creating a referral page for your mobile app involves using several Perkville API endpoints. Below are the components you'll need to consider when building your referral page.

Retrieve Referral Offer Details

The details of the referral offer are accessible via the Promotion endpoint. This endpoint will provide you with the information about the offers available for sharing, which can be displayed on your referral page.

Promotions are location specific. Filter this endpoint using the customer’s currently selected location with the location parameter. For guidance on mapping app locations to Perkville locations and fallback behavior, see the Location section in Integrating Your App with Perkville.

Get the Referral Offer URL

The Connection provides the referral_offer_url that members will share.

Submit Referrals on Behalf of Members

If you want to submit referrals on behalf of members, you can do so using the Referrals endpoint. At the bottom of the referral page, you can include a form that captures necessary information for submitting a referral.

Error Handling

When creating a referral, handle the following errors and show a customer-safe message. These are the specific validation errors raised by the referral endpoint.

• pv_api_bad_loc_id When: The provided location is missing, inactive, or not valid for the business. Customer-safe: “That location isn’t available. Please select a different location.”

• pv_referral_referer_not_connected When: The referrer does not have a Connection to the business. Customer-safe: “You need to join the loyalty program before referring someone.”

• pv_referral_self_referral When: The referrer and referee are the same person. Customer-safe: “You can’t refer yourself.”

• pv_referral_max_limit When: The referrer has exceeded the referral limit in 24 hours. Customer-safe: “You’ve reached today’s referral limit. Please try again tomorrow.”

• pv_referral_referee_not_eligible When: The referee already has a Connection to the business. Customer-safe: “That person isn’t eligible for referral.”

• required / invalid (field-level) When: Required fields are missing or malformed. Customer-safe: “We couldn’t complete your request. Please check your details and try again.”