Skip to main content

DocsREST API and MCP server

Billing & Plans API

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Account: Billing & Plans

Get Current Plan

The account's plan, field tier and record credits for the current billing period. planType is "autopay_299" (Starter), "autopay" (Growth), "pay_per_count" (pay-as-you-go orders only) or "" (never bought); status is inactive, active, canceling, past_due, unpaid or canceled. While the last subscription payment has failed, paymentIssue holds the code PAYMENT_PAST_DUE and a message. tier (1–3) sets which export columns an order may include.

GEThttps://us-farmvision-new-api.onrender.com/api/v1/billing/planTry it

In this section

Authentication

Get API key

Bearer token

Send your GTM Scoop API key (llmcp_…) or a signed-in session token as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Parameters

This endpoint takes no parameters or request body.

Mounted at

/api/v1/billing

Your plan, record credits and payments. GTM Scoop sells two subscriptions, Starter ($299/mo or $2,868/yr, 2,500 records a month) and Growth ($899/mo or $8,628/yr, 10,000 records a month), plus one-time pay-as-you-go orders at $0.09 a record; payments are confirmed in the browser with Stripe Elements, using the client secret these routes return. An annual plan bills once a year and its credits refill every month; creditsRefillOn gives the next date.

Try it in the playground

Signed out: 10 free tries a day with names hidden. Log in for live data.

Open playground

Related endpoints

All 8 endpoints in this section

Bearer token: an llmcp_ API key or a signed-in session; plan upgrades take a signed-in session only.

MethodPathWhat it does
GET/api/v1/billing/plan

Get Current Plan

The account's plan, field tier and record credits for the current billing period. planType is "autopay_299" (Starter), "autopay" (Growth), "pay_per_count" (pay-as-you-go orders only) or "" (never bought); status is inactive, active, canceling, past_due, unpaid or canceled. While the last subscription payment has failed, paymentIssue holds the code PAYMENT_PAST_DUE and a message. tier (1–3) sets which export columns an order may include.

Try Get Current Plan in the Playground
GET/api/v1/billing/credit-usage

Get Credit Usage

What the record credits went on: the current plan, orders paid with plan credits (card-paid orders are left out), completed AI analysis jobs and completed enrichment runs, newest first. Capped at the latest 200 orders, 50 analysis jobs and 200 runs.

Try Get Credit Usage in the Playground
POST/api/v1/billing/checkout-session

Start a Payment

Starts a payment and returns a Stripe PaymentIntent client secret to confirm with Stripe Elements (not a hosted Checkout URL); call /confirm-payment once Stripe reports success. autopay_299 (Starter) or autopay (Growth) starts a subscription; pay_per_count is a one-time order priced at $0.09 per record of the server's own recount ($1.00 minimum, 10,000 records maximum per order; larger orders go through an agent). 400 if no records match, 402 when a plan sign-up carries an order and this period's credits are used up, 503 if payments are temporarily unavailable.

17 parameters
  • planType (string, required) "autopay_299" (Starter subscription), "autopay" (Growth subscription) or "pay_per_count" (one-time order).
  • billingInterval (string) Subscriptions only: "monthly" (default) or "annual". Annual is charged once a year ($2,868 Starter, $8,628 Growth).
  • snapshot (object) The order. Required for pay_per_count; optional for a plan sign-up, whose order is then cut to the new plan's credits and taken from them. The server recounts it; any counts you send are ignored.
  • snapshot.datasets (array, required) One or more of "farm", "business", "property".
  • snapshot.farmFilters (object) Farm criteria, in the same shape Farm Data Search /count takes (e.g. { "states": ["Iowa"], "crops": ["Corn"] }). Needed when datasets includes farm.
  • snapshot.businessActive (array) Business criteria as { id, filterId, values, exclude } objects, as Business Data Search uses. Needed when datasets includes business.
  • snapshot.businessGeoPlaceScope (object) Optional { "statesNarrowed": [...] } geography scope from Business Data Search.
  • snapshot.propertyActive (array) Property criteria as { id, filterId, values, exclude } objects. Needed when datasets includes property.
  • snapshot.propertyGeoPlaceScope (object) Optional { "statesNarrowed": [...] } geography scope for Property.
  • snapshot.requestedCounts (object) Records to buy per dataset, e.g. { "farm": 500 }. Each is capped at that dataset's match count; a dataset left out buys every match.
  • snapshot.requestedImportCount (integer) Older single total, filled farm, then business, then property. Ignored when requestedCounts is set.
  • snapshot.farmExportColumns (array) Farm column ids to export. Omitted: the Tier 1 defaults. Columns above the order's tier are dropped (pay-as-you-go: Tier 1; Starter: 1–2; Growth: 1–3).
  • snapshot.businessExportColumns (array) Business column ids to export, same rules as farmExportColumns.
  • snapshot.propertyExportColumns (array) Property column ids to export, same rules as farmExportColumns.
  • snapshot.listName (string) A name for the list, up to 80 characters. Defaults to List_<timestamp>.
  • snapshot.orderNumber (string) Your own order reference, used in export file names. Defaults to Order_Number_<timestamp>.
  • criteriaCount (number) Accepted for compatibility but not used: the price comes from the server's recount of snapshot.
POST/api/v1/billing/confirm-payment

Confirm Payment

Call after Stripe confirms the payment: activates the subscription or records the pay-as-you-go order, and returns the plan plus the id of the purchase it unlocked (null for a plan sign-up without an order). Idempotent: a payment already applied is never applied twice. 400 if the payment has not succeeded, 403 if it belongs to another account, 409 if it was not started with /checkout-session.

1 parameter
  • paymentIntentId (string, required) The paymentIntentId (pi_…) returned by /checkout-session.
POST/api/v1/billing/claim-autopay

Buy Records with Plan Credits

For Starter and Growth subscribers: takes an order out of this period's record credits instead of charging a card. The server recounts the snapshot, cuts an order bigger than the credits left down to fit, and reports how many records were requested and granted. Send an idempotency key to make retries safe: repeating a key returns the first order with replayed: true and spends nothing, and without one every call is a new order. 403 without an active (or canceling) subscription, 400 if nothing matches or the key is malformed, 402 once the credits are used up, 409 CLAIM_IN_PROGRESS while another request with the same key is still placing the order (repeat it to get the order).

16 parameters
  • idempotencyKey (string) A unique value for this order, such as a UUID: 16 to 128 letters, digits, hyphens or underscores. Reuse it only to retry the same order. Can be sent as an Idempotency-Key header instead.
  • snapshot (object, required) The order: which datasets, the search criteria, and how many records. The server recounts it; any counts you send are ignored.
  • snapshot.datasets (array, required) One or more of "farm", "business", "property".
  • snapshot.farmFilters (object) Farm criteria, in the same shape Farm Data Search /count takes (e.g. { "states": ["Iowa"], "crops": ["Corn"] }). Needed when datasets includes farm.
  • snapshot.businessActive (array) Business criteria as { id, filterId, values, exclude } objects, as Business Data Search uses. Needed when datasets includes business.
  • snapshot.businessGeoPlaceScope (object) Optional { "statesNarrowed": [...] } geography scope from Business Data Search.
  • snapshot.propertyActive (array) Property criteria as { id, filterId, values, exclude } objects. Needed when datasets includes property.
  • snapshot.propertyGeoPlaceScope (object) Optional { "statesNarrowed": [...] } geography scope for Property.
  • snapshot.requestedCounts (object) Records to buy per dataset, e.g. { "farm": 500 }. Each is capped at that dataset's match count; a dataset left out buys every match.
  • snapshot.requestedImportCount (integer) Older single total, filled farm, then business, then property. Ignored when requestedCounts is set.
  • snapshot.farmExportColumns (array) Farm column ids to export. Omitted: the Tier 1 defaults. Columns above the order's tier are dropped (pay-as-you-go: Tier 1; Starter: 1–2; Growth: 1–3).
  • snapshot.businessExportColumns (array) Business column ids to export, same rules as farmExportColumns.
  • snapshot.propertyExportColumns (array) Property column ids to export, same rules as farmExportColumns.
  • snapshot.listName (string) A name for the list, up to 80 characters. Defaults to List_<timestamp>.
  • snapshot.orderNumber (string) Your own order reference, used in export file names. Defaults to Order_Number_<timestamp>.
  • criteriaCount (number) Accepted for compatibility but not used: credits are taken for the server's recount.
POST/api/v1/billing/cancel-autopay

Cancel Subscription

Cancels the Starter or Growth subscription at the end of the current billing period. The plan's status becomes canceling, and it and its credits keep working until then. 400 if the account has no subscription.

GET/api/v1/billing/change-plan/preview

Preview Plan Upgrade

Quotes an upgrade before you make it: Starter to Growth, monthly to annual, or both. The new billing period starts today, so amountDueCents is the new plan's price less the unused part of the current one. Refusals are 409 with a code: NO_ACTIVE_PLAN, SAME_PLAN, DOWNGRADE_NOT_SELF_SERVE (moving down is arranged by support for the renewal date) or NOT_SELF_SERVE.

2 parameters
  • planType (string, required) "autopay" (Growth) or "autopay_299" (Starter).
  • billingInterval (string) "monthly" (default) or "annual".
Try Preview Plan Upgrade in the Playground
POST/api/v1/billing/change-plan

Upgrade Plan

Makes the upgrade quoted by /change-plan/preview and charges the saved card at once; the charge is worked out at that moment, so it can differ from the preview by a few cents. The new period starts immediately and any pending cancellation is undone; a declined card changes nothing. On the same billing cycle, what you already used this period still counts against the new allowance (usedCarried and remainingAfterUpgrade in the preview) and the next renewal gives the full allowance; moving from monthly to annual starts fresh. Same 409 codes as the preview, and 503 if payments are temporarily unavailable.

2 parameters
  • planType (string, required) "autopay" (Growth) or "autopay_299" (Starter).
  • billingInterval (string) "monthly" (default) or "annual".

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy