Generates a batch of unique referral codes for a user to share with their network.

When to Use This Endpoint

• User requests new referral codes for sharing
• Bulk provisioning codes for influencers/partners
• Replacing exhausted codes (max_uses reached)
• Pre-generating codes for campaigns
• Creating limited-use codes for exclusive distributions

When NOT to Use This Endpoint

• Creating affiliate codes (use POST /v1/affiliates instead)
• Checking existing codes (use GET /v1/referral_codes)
• Using a code (use PATCH /v1/referral_codes/{code}/use)

Important Constraints

• Required Scope: service_role (service-to-service calls only)
• Default Quantity: 5 codes generated if not specified
• Quantity Range: 1-50 codes per request
• Code Format: Auto-generated alphanumeric codes (e.g., "ABC1234")
• Uniqueness: All codes globally unique across entire project
• Max Uses: Optional limit (null = unlimited uses)

Code Generation

• Codes are randomly generated alphanumeric strings
• Format: 7 characters (uppercase letters + numbers)
• Guaranteed unique within project
• Cannot specify custom code values (auto-generated for security)

Usage Limits

Set max_uses to control code usage:

• null (default): Unlimited uses
• 1: Single-use code (exclusive invite)
• 5, 10, 100: Limited campaign codes
• Once limit reached, code becomes unavailable

Common Errors

• 400 Bad Request:
  • Invalid quantity (must be 1-50)
  • Invalid user identifier format
  • Invalid max_uses value (must be positive integer or null)
• 403 Forbidden: API key lacks service_role scope
• 429 Too Many Requests: Rate limit exceeded

Best Practices

• Generate codes in batches to reduce API calls
• Use limited max_uses for exclusive campaigns
• Track code usage with GET /v1/referral_codes endpoint
• Consider campaign strategy when setting quantity

Related Endpoints

• GET /v1/referral_codes - View user's codes
• GET /v1/referral_codes/{code} - Check specific code
• PATCH /v1/referral_codes/{code} - Update code settings
• PATCH /v1/referral_codes/{code}/use - Use a code

Required API Key Scope: service_role