Plans & Tokens

How Plans Work#

Keepa's API plans 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. 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.

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.

Managing Your Subscription#

Cancel#

A subscription can be canceled at any time through your dashboard. Once canceled, it is scheduled to be terminated at the end of its period.

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.

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. Keepa never has access to your full credit card information. If you require other forms of payment, please contact info@keepa.com. Keepa does not offer discounts.

Dashboard#

Once you have purchased a plan, you can use the API page 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:

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):

# 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, which consumes 1 token per ASIN. See Making Requests for the full response envelope.

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
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;
}

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)")

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 -s "https://api.keepa.com/product?key=YOUR_API_KEY&domain=1&asin=B0F3GWXLTS"

Example response#

{
  "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 page.