| 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 parametersplanType (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 parameterpaymentIntentId (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 parametersidempotencyKey (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 parametersplanType (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 parametersplanType (string, required) "autopay" (Growth) or "autopay_299" (Starter).billingInterval (string) "monthly" (default) or "annual".
|