​

Overview

This guide explains how to integrate partner-initiated campaign creation and reward issuance using the Thanx Partner API. This integration allows partners to programmatically create campaigns, configure reward variants, and issue rewards to users — all from within their own platform. Common use cases include feedback-driven service recovery, automated marketing triggers, loyalty activation based on external events, and CRM-driven reward distribution. The integration is entirely server-to-server. Partners trigger reward issuance on behalf of merchants by identifying users via email or phone number. By building to these endpoints, partners can deliver a unified workflow where merchants no longer need to switch between systems to act on insights and issue rewards. This reduces friction, speeds up execution, and creates a tighter feedback loop between partner platforms and Thanx loyalty.

---

​

Credentials You Will Need

For this kind of integration, you will be provided the following credentials:

• Client ID
• Access Token

These credentials grant access to all merchants that have explicitly opted into the specified integration. All merchants accessible to these credentials can be listed via the Get Merchants endpoint. Each API credential is configured with an agreed upon scope — granting access to a subset of the API endpoints available. The campaign and reward issuance endpoints require the rewards.issue scope. Use the Get Scopes endpoint to verify which scopes your credentials have access to.

---

​

Endpoints We Will Be Using

The following endpoints are the minimum required for this integration:

1. List Reward Templates — Discover available reward templates for a merchant
2. Create Campaign — Create a campaign with reward variants
3. Issue Rewards — Issue rewards to users by email or phone
4. Get Issuance Job — Poll for issuance job completion status

---

​

Postman API Collection

Here you will find the Partner API Postman Collection to import directly within your API testing tool. This collection includes sample values for credentials. Replace them with those provided by your Thanx representative to ensure successful API calls. Partner API Postman Collection

---

​

API Interaction Workflow

---

​

Integration Flow

​

1 — Discovery

Before creating campaigns or issuing rewards, the partner must discover which merchants are accessible and what reward templates each merchant has published. Call the Get Merchants endpoint to retrieve the list of merchants that have opted into the integration. For each merchant, call the List Reward Templates endpoint to retrieve available reward templates. These templates define the types of rewards that can be issued (e.g., “Free Coffee”, “$5 Off Next Visit”). Merchant and reward template data should be cached and refreshed periodically rather than fetched on every operation. Endpoints used in this step:

1. Get Merchants Lists all merchants accessible to the integration partner.
2. List Reward Templates Returns published reward templates for a given merchant.
3. Get Reward Template (Optional) Returns details of a specific reward template.

---

​

2 — Campaign Creation

A campaign defines the time window, terms, and reward variants for issuing rewards to users. Each campaign must have between 1 and 4 variants. Treatment variants specify a reward_template_id that defines the reward to be issued. Control variants (named “Control”) do not require a reward_template_id and are used for A/B testing — measuring the impact of rewards versus no reward. The partner provides the following when creating a campaign:

• merchant_id — The merchant the campaign belongs to
• name — Campaign name (e.g., “Service Recovery - Negative Feedback”)
• objective — Campaign objective (e.g., “Re-engage guests after poor experience”)
• fine_print — Terms and conditions
• start_at / end_at — Campaign active window (ISO8601)
• redeemable_from / redeemable_to — When issued rewards can be redeemed (ISO8601)
• variants — Array of 1–4 variants, each with a name and optional reward_template_id

Campaigns can be created once per use case (e.g., one for service recovery, one for VIP rewards) and reused for multiple issuance jobs, or created on-the-fly per event depending on the partner’s workflow. Endpoints used in this step:

1. Create Campaign Creates a new partner-initiated campaign with reward variants for a merchant.
2. List Campaigns (Optional) Lists all active partner-initiated campaigns for a merchant.
3. Get Campaign (Optional) Retrieves details of a specific campaign.

---

​

3 — Reward Issuance

This is the core action. When the partner’s platform determines that a user should receive a reward (e.g., a guest left negative feedback, a VIP guest made a purchase), it calls the Issue Rewards endpoint. Rewards are issued by identifying users via email or phone number. Phone numbers must be in E.164 format (e.g., +12025551234). Up to 10,000 identifiers can be submitted per issuance job. The endpoint initiates an asynchronous job and returns immediately with a 202 Accepted response containing the issuance job ID. Rewards are processed in the background. Use the X-Idempotency-Key header to prevent duplicate issuance jobs if the same request is retried. Endpoints used in this step:

1. Issue Rewards Initiates an asynchronous reward issuance job for a given campaign variant.

---

​

4 — Monitoring & Completion

After initiating an issuance job, the partner should poll the Get Issuance Job endpoint to track progress. Job states progress as follows: pending → processing → completed or failed. When the job reaches the completed state, a summary field is included with:

• success_count — Number of rewards successfully issued
• failure_count — Number of failed issuances
• failures — Array of failure details including identifier_index, identifier_type, and error message

Partners should surface success and failure information to merchants as appropriate. Alternatively, instead of polling, partners can subscribe to webhooks (see below). Endpoints used in this step:

1. Get Issuance Job Returns the current status of a reward issuance job.

---

​

5 — Revocation (If Needed)

If rewards were issued in error (e.g., fraudulent feedback, incorrect campaign), the partner can revoke all rewards from a given issuance job. Only issuance jobs in a completed or failed state can be revoked. Jobs that are pending or processing will return a 422 error. Jobs that are already revoking or revoked will also return a 422 error. Revocation is processed asynchronously. The endpoint returns 202 Accepted and the job transitions to a revoking state while rewards are being revoked in the background. Endpoints used in this step:

1. Revoke Issuance Job Revokes all rewards issued by a given issuance job.

---

​

Webhooks (Optional)

Instead of polling with the Get Issuance Job endpoint, partners can subscribe to webhooks for real-time notifications. To have webhooks enabled, reach out to developer.support@thanx.com. Webhook requirements:

• Endpoint must be a valid HTTPS URL
• Must respond to POST requests within 15 seconds
• Webhooks are not configured to retry by default — any missed data can be collected via bulk data transfer mechanisms

---

​

Rate Limits

Integration partners should not exceed a rate of 5 requests per second and 2,000 requests per 15 minutes. These are hard limits and the API will return 429 Too Many Requests once exceeded. Rate-limited requests can and should be retried. One such strategy is through an exponential backoff approach. Should your specific integration use-case require higher API throughput, please reach out to developer.support@thanx.com to request an increase.

---

​

Certification

Once your integration has been built and developed against the sandbox environment, please reach out to developer.support@thanx.com to go through a lightweight but mandatory certification process. For basic integration use-cases, certification is quick and normally takes no more than a few days depending on the scope of integration. This process is mainly designed to ensure the integration is working as intended without risking any negative impact on live customers (merchant or consumer). Each net new integration use-case should be re-certified as new use-cases will very likely require different scoping. Launching new merchants on certified integration use-cases does not require re-certification. The certification process will start with a video call with members of our developer support team. On the call, your team will demo the integration and all the supported use-cases. After the demo of all supported use-cases, our team will validate the following:

​

Interactions

1. Discovery: retrieving merchants and reward templates
2. Campaign creation with appropriate variants
3. Reward issuance to users by email and/or phone
4. Issuance job monitoring (polling or webhook-based)
5. Error handling for failed issuances
6. Revocation workflow (if applicable)

​

API

1. Requests must include all required headers (Authorization, X-ClientId, Accept-Version, Content-Type, User-Agent)
2. Requests must not be unnecessarily duplicated
3. Idempotency keys should be used for reward issuance requests
4. Error messages should be handled gracefully
5. Requests should only be issued at a reasonable frequency (e.g., don’t rapidly poll the API for changes)

​

Product Capabilities

The following product capabilities must be supported in your campaign and reward issuance integration:

​

Campaign Configuration

Partners must be able to create campaigns with appropriate time windows, terms, and reward variants. Campaigns must reference valid reward templates retrieved from the List Reward Templates endpoint.

​

Reward Issuance

Partners must be able to issue rewards to users by email or phone number via the Issue Rewards endpoint. Partners should handle the asynchronous nature of issuance jobs by either polling the Get Issuance Job endpoint or subscribing to webhooks.

​

Error & Failure Handling

Partners must gracefully handle issuance failures. When an issuance job completes with failures, the partner should surface relevant error information (e.g., invalid email, user not found) and should not silently drop failed issuances.

---

​

Additional Endpoints to Enhance the Experience