Storefront APIs

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Allows the authenticated customer to redeem their loyalty points for rewards.

Redemption flow:

1. Customer selects a reward from available options
2. Frontend calls this endpoint with redeemRuleId
3. System validates customer has sufficient points
4. Points are deducted from available balance
5. Discount code is created in Shopify
6. Reward record is created with status "UNUSED"
7. Transaction is logged
8. Updated loyalty info is returned
9. Customer receives discount code to use at checkout

Request body fields:

• redeemRuleId: ID of reward to redeem (required) Get available options from GET /loyalty/cp/api/customer-loyalty
• points: Override default points (optional) If not provided, uses the redemption rule's default point value
• variantId: Required for product-specific rewards (optional) Shopify variant ID for "free product" type rewards

Authentication: Requires customer JWT token. The authenticated customer is the one redeeming points. Cannot redeem points on behalf of another customer.

Validation checks:

• Customer is authenticated
• Customer has sufficient availablePoints
• Redemption rule exists and is active
• For product rewards, variantId is provided
• Customer is enrolled in loyalty program
• Customer status is ACTIVE (not excluded)

What happens to points:

• Deducted from availablePoints immediately
• Added to lifetime spending total
• Transaction created with type "REDEEMED"
• Cannot be undone (points deduction is final)

Discount code generation:

• For discounts: Creates Shopify discount code
• Code is unique per customer
• Has expiry date if configured
• Minimum purchase amount if configured
• Product/collection restrictions if configured

Store credit rewards:

• Adds value to storeCreditBalance instead of creating discount code
• Can be used as payment method at checkout
• Managed separately from Shopify discount codes

Error scenarios:

• Insufficient points: availablePoints < required points
• Invalid rule: redeemRuleId doesn't exist or is inactive
• Missing variantId: Required for product rewards
• Customer not enrolled: Must enroll first
• Customer excluded: EXCLUDED or EXCLUDED_BY_CUSTOMER status
• System error: Shopify API failure, discount code creation failure

Best practices:

1. Check availablePoints before showing redemption options
2. Display point cost clearly to customer
3. Show expected reward (discount %, amount, etc.)
4. Handle errors gracefully with clear messages
5. After success, show discount code prominently
6. Provide copy-to-clipboard functionality for code
7. Explain when/how to use the discount code

Example response handling:

// After successful redemption
const response = await redeemPoints(ruleId);
// Find the newly created reward
const newReward = response.rewards.find(r => r.status === 'UNUSED');
// Display to customer
showDiscountCode(newReward.discountCode, newReward.expiryDate);

Common UI flow:

1. Display available redemption options with point costs
2. Customer clicks "Redeem"
3. Show confirmation dialog with point cost
4. Call this endpoint
5. On success: Show discount code in modal/banner
6. Update points display with new balance
7. Add code to "My Rewards" list