> ## Documentation Index > Fetch the complete documentation index at: https://docs.loyalty.dog/llms.txt > Use this file to discover all available pages before exploring further. # Issue multiple gift cards > ### Bulk Issue Gift Cards Issues multiple gift cards in a single request. For counts up to the sync threshold (`gift_card_bulk_issue_sync_threshold`, default 50) the cards are created synchronously and returned immediately. For larger batches the request is accepted asynchronously and a task ID is returned for polling. **Issuance modes**: - `count` (integer) — count-only: cards have no recipient data; a CSV download link is returned so the merchant can distribute the numbers. - `recipients` (list) — per-recipient: each card is optionally pre-populated with the given customer info and a notification is dispatched. **Path Parameters**: - `programId`: MongoDB ObjectId of the loyalty program **Request Body** (`BulkIssueGiftCardRequest`): - `initialValue`: Starting balance (0.01 – 10,000.00) - `isPhysical`: `true` for physical cards - `designTemplate`: Optional design-template slug - `expiresAt`: Optional explicit expiry; defaults to +365 days - `count` **or** `recipients`: Mutually exclusive **Response (sync ≤ threshold)**: - HTTP 201 with `BulkIssuanceSyncResponse` **Response (async > threshold)**: - HTTP 202 with `BulkIssuanceAsyncResponse` (`taskId`, `status`) **Idempotency**: - Pass `Idempotency-Key` header to make the request safely retryable. ## OpenAPI ````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/programs/{programId}/cards/bulk openapi: 3.1.0 info: title: LoyaltyDog description: >- Welcome to the LoyaltyDog API! This API provides access to our loyalty program features, allowing you to integrate with various platforms and manage your loyalty data. Want to query LoyaltyDog via an AI assistant (Claude, Cursor, Windsurf)? See the [MCP Integration guide](https://loyaltydog.ai/playground#mcp). termsOfService: https://loyalty.dog/loyalty-program-terms-service contact: name: LoyaltyDog Support url: https://loyalty.dog/contact-us email: support@loyalty.dog version: 1.0.1 servers: - url: https://api.loyalty.dog description: Production security: - bearerAuth: [] paths: /v2/giftcards/programs/{programId}/cards/bulk: post: tags: - Gift Cards summary: Issue multiple gift cards description: >- ### Bulk Issue Gift Cards Issues multiple gift cards in a single request. For counts up to the sync threshold (`gift_card_bulk_issue_sync_threshold`, default 50) the cards are created synchronously and returned immediately. For larger batches the request is accepted asynchronously and a task ID is returned for polling. **Issuance modes**: - `count` (integer) — count-only: cards have no recipient data; a CSV download link is returned so the merchant can distribute the numbers. - `recipients` (list) — per-recipient: each card is optionally pre-populated with the given customer info and a notification is dispatched. **Path Parameters**: - `programId`: MongoDB ObjectId of the loyalty program **Request Body** (`BulkIssueGiftCardRequest`): - `initialValue`: Starting balance (0.01 – 10,000.00) - `isPhysical`: `true` for physical cards - `designTemplate`: Optional design-template slug - `expiresAt`: Optional explicit expiry; defaults to +365 days - `count` **or** `recipients`: Mutually exclusive **Response (sync ≤ threshold)**: - HTTP 201 with `BulkIssuanceSyncResponse` **Response (async > threshold)**: - HTTP 202 with `BulkIssuanceAsyncResponse` (`taskId`, `status`) **Idempotency**: - Pass `Idempotency-Key` header to make the request safely retryable. operationId: bulkIssueGiftCards_v2_giftcards_programs__programId__cards_bulk_post parameters: - name: programId in: path required: true schema: anyOf: - $ref: '#/components/schemas/PydanticObjectId' - type: 'null' title: Programid - name: cardId in: query required: false schema: anyOf: - $ref: '#/components/schemas/PydanticObjectId' - type: 'null' title: Cardid - name: idempotency-key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key - name: X-Eposn-Customer-Token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Eposn-Customer-Token - name: X-Eposn-Merchant-Token in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Eposn-Merchant-Token requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkIssueGiftCardRequest' responses: '201': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/BulkIssuanceSyncResponse' - $ref: '#/components/schemas/BulkIssuanceAsyncResponse' title: >- Response Bulkissuegiftcards V2 Giftcards Programs Programid Cards Bulk Post '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: PydanticObjectId: type: string maxLength: 24 minLength: 24 pattern: ^[0-9a-f]{24}$ example: 5eb7cf5a86d9755df3a6c593 BulkIssueGiftCardRequest: properties: initialValue: anyOf: - type: number maximum: 10000 minimum: 0.01 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Initialvalue isPhysical: type: boolean title: Isphysical default: false designTemplate: anyOf: - type: string maxLength: 100 - type: 'null' title: Designtemplate expiresAt: anyOf: - type: string format: date-time - type: 'null' title: Expiresat count: anyOf: - type: integer minimum: 1 - type: 'null' title: Count recipients: anyOf: - items: $ref: '#/components/schemas/BulkIssueRecipient' type: array - type: 'null' title: Recipients type: object required: - initialValue title: BulkIssueGiftCardRequest BulkIssuanceSyncResponse: properties: issuedCount: type: integer title: Issuedcount cards: items: $ref: '#/components/schemas/BulkIssuedCardSummary' type: array title: Cards csvDownloadUrl: anyOf: - type: string - type: 'null' title: Csvdownloadurl failedCount: anyOf: - type: integer - type: 'null' title: Failedcount type: object required: - issuedCount - cards title: BulkIssuanceSyncResponse BulkIssuanceAsyncResponse: properties: taskId: type: string title: Taskid status: type: string title: Status default: pending type: object required: - taskId title: BulkIssuanceAsyncResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError BulkIssueRecipient: properties: customerEmail: anyOf: - type: string format: email - type: 'null' title: Customeremail customerPhone: anyOf: - type: string format: phone - type: 'null' title: Customerphone customerName: anyOf: - type: string maxLength: 255 - type: 'null' title: Customername senderName: anyOf: - type: string maxLength: 255 - type: 'null' title: Sendername customMessage: anyOf: - type: string maxLength: 500 - type: 'null' title: Custommessage type: object title: BulkIssueRecipient BulkIssuedCardSummary: properties: id: type: string title: Id cardNumber: type: string title: Cardnumber lastFourDigits: type: string title: Lastfourdigits type: object required: - id - cardNumber - lastFourDigits title: BulkIssuedCardSummary ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT access token obtained from POST /v2/token. ````