> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thanx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriber Ingestion

# 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](/partner/metadata/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](/partner/metadata/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](/partner/overview#headers) — 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](/partner/metadata/get-merchants) — Retrieve your merchant ID
2. [Create Subscriber](/partner/subscribers/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](/overview/api_collections)

***

## API Interaction Workflow

```mermaid theme={null}
flowchart LR
  A["Get Merchants"] --> B["Get merchant_id"]
  B --> C["Create Subscriber"]
  C -->|"201 Created"| D["Success"]
  C -->|"400 Bad Request"| E["Invalid Email"]
  C -->|"429 Too Many Requests"| F["Backoff & Retry"]
  F --> C

  classDef default fill:transparent,stroke:#13c1bf,stroke-width:1px;
```

***

## 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](/partner/metadata/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](/partner/metadata/get-merchants)
   Lists all merchants accessible to the integration partner.

2. [Get Scopes](/partner/metadata/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](/partner/subscribers/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](/partner/subscribers/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](/partner/subscribers/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:

|                       | Subscriber                                                           | User                                                                                 |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Created via**       | `POST /partner/subscribers` (Partner API)                            | `POST /users` (Consumer API)                                                         |
| **What they receive** | Targeted marketing from the merchant to encourage loyalty enrollment | Full loyalty program access: rewards, points, tiers, cards                           |
| **Requirements**      | Email address + marketing consent                                    | Full enrollment flow with legal requirements (card linkage, ToS acceptance)          |
| **Complexity**        | Low — single endpoint                                                | High — requires Consumer API integration with SSO, card enrollment, legal compliance |

If your integration requires creating full loyalty program users (not just marketing subscribers), please reach out to [developer.support@thanx.com](mailto:developer.support@thanx.com) to discuss a [Consumer API](/consumer/overview) 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](mailto:developer.support@thanx.com) to request an increase.

***

## Certification

<Tip>
  **Before submitting for certification**, download and complete the self-check checklist to verify your integration meets all requirements. This reduces back-and-forth during certification and helps ensure a first-attempt pass.
</Tip>

<a href="/assets/Pre_Cert_Checklist_Subscriber_Ingestion.md" download>
  Download Subscriber Ingestion Pre-Certification Self-Check
</a>

Before receiving production credentials, all integrations must go through Thanx's [certification process](/partner/overview#certification). 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](/partner/overview#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

### Product Guide

<Snippet file="certification/product-guide.mdx" />

***

## Additional Endpoints to Enhance the Experience

| Endpoint                                             | Purpose                                                                                                                             |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **[Get Merchants](/partner/metadata/get-merchants)** | Retrieve the list of merchants accessible to the integration. Use this to populate merchant selection in your platform.             |
| **[Get Locations](/partner/metadata/get-locations)** | Retrieve locations for accessible merchants. Useful if your platform operates at the location level rather than the merchant level. |
| **[Get Scopes](/partner/metadata/get-scopes)**       | Verify which API scopes your credentials have access to. Useful for onboarding diagnostics.                                         |