# Bitrefill Documentation

## Guides
- [Fund the Account Balance](https://docs.bitrefill.com/docs/account-deposits.md): Adding funds to your account via the API.
- [Buy Batches of Bitrefill Gift Cards](https://docs.bitrefill.com/docs/brgc-batches.md): Create batches of Bitrefill Gift Cards for B2B partners.
- [Track Affiliate Earnings](https://docs.bitrefill.com/docs/commissions.md): Track and manage your affiliate earnings via the API.
- [Business API](https://docs.bitrefill.com/docs/Common Use Cases.md): Full B2B API access for platforms, resellers, and enterprise integrations.
- [Resell Bitrefill Products](https://docs.bitrefill.com/docs/integration-flow.md): Standard integration pattern for B2B partners.
- [Track Referrals](https://docs.bitrefill.com/docs/tracking-referrals.md): Understand how referral filtering works in the Affiliate API.
- [Bitrefill API Documentation](https://docs.bitrefill.com/docs/api-overview.md)
- [Core Concepts](https://docs.bitrefill.com/docs/core-concepts.md): Understand products, invoices, orders, and eSIMs before you start building.
- [Quickstart](https://docs.bitrefill.com/docs/quickstart-2.md): Make your first API call and complete a purchase in minutes.
- [Development MCP Server](https://docs.bitrefill.com/docs/development-mcp.md)
- [eCommerce MCP Server](https://docs.bitrefill.com/docs/ecommerce-mcp.md): Connect your AI assistant to Bitrefill and purchase gift cards or eSIMs directly from your conversations.
- [Setup Guides](https://docs.bitrefill.com/docs/setup-guides.md): Step-by-step instructions to connect your AI assistant to Bitrefill MCP.
- [Use with ChatGPT](https://docs.bitrefill.com/docs/use-with-chatgpt.md): Connect ChatGPT to Bitrefill MCP for purchasing gift cards and eSIMs.
- [Use with Claude Desktop](https://docs.bitrefill.com/docs/use-with-claude-chat.md): Connect Claude Desktop to Bitrefill MCP for purchasing gift cards and eSIMs.
- [Use with Claude Code](https://docs.bitrefill.com/docs/use-with-claude-code.md): Connect Claude Code CLI to Bitrefill MCP for purchasing gift cards and eSIMs.
- [Use with Cursor](https://docs.bitrefill.com/docs/use-with-cursor.md): Connect Cursor IDE to Bitrefill MCP for purchasing gift cards and eSIMs.
- [eSIMs](https://docs.bitrefill.com/docs/esims.md): Working with eSIM products via the API.
- [Gift Cards](https://docs.bitrefill.com/docs/gift-cards.md): Working with digital gift card products.
- [Products](https://docs.bitrefill.com/docs/Products.md): Browse and understand the Bitrefill product catalog.
- [Phone Top-ups](https://docs.bitrefill.com/docs/phone-topups.md): Working with mobile refill products.
- [Searching Products](https://docs.bitrefill.com/docs/searching-products.md): Find products by name, country, or category.
- [Crypto Payments](https://docs.bitrefill.com/docs/crypto-payments.md): Paying with Bitcoin, Ethereum, and other cryptocurrencies.
- [Error Codes](https://docs.bitrefill.com/docs/error-codes.md): Complete reference of API error codes.
- [Error Handling](https://docs.bitrefill.com/docs/References.md): Understanding and handling API errors.
- [Rate Limits](https://docs.bitrefill.com/docs/rate-limits.md): Understand API rate limits and how to handle them.
- [Refunds](https://docs.bitrefill.com/docs/refunds.md): Understanding when and how refunds work.
- [Test products](https://docs.bitrefill.com/docs/test-products.md): Complete reference of test products
- [Webhooks](https://docs.bitrefill.com/docs/webhooks.md): Receive real-time notifications when invoices are completed.

## API Reference
- [Create a deposit invoice](https://docs.bitrefill.com/reference/post_accounts-deposit.md): Creates an invoice to add funds to your account balance. Pay the invoice with cryptocurrency to top up your account.  **Notes:** - Cannot use balance as payment method - BTC deposits must use 'bitcoin' payment method  **Supported payment methods:** - BTC: bitcoin, lightning, ethereum, litecoin, dogecoin, dash, solana - ETH: ethereum, eth_base, eth_arbitrum - USDT: usdt_trc20, usdt_erc20, usdt_polygon, usdt_solana, usdt_bsc, usdt_arbitrum - USDC: usdc_erc20, usdc_polygon, usdc_solana, usdc_base, usdc_bsc, usdc_arbitrum  **Rate Limit**: 60 requests per 10 minutes
- [Get a specific BRGC batch by ID](https://docs.bitrefill.com/reference/get_brgc-batches-batchid.md): Retrieves detailed information about a specific batch. You can only access batches you created.  **Rate Limit**: 60 requests per 10 minutes
- [List your BRGC batches](https://docs.bitrefill.com/reference/get_brgc-batches.md): Retrieves all BRGC batches created by your account with pagination.  **Rate Limit**: 20 requests per minute
- [Create a new BRGC batch](https://docs.bitrefill.com/reference/post_brgc-batches.md): Creates a new BRGC batch and charges your account. The process is: 1. Balance is checked to ensure you have sufficient funds 2. Batch generation is queued (async job) 3. Cards are generated and account is charged 4. CSV file with all card codes is sent to your email within 1 hour 5. You can create your batch with EUR or USD cards, and pay with EUR, USD, or BTC  **Limits**: - Maximum 50,000 cards per batch (total across all denominations) - Maximum 10 different denominations per batch - Maximum 10,000 cards per denomination - Card value: 0.01 to 10,000 per card - Batch ID: 1-50 characters, alphanumeric with hyphens/underscores only  **Rate Limit**: 60 requests per 10 minutes
- [Retrieve a single eSIM by id.](https://docs.bitrefill.com/reference/get_esims-id.md)
- [Retrieve user eSIMs](https://docs.bitrefill.com/reference/get_esims.md): List all eSIMs associated with your account. Includes installation status, data bundles, and remaining data. **Rate Limit**: 20 requests per minute  **Key Response Fields**: - `id` - The ICCID (eSIM identifier) - use for top-ups - `installed` - Whether the eSIM is installed on a device - `package_history` - All data bundles with status and remaining data
- [Retrieve a single eSIM invoice by id.](https://docs.bitrefill.com/reference/get_esims-invoice-id.md)
- [Retrieve a single invoice by id.](https://docs.bitrefill.com/reference/get_invoices-id.md)
- [Retrieve user invoices.](https://docs.bitrefill.com/reference/get_invoices.md)
- [Trigger the payment of an unpaid eSIM invoice. Can only be used for invoices with 'balance' payment method.](https://docs.bitrefill.com/reference/post_esims-invoice-id-pay.md)
- [Create a new eSIM invoice](https://docs.bitrefill.com/reference/post_esims.md): Create an invoice to purchase a new eSIM or top up an existing one. **New Purchase vs Top-Up**: Include `esim_id` to top up an existing eSIM. Omit it for a new purchase. **Rate Limit**: 60 requests per 10 minutes  **Key Parameters**: - `products[].product_id` - eSIM product ID (e.g., `bitrefill-esim-europe`) - `products[].value` - Data bundle (e.g., `3GB, 30 Days`) - `products[].esim_id` - Optional ICCID for top-ups
- [Pay an unpaid invoice](https://docs.bitrefill.com/reference/post_invoices-id-pay.md): Trigger payment from account balance for an unpaid invoice. Only works when the invoice was created with `payment_method: balance`. **Rate Limit**: 60 requests per 10 minutes **Note**: For crypto payments, send funds to the address in the invoice's `payment` object instead.
- [Create a new invoice](https://docs.bitrefill.com/reference/post_invoices.md): Create an invoice to purchase one or more products. Each product becomes a separate order within the invoice. **Max Items**: 20 products per invoice **Payment Methods**: `balance`, `bitcoin`, `lightning`, `ethereum`, and various stablecoins **Rate Limit**: 60 requests per 10 minutes  **Key Parameters**: - `products[]` - Array of products with `product_id`, `value` or `package_id`, and optional `quantity` - `payment_method` - How to pay (`balance` or crypto) - `auto_pay` - If true with balance payment, pays immediately - `webhook_url` - URL for delivery notifications - `refund_address` - Required for crypto payments
- [Retrieve account balance](https://docs.bitrefill.com/reference/get_accounts-balance.md): Check your current account balance. Use this to verify sufficient funds before creating invoices with `payment_method: balance`. **Rate Limit**: 60 requests per 10 minutes
- [Searches for providers for the specified phone number](https://docs.bitrefill.com/reference/get_check-phone-number-1.md)
- [List commissions](https://docs.bitrefill.com/reference/get_commissions.md): List your earned affiliate commissions. **Affiliate accounts only** - returns 403 for non-affiliate accounts. **Supports Date Filtering**: Use `after` and `before` query parameters to filter by date range.
- [Ping server](https://docs.bitrefill.com/reference/get_ping.md): Test your API connection and authentication. Returns `pong` if successful. **Rate Limit**: 1 request per 3 seconds  Use this endpoint to verify your credentials are working before making other API calls.
- [Retrieve single order by id](https://docs.bitrefill.com/reference/get_orders-id.md): Get order details including delivery status and redemption info (gift card codes, eSIM QR codes). **Rate Limit**: 60 requests per 10 minutes  **Key Response Fields**: - `status` - Order status: `created`, `processing`, `delivered`, `failed`, `refunded` - `redemption_info` - Contains gift card code, link, PIN, and instructions (when delivered) - `product` - Product details including name and value
- [Retrieve user orders.](https://docs.bitrefill.com/reference/get_orders.md)
- [Retrieve a single eSIM product by id.](https://docs.bitrefill.com/reference/get_products-esims-id.md)
- [Retrieve eSIM product list.](https://docs.bitrefill.com/reference/get_products-esims.md)
- [Retrieve a single product by id.](https://docs.bitrefill.com/reference/get_products-id.md)
- [Search products](https://docs.bitrefill.com/reference/get_products-search.md): Search products by keyword. Supports pagination with the same structure as the products list. **Query Parameter**: `q` (required, 1-100 characters) **Rate Limit**: 60 requests per minute **Product Quota**: 1000 product requests per hour (shared with /products)
- [Retrieve product list](https://docs.bitrefill.com/reference/get_products.md): Paginated list of all available products including gift cards, eSIMs, and phone top-ups. **Caching Recommended**: Cache products locally and refresh at least daily. **Rate Limit**: 60 requests per minute **Product Quota**: 1000 product requests per hour (shared with /products/search)