# Plans & Tokens

Source: https://env.7xmtools.com/api-docs/plans-tokens.html

Keepa API plans are rate-limited with a token bucket: every plan generates a fixed number of tokens per minute, and each API request consumes tokens. This page explains the token model, subscription billing, and the token cost of each request type.

Token bucket rate limiting

## How Plans Work

Keepa's [API plans](https://env.7xmtools.com/api/pricing) are all billed monthly in advance and continue from one billing period to the next until canceled. A subscription can be canceled at any time. Access to the API is limited via the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket). This allows request bursts as well as a constant rate of requests throughout the plan's duration — it is not possible to use up the whole contingent by accident.

The plans differentiate by the **number of tokens that are generated per minute**. Unused tokens **expire after 60 minutes**.

## The Token Bucket Model

Your plan continuously adds tokens to a bucket. Because each token is valid for 60 minutes, the bucket can hold at most *rate × 60* tokens at any time. Every API request removes tokens from the bucket; tokens that sit unused for 60 minutes expire.

*The token bucket: constant token generation, limited bucket capacity, expiry of unused tokens.*

### Example: the 60 tokens per minute plan

The *60 tokens per minute* plan generates 60 tokens every minute, and each token is valid for 60 minutes — so the token bucket capacity is 3,600 tokens. The tokens are generated 24/7, whether you are making requests or not. Each requested product consumes one token. If you were to use every generated token throughout a 31-day month of the plan, you could request a total of **2,678,400 products**.

| Property | 60 tokens per minute plan |
| --- | --- |
| Token generation | 60 tokens every minute, 24/7 (whether you make requests or not) |
| Token lifetime | 60 minutes (unused tokens expire) |
| Bucket capacity | 60 × 60 = **3,600 tokens** (also the maximum burst you can spend at once) |
| Cost per requested product | 1 token |
| Maximum products in a 31-day month | 60 × 60 × 24 × 31 = **2,678,400** |

> **Note:** Some API requests require different amounts of tokens — the costs are listed in the [Token Costs by Request Type](https://env.7xmtools.com/api-docs/plans-tokens.html#token-costs) section below and on the individual endpoint pages.

## Managing Your Subscription

### Cancel

A subscription can be canceled at any time through your [dashboard](https://env.7xmtools.com/api). Once canceled, it is scheduled to be terminated at the end of its period.

> **Note:** A canceled subscription keeps running until the end of the period you already paid for. Until then you can **resume** it from your dashboard, and billing continues as before. Once the period has ended and the subscription has expired, it can no longer be reactivated — you then have to subscribe to a new plan.

### Upgrade / Downgrade

Subscriptions can be changed by switching the plan. You can **upgrade** your subscription level at any time. A **downgrade** is possible as well, but only once every 28 days. The new plan will be active immediately. Your billing cycle will remain the same, and you will be immediately charged a prorated amount in case of an upgrade, or receive a credit to your Keepa account in case of a downgrade (no refund possible).

**Example:** You are billed on the 1st of each month and upgrade your subscription exactly half-way through the plan's billing cycle (i.e., on the 15th of March). In that case, you have already been charged the full monthly cost of 10 EUR of your existing plan and used half of the current billing cycle. When you switch to the new plan, with a higher cost of 25 EUR, the unused portion of the previous plan results in a credit of 5 EUR. The cost of the new plan for the rest of the billing cycle (i.e., the rest of March) will be 12.50 EUR. Therefore, the total prorated cost of switching from the cheaper plan to the more expensive plan is **7.50 EUR**. This amount will be charged immediately.

| Proration item (upgrade on 15 March) | Amount |
| --- | --- |
| Credit for the unused half of the old plan (10 EUR/month) | −5.00 EUR |
| New plan (25 EUR/month) for the remaining half of March | +12.50 EUR |
| **Charged immediately** | **7.50 EUR** |

### Multiple subscriptions

Instead of upgrading an existing subscription, you can subscribe to an additional plan. All subscriptions will be active simultaneously, and each subscription will have its own billing cycle and billing information, but they share the same payment method and API key.

## Payment

Keepa accepts payments via credit card through the payment provider [Stripe.com](https://stripe.com/). Keepa never has access to your full credit card information. If you require other forms of payment, please contact [info@keepa.com](mailto:info@keepa.com). Keepa does not offer discounts.

## Dashboard

Once you have purchased a plan, you can use the [API page](https://env.7xmtools.com/api) to:

- view the status of your API access,
- manage your subscription,
- change your payment and billing details,
- generate a new API access key,
- retrieve receipts (invoices).

## Token Costs by Request Type

The available requests and their token costs:

| Request | Token cost |
| --- | --- |
| [Product Request](https://env.7xmtools.com/api-docs/product.html) | 1 token per product (more with optional parameters) |
| [Product Search](https://env.7xmtools.com/api-docs/product-search.html) | 10 tokens per search (up to 20 results) |
| [Product Finder](https://env.7xmtools.com/api-docs/product-finder.html) | 10 + 1 per 100 ASINs |
| [Browsing Deals](https://env.7xmtools.com/api-docs/deals.html) | 5 tokens per request (up to 150 deals) |
| [Best Sellers](https://env.7xmtools.com/api-docs/best-sellers.html) | 50 tokens per request |
| [Category Lookup](https://env.7xmtools.com/api-docs/category-lookup.html) | 1 token per request (up to 10 categories) |
| [Category Search](https://env.7xmtools.com/api-docs/category-search.html) | 1 token per search |
| [Seller Information](https://env.7xmtools.com/api-docs/seller.html) | 1 token per seller (+9 for storefront) |
| [Seller Finder](https://env.7xmtools.com/api-docs/seller-finder.html) | 10 + 1 per 100 seller IDs |
| [Most Rated Sellers](https://env.7xmtools.com/api-docs/most-rated-sellers.html) | 50 tokens per request |
| [Lightning Deals](https://env.7xmtools.com/api-docs/lightning-deals.html) | 1 token per ASIN · 500 tokens for the full list |
| [Graph Image API](https://env.7xmtools.com/api-docs/graph-image.html) | 1 token per image |
| [Tracking API](https://env.7xmtools.com/api-docs/tracking.html) | varies per tracked product |

> **Tip:** Each endpoint page documents its token cost in detail, including options that change the cost (for example, requesting marketplace offers with a product).

## Examples

### Will my workload fit a plan?

Since tokens are generated 24/7 at a fixed rate, the monthly token budget of a plan is simply `rate × 60 × 24 × days`. Combine that with the token costs above to check whether a planned workload fits a plan (illustrative calculation):

```python
# Will a "60 tokens per minute" plan cover my monthly workload?
RATE = 60                                # tokens generated per minute (plan tier)
tokens_per_month = RATE * 60 * 24 * 31   # 2,678,400 tokens in a 31-day month

# Planned monthly workload (costs from the token cost table):
products     = 1_500_000 * 1    # product requests: 1 token per ASIN
offer_pages  =   120_000 * 6    # offer pages: 6 tokens per found offer page
deal_batches =     2_000 * 5    # browsing deals: 5 tokens per 150 deals
best_sellers =        30 * 50   # best sellers lists: 50 tokens per list

needed = products + offer_pages + deal_batches + best_sellers

print(f"Plan budget: {tokens_per_month:,} tokens/month")   # 2,678,400
print(f"Workload:    {needed:,} tokens/month")             # 2,231,500
print("Fits!" if needed <= tokens_per_month else "Upgrade needed.")
```

Remember the burst limit: because unused tokens expire after 60 minutes, the bucket never holds more than `rate × 60` tokens (3,600 on the 60/min plan), so a burst larger than that has to be spread out over time while tokens refill.

### Checking your token balance

Every API response includes the current status of your token bucket, so you can monitor your balance with any request — for example a [product request](https://env.7xmtools.com/api-docs/product.html), which consumes 1 token per ASIN. See [Making Requests](https://env.7xmtools.com/api-docs/request-basics.html) for the full response envelope.

```
GET https://api.keepa.com/product?key=<yourAccessKey>&domain=<domainId>&asin=<ASIN>
```

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getProductRequest(AmazonLocale.US, null, null, "B0F3GWXLTS");
api.sendRequest(r)
    .done(result -> {
        if (result.status == ResponseStatus.OK) {
            System.out.println(result.products[0].title);
        }
    })
    .fail(failure -> System.out.println(failure));
```

**PHP**

```php
<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

$api = new KeepaAPI("YOUR_API_KEY");
$response = $api->sendRequestWithRetry(Request::getProductRequest(AmazonLocale::US, null, null, null, 1, true, ['B0F3GWXLTS']));
if ($response->status == ResponseStatus::OK) {
    echo $response->products[0]->title;
}
```

**Python**

```python
import requests

params = {"key": "YOUR_API_KEY", "domain": 1, "asin": "B0F3GWXLTS"}
r = requests.get("https://api.keepa.com/product", params=params)
data = r.json()
print(f"Tokens left: {data['tokensLeft']} (refill rate: {data['refillRate']}/min)")
```

**Node.js**

```javascript
const res = await fetch("https://api.keepa.com/product?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS");
const data = await res.json();
console.log(`Tokens left: ${data.tokensLeft} (refill rate: ${data.refillRate}/min)`);
```

**cURL**

```bash
curl -s "https://api.keepa.com/product?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS"
```

### Example response

```json
{
  "processingTimeInMs": 16,
  "tokensLeft": 3487,
  "refillIn": 21000,
  "refillRate": 60,
  "tokenFlowReduction": 0.0,
  "tokensConsumed": 1,
  "products": [
    {
      "asin": "B0F3GWXLTS",
      "domainId": 1,
      "title": "Example Product Title"
    }
  ]
}
```

Response shortened for readability; illustrative values. `tokensLeft` is your current bucket balance, and `refillRate` is your plan's tokens-per-minute rate — the fields are documented on the [Making Requests](https://env.7xmtools.com/api-docs/request-basics.html) page.