Referral Rewards Extension

The Referral Rewards RS Gateway extension is a set of APIs that return a unique referral code for a subscriber that you can use subsequently when creating a new subscriber.

The Referral Rewards extends the CreateSubscriber API to accept a referral code as a parameter and rewards the referring subscriber by triggering a purchase operation when the new subscriber is created.

For example, a client requests a referral code using the following API:

GET /referral_rewards/subscriber/{SearchTerm}

The SearchTerm identifies an existing subscriber (A) and returns a ReferralCode (of type string) that identifies the active subscriber (A) when a new subscriber (B) is created.

You can also identify the referring subscriber (A) by specifying a ReferralCode in a request. In this call, the referring subscriber's object ID is returned.

GET /referral_rewards/subscriber/oid/{ReferralCode}

When you create a new subscriber with a POST request (MtxSubscriberCreate or CreateSubscriberAndDeviceRequest), and the request includes a ReferralCode in the Attr block, the Referral Rewards extension determines if the referral code matches an active subscriber. If there is a match, a catalog item purchase is made on behalf of the active subscriber. The catalog item is determined by a parameter set in the rsgateway.yaml file as described in the discussion about installing and configuring the Referral Rewards extension.

The referral.properties file defines the offer that is rewarded to the referrer, an MtxPurchasedOfferExtension MDC with a field named ReferrerMtxObjectId of type MtxObjectId, and an MtxSubscriberExtension MDC.

```
referral_rewards.catalog.id=1
```

referral_rewards.purchase_extension_mdc.name=ReferralPurchaseExtension

referral_rewards.subscriber_extension_mdc.name=ReferralSubscriberExtension

Define the ReferrerMtxObjectId in the ReferralPurchaseExtension. This field is used as an audit to confirm that the reward was purchased for a subscriber.

Referral Rewards Configuration

To use the referral code, you must add a ReferralCode field to the custom subscriber MDC. For example:

Create a custom subscriber MDC:

Added MDC:00003:What is the container's name?ReferralSubscriberExtension
Added MDC:00003:What is the container's key?-3
Added MDC:00003:What is the name of the base container (if any)?MtxSubscriberObject
Added MDC:00003:What is the created schema version?2
Added MDC:00003:What is the deleted schema version?0

In the ReferralSubscriberExtension MDC, define an MDC string field named ReferralCode:

New ReferralSubscriberExtension field:00001:What is the field's name?ReferralCode
New ReferralSubscriberExtension field:00001:What is the field's type?string
New ReferralSubscriberExtension field:00001:What is the field's max-size?0
New ReferralSubscriberExtension field:00001:Is this field a list (y/n)?n
New ReferralSubscriberExtension field:00001:Is this field an array (y/n)?n
New ReferralSubscriberExtension field:00001:What is the created schema version?2
New ReferralSubscriberExtension field:00001:What is the deleted schema version?0

You must add the ReferrerMtxObjectId field to the custom purchase offer extension. For example:

Create a custom purchased offer extension:

Added MDC:00012:What is the container's name?ReferralPurchaseExtension
Added MDC:00012:What is the container's key?-12
Added MDC:00012:What is the name of the base container (if any)?MtxPurchasedOffer
Added MDC:00012:What is the created schema version?2
Added MDC:00012:What is the deleted schema version?0

In the ReferralPurchaseExtension MDC, define an MDC string field named ReferrerMtxObjectId:

New ReferralPurchaseExtension field:00001:What is the field's name?ReferrerMtxObjectId
New ReferralPurchaseExtension field:00001:What is the field's type?MtxObjectId
New ReferralPurchaseExtension field:00001:What is the field's max-size?0
New ReferralPurchaseExtension field:00001:Is this field a list (y/n)?n
New ReferralPurchaseExtension field:00001:Is this field an array (y/n)?n
New ReferralPurchaseExtension field:00001:What is the created schema version?2
New ReferralPurchaseExtension field:00001:What is the deleted schema version?0