Back to My Kounta

Integrated Customer for Loyalty, Payments and CRM

Josh -

Customer Integration

While Kounta provides the capability for you to easily find, create and update customers for your integrated merchant, there are times where Kounta may not yet know about these customers.

As such we've provided the ability for a merchant to initiate a search directly within your application, allowing you to return one or more customers that match the search parameter, alongside extra information and integrated actions the merchant can initiate.

 

Enabling the Integrated Customer functionality

To enable this functionality, go to the Loyalty tab of your Kounta add-on configuration and turn on "Enable Integrated Customers" and configure the appropriate URLs. You can also enable Search functionality there.

 

Search URL

When we lookup the customer we will include the following parameters
keyword, company_id, site_id, and order_id in the url

Note that all IDs here are the Kounta IDs, and the order_id provided is just a placeholder ID at the time of the request, and will need to be included as-is in your response.

E.g.

https://www.rewardsprovider.com/customer-search?keyword=John%20Smith&site_id=123&company_id=456&order_id=111

You can return one or more customers that match the keyword search parameters. The response schema would look like:

{
"members": { "string member id": { "id": "string for member id in your system (required)", "first_name": "string (required)", "last_name": "string (optional)", "email_address": "string of members email (required)", "current_points": "string of how many points this member currently have. (optional)", "points_label": "string of the label under a member points and each rewards points (optional, default: 'Points')", "icon_url": "string URL for the customer image to display (optional, default: internal image, size: 300 x 300 circle)", "intro_text": "String of intro text shown above rewards (optional)", "params": { "Params": "Object of key: value pairs for parameters that are shown just below intro text (optional)" } } } }

Example Response

{
  "members": {
    "683573e5-23e6-2365-7a2a-9c5b53890ef4": {
      "id": "683573e5-23e6-2365-7a2a-9c5b53890ef4",
      "current_points": "587",
      "points_label": "Points",
      "email_address": "peter.parker@spiderman.com",
      "first_name": "Peter",
      "last_name": "Parker",
      "icon_url": "https:\/\/images.com\/image-user-large-02.jpg",
      "rewards": [
        "8494",
        "9900"
      ],
      "intro_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
      "params": {
        "Gender": "Male",
        "Date of Birth": "1962-08-26",
        "Points Redeemed": 240
      }
    },
    "1234567": {
      "id": "1234567",
      "current_points": "320",
      "points_label": "Points",
      "email_address": "clark.kent@superman.com",
      "first_name": "Clark",
      "last_name": "Kent",
      "icon_url": "https:\/\/images.com\/image-user-large-02.jpg",
      "rewards": [
        "8494",
        "9100"
      ],
      "intro_text": "VIP member who enjoys gluten free food.",
      "params": {
        "Gender": "Male",
        "Date of Birth": "1959-04-02",
        "Points Redeemed": 120
      }
    }
  }
}

Rewards URL

When an individual customer is selected, a Rewards requests will be made with the customer_id (Kounta ID) and reference_id (you're ID). The reference ID is what you've previously sent us as documented here.

E.g.

https://www.rewardsprovider.com/reward-lookup?customer_id=789&reference_id=911&site_id=123&company_id=456&order_id=111

Note a 'reward' could indicate any type of action, it could infer payment, discount, reward, or coupon. Basically it allows you to prompt the merchant to take some action on the customer and/or order as needed.

The expected response is similar, except you can now just return the individual member record and the rewards associated with that member.

{
  "members": {
    "string member id": {
      "id": "string for member id in your system (required)",
      "first_name": "string (required)",
      "last_name": "string (optional)",
      "email_address": "string of members email (required)",
      "current_points": "string of how many points this member currently have. (optional)",
      "points_label": "string of the label under a member points and each rewards points (optional, default: 'Points')",
      "icon_url": "string URL for the customer image to display (optional, default: internal image, size: 300 x 300 circle)",
      "rewards": [
        "array[string] of reward ids (optional)"
      ],
      "intro_text": "String of intro text shown above rewards (optional)",
      "params": {
        "Params": "Object of key: value pairs for parameters that are shown just below intro text (optional)"
      }
    }
  },
  "rewards": {
    "string reward id": {
      "id": "string internal reward id in your system (required)",
      "redeem_url": "string URL for redeeming this reward, which will be called when the POS user clicks redeem on this reward. It needs to include the order_id we sent you, such as 'order_id=1234' in the URL. We will add the following parameters: companyId, siteId, customerId, and optionally quantity (required)",
      "title": "string reward title (required)",
      "terms": "string any details\/text you want to display for the reward (optional)",
      "points_required": "string number of points required to redeem reward (optional)",
      "points_label": "string of the label shown next to number of points (optional, default: member.points_label then 'Points' if empty)",
      "action_label": "string for the action button for redemption (optional, default: 'Redeem')",
      "variable_quantity": "boolean representing whether to allow user to select number of points to redeem (up to points_required amount) when they click 'Redeem'. This amount will be sent as an additional parameter: &quantity=50 (optional)"
    }
  }
}

Example Response

{
  "members": {
    "683573e5-23e6-2365-7a2a-9c5b53890ef4": {
      "id": "683573e5-23e6-2365-7a2a-9c5b53890ef4",
      "current_points": "587",
      "points_label": "Points",
      "email_address": "peter.parker@spiderman.com",
      "first_name": "Peter",
      "last_name": "Parker",
      "icon_url": "https:\/\/images.com\/image-user-large-02.jpg",
      "rewards": [
        "8494",
        "9900"
      ],
      "intro_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
      "params": {
        "Gender": "Male",
        "Date of Birth": "1962-08-26",
        "Points Redeemed": 240
      }
    }
  },
  "rewards": {
    "8494": {
      "id": "8494",
      "redeem_url": "https:\/\/yoursite.com\/customerrewards?redeem=1&order_id=1234&itemId=8897&rewardId=8494&merchantId=50",
      "title": "Pay with Prepaid Credit",
      "terms": "Use available balance to pay for this order",
      "points_required": "15",
      "points_label": "Dollars",
      "action_label": "Checkout",
      "variable_quantity": true
    },
    "9900": {
      "id": "9900",
      "redeem_url": "https:\/\/yoursite.com\/customerrewards?redeem=1&order_id=1234&itemId=4453&rewardId=9900&merchantId=50",
      "title": "Free Coffee",
      "terms": "Use your points for a free coffee",
      "points_required": "20",
      "points_label": "Points",
      "action_label": "Redeem"
    }
  }
}

Redemption

We will use the redeem_url you provided for the reward, replacing the "order_id=1234" placeholder with a valid ID you can use to call the API and update the order. After updating the order via the API you should return a response in the format:

{
  success: boolean (true or false),
  error: "error message if success was false, else can be omitted"
}

Errors

If you need to return an error, please return it in the format:

{
  error: "Your error message here"
}

 

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk