The Vouchers API allows you to create, manage, and redeem discount codes and promotional vouchers for Pocketbook services.

Overview

Vouchers provide a flexible way to offer discounts, promotions, or free credits to users. They can be:

• Single-use or multi-use
• Time-limited or permanent
• Percentage-based or fixed-amount discounts
• Restricted to specific products or services

Endpoints

List All Vouchers

Get a paginated list of all vouchers.

GET /api/v1/vouchers

Query Parameters:

• page (integer, optional): Page number for pagination (default: 1)
• limit (integer, optional): Items per page (default: 20, max: 100)
• status (string, optional): Filter by status (active, expired, used)

Example Request:

curl -X GET "https://api.pocketbook.studio/api/v1/vouchers?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response:

{
  "vouchers": [
    {
      "id": "vouch_abc123",
      "code": "WELCOME2024",
      "type": "percentage",
      "value": 20,
      "status": "active",
      "uses_remaining": 100,
      "max_uses": 100,
      "expires_at": "2024-12-31T23:59:59Z",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  }
}

Create Voucher

Create a new voucher code.

POST /api/v1/vouchers

Request Body:

{
  "code": "WELCOME2024",
  "type": "percentage",
  "value": 20,
  "max_uses": 100,
  "expires_at": "2024-12-31T23:59:59Z",
  "description": "Welcome discount for new users"
}

Parameters:

• code (string, required): Unique voucher code (alphanumeric, 4-32 characters)
• type (string, required): percentage or fixed_amount
• value (number, required): Discount value (1-100 for percentage, cents for fixed_amount)
• max_uses (integer, optional): Maximum number of redemptions (null for unlimited)
• expires_at (string, optional): ISO 8601 expiration timestamp
• description (string, optional): Internal description

Example Request:

curl -X POST "https://api.pocketbook.studio/api/v1/vouchers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE50",
    "type": "percentage",
    "value": 50,
    "max_uses": 1000,
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Example Response:

{
  "id": "vouch_xyz789",
  "code": "SAVE50",
  "type": "percentage",
  "value": 50,
  "status": "active",
  "uses_remaining": 1000,
  "max_uses": 1000,
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Voucher Details

Retrieve details for a specific voucher.

GET /api/v1/vouchers/{voucher_id}

Example Request:

curl -X GET "https://api.pocketbook.studio/api/v1/vouchers/vouch_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Redeem Voucher

Apply a voucher code to an order or subscription.

POST /api/v1/vouchers/redeem

Request Body:

{
  "code": "WELCOME2024",
  "order_id": "ord_123456"
}

Example Request:

curl -X POST "https://api.pocketbook.studio/api/v1/vouchers/redeem" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WELCOME2024",
    "order_id": "ord_123456"
  }'

Example Response:

{
  "success": true,
  "voucher": {
    "id": "vouch_abc123",
    "code": "WELCOME2024",
    "type": "percentage",
    "value": 20
  },
  "discount_applied": 1999,
  "original_amount": 9999,
  "final_amount": 8000
}

Update Voucher

Update an existing voucher.

PATCH /api/v1/vouchers/{voucher_id}

Request Body:

{
  "status": "inactive",
  "max_uses": 200
}

Example Request:

curl -X PATCH "https://api.pocketbook.studio/api/v1/vouchers/vouch_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive"
  }'

Delete Voucher

Permanently delete a voucher.

DELETE /api/v1/vouchers/{voucher_id}

Example Request:

curl -X DELETE "https://api.pocketbook.studio/api/v1/vouchers/vouch_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Voucher Types

Percentage Discount

Applies a percentage discount to the total amount.

{
  "type": "percentage",
  "value": 25
}

This applies a 25% discount to the order total.

Fixed Amount Discount

Applies a fixed discount in cents.

{
  "type": "fixed_amount",
  "value": 1000
}

This applies a $10.00 discount to the order total.

Voucher Status

• active: Voucher can be redeemed
• expired: Voucher expiration date has passed
• used: Voucher has reached its maximum uses
• inactive: Voucher has been manually deactivated

Best Practices

1. Unique Codes: Use unique, non-guessable codes for security
2. Expiration Dates: Always set expiration dates for promotional vouchers
3. Usage Limits: Set appropriate max_uses to prevent abuse
4. Monitoring: Regularly audit voucher usage and redemption patterns
5. Validation: Always validate voucher codes before applying discounts

Error Responses

See the Error Handling documentation for common error codes and responses.

Common voucher-specific errors:

• voucher_not_found: Voucher code does not exist
• voucher_expired: Voucher has expired
• voucher_max_uses_reached: Voucher has been used maximum times
• voucher_inactive: Voucher has been deactivated
• voucher_code_exists: Code already exists when creating voucher

Rate Limits

Voucher API endpoints are subject to the following rate limits:

• List/Read operations: 100 requests per minute
• Create/Update operations: 50 requests per minute
• Redeem operations: 200 requests per minute

See Rate Limiting for more information.