The Restaurant Heroes provides a referral conversion interface to allow your software platform to notify TRH when a referred user has converted to a paying customer.

The Conversion Data Object
Regardless of how you integrate, the request payload must contain a JSON object with the following information:
  • partner: required, string, max 255 characters.
  • This is your unique identifier in our system, and is set by your account rep during onboarding.
  • This is a constant, sent with every conversion request.
  • product: required, string, max 255 characters.
  • The TRH "product slug" for the product being converted. This value is set by your account rep during product setup.
  • If you have only one product, this is a constant, sent with every conversion request; if you have multiple products, this is a variable value.
  • email: required, string, max 128 characters
  • The customer's email address.
  • Email address must match the email address referred to you.
  • amount: sometimes required, numeric
  • Required when you have a single custom product trigger, i.e. when payouts are not based on the product price stored in the TRH database.
  • Value is ignored if an amounts array is provided as well.
  • amounts: sometimes required, array
  • Required when you have multiple custom product triggers.
  • Format: [{trigger_id: id, amount: number}, ...]
  • You will need to work with an account rep to configure this step.
  • partner_data: optional, object
  • TRH can store arbitrary meta information passed through from your system. For example, if you want to attach a customer ID, transaction ID, etc, your account rep can add those fields to your TRH partner account, and subsequent conversion requests can include those values.
  • Format: { "custom_key_name": "value from your system", ...}


Method 1: API Integration
If feasible, this is the preferred method, as you will be able to handle failures and have finer control over the process.
  • On your "success" page (at whatever point in your signup process a referral is deemed "converted"), collect the data required to build the Conversion Data Object outlined above.
  • POST the data to https://therestaurantheroes.com/data/v1/referral/convert 
  • Success response:
  • Status: 200
  • Payload: { 'success': true, 'message': 'Converted'}
  • Failure response
  • Status: 422
  • Failure errors
  • product_not_found: provided product slug is invalid
  • partner_not_found: provided partner slug is invalid
  • convert_mismatch: the provided product slug does not belong to a product owned by the specified partner
  • referral_not_found: the email address you supplied is not connected to a referral in our system.
  • sub_exists: the referral connected to the email address you supplied has already been converted.

Method 2: JS Plugin Integration
For Partners that do not have the development resources available to do a deep integration, we provide a lightweight javascript conversion script that does the heavy lifting for you.

  • On your "success" page (at whatever point in your signup process a referral is deemed "converted"), include this script tag:

  • <script src="//therestaurantheroes.com/js/lead.js"></script>
  • Build the Conversion Data Object outlined above.
    <script>
var data = {
  partner: 'your-partner-slug',// Partner slug
  product: 'your-product-slug',// Product slug
  email: 'customer@example.com', // Email
  // amount: 10.99        // Optional Amount
  // amounts: [{...},...]     // Optional amounts array
  // partner_data: {...}     // Optional custom data array
};
</script>
  • Fire the conversion request; if there are additional tasks you'd like to do based on the result of the request, you may write and provide a callback function to your request:

  • <script>
function anOptionalCallback(err, res = null){
  // your optional actions here...
  // Example, for debugging:
  console.log(err, res);
}


//Fire conversion request
trh.convert(data, anOptionalCallback);
</script>