Skip to main content

How to Integrate Reward Redemptions with a 3rd Party Fulfillment Tool

This guide describes how to programmatically export redemption data and send it to a fulfillment tool of your choice using our API.

Bob avatar
Written by Bob
Updated over 2 months ago

Some brands prefer to handle reward fulfillment outside of SocialLadder—using external platforms like shipping providers, gift card tools, or other fulfillment software. This guide walks your development team through how to programmatically export redemption data from SocialLadder and send it to a fulfillment tool of your choice using our API.

📌 Overview

When an ambassador redeems a reward in SocialLadder, our system captures all relevant details, including:

  • Reward name

  • Contact and shipping information

  • Unique redemption code

  • Date and status

If you want to handle fulfillment externally, you can pull this data via API and pass it to your own system or any third-party tool.

🧑‍💻 Step-by-Step Integration Guide

1. Get the Report ID for Redemption Details

Use the Reports endpoint to get a list of available reports.

Endpoint:

GET https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/reports

Look for the report with the name:

"DisplayName": "Redemption Details"

Example Response:

{ "ReportList": [ { "ID": 23, "DisplayName": "Redemption Details" } ] }

✅ In this example, the report ID is 23.

2. Fetch Redemption Data

Use the Report Data endpoint to export the redemption data using the report ID.

Endpoint:

GET https://socialladder.rkiapps.com/SocialLadderAPI/api/v1/reportData?reportID=23&apiKey=YOUR_API_KEY

🛠 Replace 23 with your actual report ID and include your API key.

Example Fields Returned:

  • REWARD NAME

  • REDEMPTION CODE

  • EMAIL ADDRESS

  • ADDRESS, CITY, STATE, ZIP CODE

  • PHONE NUMBER

  • REDEMPTION DATE

3. Handle Pagination

Each API response includes up to 200 rows. If there are more redemptions, the response will include a PreviousPageURL like this:

"PreviousPageURL": "https://socialladder...&beforeID=2"

To retrieve additional rows:

  • Use the PreviousPageURL to get the next page

  • Repeat until no more pagination URL is returned

4. Transform the Data

You’ll need to map each redemption record to match the format required by your third-party fulfillment tool. The key fields often include:

Field

Description

REWARD NAME

Name of the redeemed item

REDEMPTION CODE

Unique code for 100% off reward

FIRST NAME / LAST NAME

Ambassador's name

EMAIL ADDRESS

Used for digital delivery or contact

ADDRESS

Required for physical shipments

STATUS

e.g., Wait for Delivery

5. Send to Your Fulfillment Tool

Once the data is formatted, use the fulfillment platform’s API to submit each redemption. Every third-party tool will have different requirements, so refer to their documentation.

⚠️ You are responsible for:

  • Authentication and API keys for the 3rd party tool

  • Formatting payloads correctly

  • Handling error responses or retries

✅ Example Workflow

  1. Pull redemptions details from SocialLadder via API

  2. Iterate through the redemptions until you reach the last redemption previously processed

  3. Map and send to your fulfillment tool’s API

  4. Store the maximum VIEWROW_ID for the next run to know when you have reached redemptions you've already processed

🔐 Security Reminders

  • Always use HTTPS for API communication

  • Store your API keys securely

  • Validate all external inputs and outputs

🧩 Need Help?

If you have questions or want help setting up your integration, contact your Customer Success Manager or email us at support@socialladderhelp.com.

Related Links:

Did this answer your question?