Python SDK Reference¶

Learn how to use Voucher API with Python.

Installation¶

pip install voucher-api

Configuration¶

from voucher_api import VoucherClient

client = VoucherClient(
    api_key='your_api_key',
    environment='production'  # or 'sandbox'
)

Core Features¶

Create Voucher¶

voucher = client.vouchers.create(
    code='SUMMER2024',
    type='percentage',
    value=20,
    conditions={
        'min_order_value': 50.00,
        'max_uses': 1000
    }
)

Validate Voucher¶

validation = client.vouchers.validate(
    code='SUMMER2024',
    order={
        'value': 100.00,
        'currency': 'USD'
    }
)

Apply Voucher¶

result = client.vouchers.apply(
    code='SUMMER2024',
    order_id='order_123'
)

Advanced Features¶

Batch Operations¶

results = client.vouchers.batch_create([
    {
        'code': 'SUMMER2024',
        'type': 'percentage',
        'value': 20
    },
    {
        'code': 'WINTER2024',
        'type': 'fixed',
        'value': 10.00
    }
])

Analytics¶

analytics = client.analytics.get_performance(
    start_date='2024-01-01',
    end_date='2024-03-20'
)

Error Handling¶

try:
    voucher = client.vouchers.create(
        code='SUMMER2024',
        type='percentage',
        value=20
    )
except VoucherError as error:
    if error.code == 'INVALID_REQUEST':
        # Handle validation error
        pass
    elif error.code == 'RATE_LIMIT_EXCEEDED':
        # Handle rate limit error
        pass

Webhooks¶

from voucher_api import WebhookHandler
from flask import Flask, request

app = Flask(__name__)
handler = WebhookHandler('your_webhook_secret')

@app.route('/webhooks/voucher', methods=['POST'])
def handle_webhook():
    event = handler.verify(
        request.data,
        request.headers['X-Voucher-Signature']
    )

    if event.type == 'voucher.created':
        # Handle created event
        pass
    elif event.type == 'voucher.validated':
        # Handle validated event
        pass

    return 'Webhook received', 200

Best Practices¶

Error Handling
Use try-except blocks
Handle specific error codes
Implement retry logic
Performance
Use batch operations
Cache responses
Monitor rate limits
Security
Store API keys securely
Verify webhook signatures
Use HTTPS endpoints

Next Steps¶

Additional Resources¶

Voucher Validation¶

# Validate a voucher
validation = client.vouchers.validate(
    code='SUMMER2024',
    order_value=100.00,
    customer_id='customer_123',
    items=[
        {
            'id': 'item_1',
            'price': 50.00,
            'quantity': 2
        }
    ]
)

# Check validation result
if validation.is_valid:
    print('Discount amount:', validation.discount_amount)
else:
    print('Validation failed:', validation.error)

Voucher Application¶

# Apply a voucher
application = client.vouchers.apply(
    code='SUMMER2024',
    order_id='order_456',
    customer_id='customer_123',
    items=[
        {
            'id': 'item_1',
            'price': 50.00,
            'quantity': 2
        }
    ]
)

# Remove applied voucher
client.vouchers.remove(
    code='SUMMER2024',
    order_id='order_456'
)

Analytics¶

# Get voucher analytics
analytics = client.analytics.get_voucher_stats(
    voucher_id='SUMMER2024',
    start_date='2024-01-01',
    end_date='2024-12-31'
)

# Get redemption history