Visit Limits

Visit limits allow you to control how many times your QR codes can be scanned. Once the limit is reached, users will be redirected to a fallback URL or shown a custom message.

Overview

Visit limits are perfect for:

• Limited Time Offers - Create QR codes that expire after a certain number of scans
• Event Access - Limit access to event-specific content
• Beta Testing - Control access to new features or content
• Resource Management - Prevent overuse of limited resources
• Marketing Campaigns - Create urgency with limited availability

Implementation

Basic Visit Limits

Add visit limits to any QR code by including the access_limit object in the settings inside the input property:

{
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "input": {
    "url": "https://example.com/special-offer",
    "settings": {
      "access_limit": {
        "max_visits": 100,
        "fallback_url": "https://example.com/offer-expired"
      }
    }
  },
  "title": "Limited Offer QR"
}

Request Parameters

User Experience

When a user scans a QR code with visit limits:

1. Scan Detection - The QR code scanner detects the content
2. Limit Check - System checks if the visit limit has been reached
3. Content Access - If under limit, user accesses the content
4. Limit Reached - If limit reached, user is redirected to fallback URL

HTTP Response Codes

Visit Limit Responses

Example Response When Limit Reached

{
  "error": "Visit limit exceeded",
  "message": "This QR code has reached its maximum number of visits.",
  "fallback_url": "https://example.com/offer-expired"
}

Examples

Limited Time Offer

{
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "input": {
    "url": "https://example.com/50-percent-off",
    "settings": {
      "access_limit": {
        "max_visits": 50,
        "fallback_url": "https://example.com/offer-expired"
      }
    }
  },
  "title": "50% Off Limited Offer"
}

Event Registration

{
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "input": {
    "url": "https://example.com/event-registration",
    "settings": {
      "access_limit": {
        "max_visits": 200,
        "fallback_url": "https://example.com/event-full"
      }
    }
  },
  "title": "Event Registration"
}

Beta Access

{
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "input": {
    "url": "https://example.com/beta-feature",
    "settings": {
      "access_limit": {
        "max_visits": 25,
        "fallback_url": "https://example.com/beta-closed"
      }
    }
  },
  "title": "Beta Feature Access"
}

Behavior for Existing QR Codes

When you add visit limits to existing QR codes:

• Previous Visits Counted - All previous visits are included in the limit
• Immediate Effect - Limits take effect immediately after creation
• No Retroactive Changes - You cannot change limits after creation
• Monitoring Available - Track current visit count through analytics

Best Practices

Setting Appropriate Limits

1. Consider Your Use Case - Set limits based on your specific needs
2. Test with Small Numbers - Start with small limits for testing
3. Monitor Performance - Track how quickly limits are reached
4. Plan for Success - Be prepared to increase limits if needed

Fallback URL Strategy

1. Meaningful Content - Provide useful information on the fallback page
2. Alternative Options - Offer alternative ways to access content
3. Clear Messaging - Explain why the limit was reached
4. Contact Information - Provide ways to get help or request access

User Experience

1. Clear Expectations - Let users know about visit limits upfront
2. Progress Indicators - Show remaining visits if appropriate
3. Alternative Access - Provide backup methods for important content
4. Error Handling - Handle limit reached scenarios gracefully

Monitoring and Analytics

Visit Tracking

• Real-time Counters - Monitor visit counts in real-time
• Geographic Data - Track where visits are coming from
• Device Analytics - Understand which devices are scanning
• Time-based Analysis - See when visits are most frequent

Limit Management

• Current Status - Check how many visits remain
• Historical Data - Review past visit patterns
• Performance Metrics - Analyze QR code effectiveness
• Optimization Opportunities - Identify areas for improvement

Troubleshooting

Common Issues

1. Limit Reached Unexpectedly

• Check if previous visits were counted
• Verify the limit was set correctly
• Review analytics for unexpected traffic

1. Fallback URL Not Working

• Ensure the fallback URL is accessible
• Test the URL manually
• Check for redirect loops or errors

1. Analytics Discrepancies

• Allow time for analytics to update
• Check for caching issues
• Verify API responses

Error Handling

1. Graceful Degradation - Handle limit reached scenarios in your application
2. User Feedback - Provide clear messages when limits are reached
3. Alternative Access - Offer backup methods for important content
4. Support Contact - Provide ways for users to get help

Advanced Usage

Combining with Other Features

Visit limits can be combined with other advanced features:

{
  "typology": "/api/qr-typologies/0598466c-025c-11ef-83ba-06c4e69992ab",
  "input": {
    "url": "https://example.com/premium-content",
    "settings": {
      "password_protected": true,
      "password": "premium-access",
      "access_limit": {
        "max_visits": 100,
        "fallback_url": "https://example.com/premium-expired"
      }
    }
  },
  "title": "Premium Content with Limits"
}

Dynamic Limits

Consider implementing dynamic limits based on:

• Time of Day - Different limits for peak vs. off-peak hours
• User Type - Different limits for different user segments
• Content Type - Varying limits based on content sensitivity
• Geographic Location - Regional limits for localized content

Next Steps

• Learn about Password Protection
• Explore Analytics
• Create your first limited QR code
• Set up Project Organization