> ## 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. # Creategiftcard > Create a new gift card in pending status with a generated card number and security code. Validates and sets the expiration (defaults to 1 year, must not exceed 5 years), sanitizes the provided custom message to prevent XSS, generates a unique 16-digit card number and a 6-digit security code, persists the card with a zero balance and the requested initialValue, and returns the persisted card representation. Parameters: data (CreateGiftCardRequest): Request payload containing initialValue, merchantId, optional customer fields, expiration, isPhysical, designTemplate, and customMessage. Returns: GiftCardResponse: The newly created gift card data (status will be "pending"); the security code is stored but not returned. ## OpenAPI ````yaml https://api.loyalty.dog/openapi.json post /v2/giftcards/programs/{programId}/cards 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: post: tags: - Gift Cards summary: Creategiftcard description: >- Create a new gift card in pending status with a generated card number and security code. Validates and sets the expiration (defaults to 1 year, must not exceed 5 years), sanitizes the provided custom message to prevent XSS, generates a unique 16-digit card number and a 6-digit security code, persists the card with a zero balance and the requested initialValue, and returns the persisted card representation. Parameters: data (CreateGiftCardRequest): Request payload containing initialValue, merchantId, optional customer fields, expiration, isPhysical, designTemplate, and customMessage. Returns: GiftCardResponse: The newly created gift card data (status will be "pending"); the security code is stored but not returned. operationId: createGiftCard_v2_giftcards_programs__programId__cards_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: 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/CreateGiftCardRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GiftCardResponse' '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 CreateGiftCardRequest: properties: initialValue: anyOf: - type: number maximum: 10000 minimum: 0.01 - type: string pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$ title: Initialvalue 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 merchantId: $ref: '#/components/schemas/PydanticObjectId' expiresAt: anyOf: - type: string format: date-time - type: 'null' title: Expiresat isPhysical: type: boolean title: Isphysical default: false designTemplate: anyOf: - type: string maxLength: 100 - type: 'null' title: Designtemplate customMessage: anyOf: - type: string maxLength: 500 - type: 'null' title: Custommessage deliverAt: anyOf: - type: string format: date-time - type: 'null' title: Deliverat type: object required: - initialValue - merchantId title: CreateGiftCardRequest GiftCardResponse: properties: id: $ref: '#/components/schemas/PydanticObjectId' cardNumber: type: string title: Cardnumber balance: type: string title: Balance initialValue: type: string title: Initialvalue status: $ref: '#/components/schemas/GiftCardStatus' createdAt: type: string format: date-time title: Createdat updatedAt: anyOf: - type: string format: date-time - type: 'null' title: Updatedat activatedAt: anyOf: - type: string format: date-time - type: 'null' title: Activatedat expiresAt: type: string format: date-time title: Expiresat suspendedReason: anyOf: - type: string - type: 'null' title: Suspendedreason suspendedUntil: anyOf: - type: string format: date-time - type: 'null' title: Suspendeduntil suspendedAt: anyOf: - type: string format: date-time - type: 'null' title: Suspendedat customerId: anyOf: - $ref: '#/components/schemas/PydanticObjectId' - type: 'null' customerEmail: anyOf: - type: string - type: 'null' title: Customeremail customerPhone: anyOf: - type: string - type: 'null' title: Customerphone customerName: anyOf: - type: string - type: 'null' title: Customername senderName: anyOf: - type: string - type: 'null' title: Sendername merchantId: $ref: '#/components/schemas/PydanticObjectId' merchantName: anyOf: - type: string - type: 'null' title: Merchantname isPhysical: type: boolean title: Isphysical designTemplate: anyOf: - type: string - type: 'null' title: Designtemplate customMessage: anyOf: - type: string - type: 'null' title: Custommessage lastFourDigits: type: string title: Lastfourdigits programId: $ref: '#/components/schemas/PydanticObjectId' deliverAt: anyOf: - type: string format: date-time - type: 'null' title: Deliverat delivered: type: boolean title: Delivered default: false card: anyOf: - $ref: '#/components/schemas/PassCard' - type: 'null' type: object required: - id - cardNumber - balance - initialValue - status - createdAt - updatedAt - activatedAt - expiresAt - suspendedReason - suspendedUntil - suspendedAt - customerId - customerEmail - customerPhone - customerName - merchantId - isPhysical - designTemplate - customMessage - lastFourDigits - programId - card title: GiftCardResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError GiftCardStatus: type: string enum: - pending - active - suspended - expired - voided - depleted title: GiftCardStatus description: Gift card status enumeration. PassCard: properties: serialNumber: type: string title: Serialnumber passTypeIdentifier: type: string title: Passtypeidentifier url: type: string minLength: 1 format: uri title: Url type: object required: - serialNumber - passTypeIdentifier - url title: PassCard description: |- The customer card object Attributes: serialNumber (str): The serial number of the customer pass passTypeIdentifier (str): The pass type identifier of the customer pass url (str): The shareable URL of the customer pass 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. ````