Skip to main content

Credits and billing

A live key spends credits. A test key never does.

CallCredits
A text estimate10
A photo estimate25
A follow-up5

A call holds its credits before the estimator runs and charges them when it answers. A call that fails gives them back. GET /v1/balance returns what is left, lot by lot.

Lots and expiry​

Credits come in lots, and each lot has its own expiry:

  • A pack lasts 12 months from the purchase.
  • The Business plan's credits last until the period they came with ends.
  • Free live credits last until the month ends.

The lot that expires first is spent first. When the balance cannot cover a call, it answers 402 insufficient_credits and charges nothing.

Buying credits​

Buy packs and plans in the dashboard under Billing, or send the customer to a Checkout page from your own code:

curl https://api.wfskills.com/v1/billing/checkout \
  -H "Authorization: Bearer $HOMETOWN_LIVE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"pack": "credits_10000", "success_url": "https://example.com/billing/done", "cancel_url": "https://example.com/billing"}'

The answer has the page in url. The credits arrive when the invoice is paid, a few seconds after the payment, never when the page returns to success_url. This route needs a live key with the billing:manage scope; a test key answers 403 test_key_on_live_route.

pack takes credits_2500, credits_10000, credits_50000, plan_api_business or addon_records. Invoices need the legal name, the address and the country for the tax. Without them the route answers 422 billing_profile_incomplete. Fill them in once in the dashboard.

Invoices and the saved card are in the dashboard under Billing, on pages Stripe hosts.

Monthly cap​

Set a monthly cap in credits in the dashboard. A call that would go past it answers 402 monthly_cap_reached and charges nothing. The answer carries resets_at, the first day of the next month in the account time zone.

Automatic top-up​

Choose a pack and a threshold in the dashboard. When a live call leaves the balance under the threshold, Hometown buys that pack with the saved card. One top-up runs at a time, so a burst of calls is charged once. The credits arrive with the paid invoice, as with any purchase.

Free live​

An account opened in the dashboard gets 1,000 live credits each month. It needs a verified email, a phone number and a saved card first. The same three open the first live key. The credits last until the month ends.

When a payment fails​

A failed payment marks the account past due, and the API keeps working. The third failure in 14 days suspends it: every call answers 403 tenant_suspended. Paying the open invoice in the dashboard opens the account again.

Last updated on