---
title: "Create loyalty cards"
method: POST
path: "/v1/loyalty_programs/{loyaltyProgramId}/cards/batch"
tags: ["Loyalty cards"]
---

# Create loyalty cards

`POST /v1/loyalty_programs/{loyaltyProgramId}/cards/batch`

## Request

- Base URL: `https://yourbaseurl.talon.one`
- URL: `https://yourbaseurl.talon.one/v1/loyalty_programs/{loyaltyProgramId}/cards/batch`
- Auth: one of:
  - API key in header `Authorization`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/talon/apis/management-api/docs/v1/loyalty_programs/:loyaltyProgramId/cards/batch/post.ts> (a function with typed inputs; its response is checked against the schema)

> [!note] Management API endpoints are **not** meant to be used in real-time integrations that directly serve your end users. Rate limit: 3 requests per second.

Create a batch of loyalty cards in a specified [card-based loyalty
program](https://docs.talon.one/docs/product/loyalty-programs/overview#loyalty-program-types).

Customers can use loyalty cards to collect and spend loyalty points.

> [!important] **Note**
> - The specified card-based loyalty program must have a defined card code
>   format that is used to generate the loyalty card codes.
> - Trying to create more than 20,000 loyalty cards in a single request
>   returns an error message with a `400` status code.

## Path parameters

- `loyaltyProgramId` integer, required

## Request body

- LoyaltyCardBatch
  - `numberOfCards` integer, required: Number of loyalty cards in the batch.
  - `batchId` string: ID of the loyalty card batch.
  - `status` 'active' | 'inactive': Status of the loyalty cards in the batch.
  - `attributes` object: Set values for the [custom attributes](https://docs.talon.one/docs/dev/concepts/attributes#custom-attributes) of a loyalty card. These attributes must be created in the Campaign Manager before their values can be updated through this endpoint.
  - `cardCodeSettings` CodeGeneratorSettings
    - `validCharacters` string[], required: List of characters used to generate the random parts of a code.
    - `couponPattern` string, required: The pattern used to generate codes, such as coupon codes, referral codes, and loyalty cards. The character `#` is a placeholder and is replaced by a random character from the `validCharacters` set.

## Response `200`

OK

- LoyaltyCardBatchResponse
  - `numberOfCardsGenerated` integer, required: Number of loyalty cards in the batch.
  - `batchId` string, required: ID of the loyalty card batch.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `404`: Not found

## Changes

- **2026-11-07** `7ef1b9504c3a`: 2 warning, 1 info
  - the `allOf[subschema #1]/numberOfCards` request property's max was set to `20000.00`
  - the `allOf[subschema #1]/numberOfCards` request property's min was set to `1.00`
  - added the new optional request property `allOf[subschema #1]/attributes`

[Operation history](https://skmtc.dev/talon/apis/management-api/changes/v1/loyalty_programs/:loyaltyProgramId/cards/batch/post.md)

---

[API](https://skmtc.dev/talon/apis/management-api.md) - [All operations](https://skmtc.dev/talon/apis/management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/talon/apis/management-api/revisions/7ef1b9504c3a?raw)