# Redeem customer points for rewards

Processes a point redemption request and generates a discount code or reward.

How it works:
1. Validates customer has sufficient available points
2. Deducts points from customer's balance
3. Creates a discount code in Shopify (if applicable)
4. Creates a reward record with status "UNUSED"
5. Logs the transaction for audit trail
6. Returns updated customer loyalty information

Request body fields:
- customerId OR customerEmail: Identify the customer (provide one, not both)
- redeemRuleId: ID of the redemption rule to use (required)
- points: Number of points to redeem (optional - uses rule default if not provided)
- variantId: Product variant ID for product-specific rewards (optional, required for product rewards)

Redemption rule types:
- Fixed discount: Creates discount code for fixed amount off
- Percentage discount: Creates discount code for percentage off
- Free shipping: Creates free shipping discount code
- Free product: Creates discount code for free product (requires variantId)
- Store credit: Adds credit to customer's account

Important validation rules:
- Customer must have >= points required for redemption
- Customer must be enrolled in loyalty program
- Redemption rule must be active
- For product rewards, variantId is required
- Points are deducted immediately (transaction is atomic)

Common errors:
- "Insufficient points": Customer doesn't have enough available points
- "Redemption rule not found": Invalid redeemRuleId
- "Customer not found": Invalid customer ID/email
- "Variant ID required": Missing variantId for product reward
- "Customer not enrolled": Customer hasn't been enrolled in loyalty program

Best practices:
- Always check customer's availablePoints before attempting redemption
- Use GET /api/external/point-redeem-rules to get available redemption options
- Store the returned discount code for customer to use at checkout
- Monitor for 400 errors and handle insufficient points gracefully

Endpoint: POST /api/external/redeem-points

## Header parameters:

  - `X-API-Key` (string, required)
    API key for authentication

## Request fields (application/json):

  - `customerId` (integer,null)
    Shopify customer ID (numeric). Identifies which customer is redeeming points.
Provide either customerId OR customerEmail, not both.
Example: 67890
    Example: 67890

  - `customerEmail` (string,null)
    Customer's email address. Alternative to customerId for identifying the customer.
Provide either customerId OR customerEmail, not both.
Must be a valid email address that exists in your Shopify store.
Example: customer@example.com
    Example: "customer@example.com"

  - `redeemRuleId` (integer, required)
    ID of the redemption rule to use. Determines what reward the customer receives.
Use GET /api/external/point-redeem-rules to get available redemption options.
Must be an active redemption rule configured in your loyalty program.
Example: 5
    Example: 5

  - `points` (number,null)
    Number of points to redeem. Must be positive.
If not provided, uses the default points value from the redemption rule.
Customer must have at least this many available points.
Example: 100.0
    Example: 100

  - `variantId` (integer,null)
    Shopify product variant ID. Required when redeeming for product-specific rewards (free product).
Not required for discount codes or store credit rewards.
Must be a valid variant ID from your Shopify catalog.
Example: 12345678
    Example: 12345678

## Response 200 fields (application/json):

  - `availablePoints` (number)

  - `pendingPoints` (number)

  - `creditedPoints` (number)

  - `spentAmount` (number)

  - `storeCreditBalance` (number)

  - `achievableTierId` (integer)

  - `currentVipTier` (string)

  - `vipTierExpiredAt` (string)

  - `createAt` (string)

  - `rewardedForFacebook` (boolean)

  - `rewardedForPinterest` (boolean)

  - `rewardedForTwitter` (boolean)

  - `rewardedForInstagram` (boolean)

  - `rewardedForYoutube` (boolean)

  - `rewardedForTiktok` (boolean)

  - `rewardedForNewsLetter` (boolean)

  - `rewardedForSms` (boolean)

  - `referredCompleted` (integer)

  - `referralLink` (string)

  - `customerStatus` (string)
    Enum: "ACTIVE", "INACTIVE", "EXCLUDED", "EXCLUDED_BY_CUSTOMER"

  - `dob` (string)

  - `rewards` (array)

  - `rewards.id` (integer)

  - `rewards.shop` (string, required)

  - `rewards.customerId` (integer, required)

  - `rewards.description` (string)

  - `rewards.pointTransactionId` (integer)

  - `rewards.pointRedeemRuleId` (integer)

  - `rewards.discountCode` (string, required)

  - `rewards.usedAt` (string)

  - `rewards.orderId` (integer)

  - `rewards.orderName` (string)

  - `rewards.status` (string, required)
    Enum: "USED", "UNUSED", "REFUNDED", "EXPIRED", "SUBSCRIPTION_ACTIVE"

  - `rewards.expireDate` (string)

  - `rewards.variantId` (integer)

  - `rewards.discountCodeId` (string)

  - `rewards.productData` (string)

  - `rewards.usageCount` (integer)

  - `rewards.amount` (number)

  - `rewards.rewardType` (string)
    Enum: "STORE_CREDIT", "DISCOUNT_CODE", "POINTS"

  - `rewards.lastExpiryReminderSentDate` (string)

  - `rewardedForCreatingAccount` (boolean)

  - `rewardedForSharingOnFacebook` (boolean)

  - `rewardedForSharingOnX` (boolean)