Credits and caching

SocialTap is prepaid: you buy credits, and each successful request spends some of them. One balance covers every endpoint on every platform.

• Failed requests are free: errors cost 0 credits.
• Cache hits are free.
• Credits from packs and top-ups never expire.
• A monthly plan's credits are spent first, and what is left of them ends at each renewal.
• One credit balance for every endpoint and platform.
• Prices exclude tax: sales tax is added at checkout where it applies.
• Outside the US, plans and packs are sold to businesses: checkout asks for your VAT, GST or other business tax ID.

How a request is charged

1. Reserve. Before calling the platform, SocialTap checks that your balance covers the endpoint's minimum price and sets that minimum aside, nothing more. If the balance is below the minimum, the request fails immediately with insufficient_credits.
2. Fetch. Endpoints try their sources cheapest first and stop at the first one that works. The source that produced the result is reported as meta.source (see sources). Right before a source that costs more than what is set aside (a price that grows with the size of the item), SocialTap sets aside more of your balance: the exact price when the size of the item is known in advance, otherwise as much as your balance allows, and it then processes only as much of the item as that pays for. A source your balance can't pay for is skipped.
3. Charge. The price of the result is charged and the rest released. If the result would cost more than your balance covers, the request fails with insufficient_credits instead and costs nothing. A failed request releases everything.

A request that succeeds after you hang up (a timeout, a closed connection) is still charged. Its result is cached: retry with max_age to get it as a free cache hit.

What you paid is in meta.credits_charged and in the x-credits-charged header. x-credits-remaining is your account balance right after this request was charged; other requests of yours still in flight may lower it further, so with requests in parallel treat it as an upper bound. Both headers are on every response to an authenticated request, errors included (with a charge of 0); a unauthorized response has neither.

Reservations

A request starts only if your balance covers the endpoint's minimum, and only that minimum is set aside when it starts. More is set aside just before costlier work, and only what that work needs. Requests running in parallel therefore don't each lock up the most they could cost: your balance has to cover their minimums, plus the actual price of whatever costlier work they reach.

Prices that grow with the size of the item have a ceiling, because items above a size limit are refused; that ceiling is the most one request can cost.

Prices

A price is either flat ("1 credit") or a base plus a per-unit amount, for sources whose cost grows with the size of the item; the unit is part of the price.

Sources

Monthly plans

Subscribe in the dashboard's Billing page. GET /v1/billing/subscription reads your plan: when it renews, what it changes to, and how much of your balance is monthly credits. plan.renewed, plan.changed, plan.payment_failed and plan.ended tell your webhooks. Subscribing, changing and canceling are for a person in the dashboard only, as they authorize charges to the card.

• Each month. Your plan renews on the same day each month and adds its credits. Requests spend monthly credits first, and what is left of them ends at the renewal. Credits from packs and top-ups stay, and never expire.
• If you run out. Buy your plan's top-up or any pack in Billing, or turn on auto top-up with a monthly cap. Your plan keeps renewing as usual.
• Upgrading. A bigger plan starts right away. You pay its full price today, a new month starts today, its credits are added, and the monthly credits you had left stay until your next renewal.
• Downgrading. A smaller plan starts at your next renewal, and nothing is charged today. You can change your mind until then.
• Canceling. Cancel any time in Billing, and you won't be charged again. Your plan and its credits last until the end of the month you paid for. Pack and top-up credits stay.
• Refunds. You can ask for a refund of a credit pack's unused credits within 14 days of buying it: email support@socialtap.dev. A month of a plan that has already started isn't refunded, and canceling stops the next charge.

A renewal that can't be paid adds no credits, and the credits you have keep working. You are emailed, and the card is tried again over the next few days. The plan ends if those tries fail. You can still upgrade meanwhile: the new plan is charged right away, and the unpaid renewal as well, with its credits added when it is.

Packs

Buy a pack in the dashboard, or with POST /v1/billing/checkout: it answers a Stripe Checkout URL to open and pay; the credits are added when the payment completes. Read your balance with GET /v1/account. A plan's subscribers can also buy its top-up, listed above, the same way.

Auto top-up

Auto top-up buys a pack for you when your balance runs low, so live traffic never stops at insufficient_credits. Turn it on in the dashboard's Billing page and choose three things: the pack, the balance to top up at (your low-balance alert's by default) and a monthly cap. The cap is required; by default it is 3 times the pack's price, plus 10% for sales tax, rounded up to the dollar.

Each time a request leaves your balance at or below the threshold, SocialTap charges your saved card for the pack (or your monthly plan's top-up, which follows your plan if you change it), adds sales tax where it applies as at checkout, and emails the receipt. It runs once per crossing (again only after the balance has been above the threshold), one top-up at a time, and never past the cap in a calendar month (UTC), tax included: a top-up that would pass it is skipped and you are emailed.

To keep a stolen card from being charged again and again, auto top-up also charges at most a set amount in any 7 days, tax included, however high your cap is. It starts at $500 and adds 2 times every payment that settled at least 14 days ago; Billing and GET /v1/billing/auto_topup show yours. A top-up that would pass it is skipped and you are emailed, and it runs by itself once there is room: write to support to lift it sooner. Buying a pack yourself is never limited by it.

A charge that fails is never retried. Auto top-up turns itself off, you are emailed why, and Billing shows it: a declined card, or a bank asking you to confirm the payment (buy the pack in Billing, where your bank can ask, then turn auto top-up back on). Fix the card in Billing's payment settings, then turn it on again. A pack you buy saves its card for auto top-up, which never charges it until you turn auto top-up on.

If your bank only asks about a payment, which is not yet a dispute, auto top-up turns off and nothing else changes: you can turn it back on. A dispute of any payment on the account, not only a top-up's, turns auto top-up off and ends a monthly plan, so that card isn't charged again. Auto top-up then comes back only when you turn it on, with a different card or once the dispute is closed in our favor. It never comes back on its own.

GET /v1/billing/auto_topup reads it, and auto_topup.succeeded, auto_topup.failed and auto_topup.skipped tell your webhooks. Turning it on or changing it is for a person in the dashboard only, as it authorizes charges to the card.

Purchases and receipts

Billing lists every purchase, newest first: packs you bought, auto top-ups and monthly plan payments, with what each cost, its credits and whether it was refunded or disputed. Each has its receipt (a plan payment, its invoice with a PDF), opened from Stripe when you ask for it. GET /v1/billing/purchases and GET /v1/billing/purchases/{id}/receipt read the same with an API key, for your bookkeeping. Billing's payment settings change the billing address, name and tax ID your receipts show.

Caching

Every endpoint accepts these options:

With max_age=N, SocialTap may answer from a stored response that is at most N seconds old. Cached responses have meta.is_cached set to true and are free. A response is stored for at most 7 days, so a larger N counts as that.