​

Overview

This guide explains how to integrate subscriber ingestion using the Thanx Partner API. This integration allows partners and merchants to programmatically opt email addresses into a merchant’s Thanx loyalty marketing. Common use cases include syncing newsletter signups, importing CRM contacts, connecting email marketing platforms, and ingesting subscribers from website signup forms. The integration is entirely server-to-server. Partners submit subscriber information on behalf of merchants, and Thanx handles targeted loyalty outreach to encourage full loyalty program enrollment. This is one of the simplest Thanx API integrations — it requires a single endpoint and minimal configuration.

---

​

Credentials You Will Need

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

• Client ID — used in the X-ClientId header
• Access Token — used in the Authorization header

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 subscriber ingestion endpoint requires the subscribers.write scope. Use the Get Scopes endpoint to verify which scopes your credentials have access to. All API requests must include the required headers documented in the Partner API Overview — including Authorization, X-ClientId, Accept-Version, Content-Type, and User-Agent.

---

​

Endpoints We Will Be Using

The following endpoints are required for this integration:

1. Get Merchants — Retrieve your merchant ID
2. Create Subscriber — Opt an email address into a merchant’s loyalty marketing

---

​

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 — Setup & Discovery

Before creating subscribers, the partner must retrieve the merchant ID for the merchant whose loyalty marketing subscribers will be opted into. Call the Get Merchants endpoint to retrieve the list of merchants that have opted into the integration. Each merchant in the response includes an id that is required when creating subscribers. For single-merchant integrations, this only needs to be done once. The merchant ID can then be stored and reused for all subsequent subscriber creation requests. Endpoints used in this step:

1. Get Merchants Lists all merchants accessible to the integration partner.
2. Get Scopes (Optional) Verifies which API scopes your credentials have access to. Useful for confirming subscribers.write is available.

---

​

2 — Creating Subscribers

This is the core action. When a user signs up for a newsletter, submits a form, or is otherwise identified as a marketing prospect, the partner calls the Create Subscriber endpoint to opt them into the merchant’s Thanx loyalty marketing. The request requires:

• merchant_id — The merchant to subscribe the user to
• email — The subscriber’s email address

Optional fields that enrich the subscriber profile:

• first_name — Subscriber’s first name
• last_name — Subscriber’s last name
• birth_date — Subscriber’s birth date as a nested object: { "month": 8, "day": 14 }
• zip_code — Subscriber’s zip code

Note that all subscriber fields must be wrapped inside a subscriber key in the request body. See the Create Subscriber endpoint reference for the exact payload structure. Important behavior notes:

• The endpoint responds with 201 Created for any valid email address, even if the email already exists in the system. This is by design — it prevents unintentional PII exposure for existing records.
• The response only contains the accepted email address.
• The only time the endpoint returns 400 Bad Request is when the input email address is invalid.
• All subscriber information submitted via API must have explicit user consent to participate in the merchant’s marketing.

Endpoints used in this step:

1. Create Subscriber Opts an email address into the specified merchant’s loyalty marketing.

---

​

Subscriber vs. User

It is important to understand the distinction between a subscriber and a user in the Thanx platform: If your integration requires creating full loyalty program users (not just marketing subscribers), please reach out to developer.support@thanx.com to discuss a Consumer API integration instead.

---

​

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

Before receiving production credentials, all integrations must go through Thanx’s certification process. For subscriber ingestion, the certification team will validate the following:

​

Interactions

1. Subscriber creation with valid email addresses
2. Handling of optional subscriber fields (name, birth date, zip code)
3. Bulk ingestion workflow (if applicable)
4. Ongoing sync mechanism (if applicable)

​

API

1. Requests include all required headers
2. Requests are not unnecessarily duplicated
3. Error messages are handled gracefully
4. Requests are issued at a reasonable frequency (e.g., not rapidly submitting the same email)

​

Consent

1. All subscriber data submitted to Thanx has explicit user consent for the merchant’s marketing
2. Partners do not submit email addresses obtained without proper opt-in

---

​

Additional Endpoints to Enhance the Experience