Billing and usage
Your plan, this period's usage against it, and payments. Only real leads count; junk and repeat messages are free. See Plans and limits for how limits work.
The Usage object
Properties
- Name
object- Type
- 'usage'
- Description
The object type.
- Name
plan- Type
- 'free' | 'starter' | 'pro' | 'agency' | 'scale' | 'internal'
- Description
- Name
periodStart- Type
- string
- Description
- Name
periodEnd- Type
- string
- Description
- Name
leads- Type
- object
- Description
- Name
nonLeads- Type
- object
- Description
Messages that were not leads (free up to 10× the lead allowance)
- Name
testLeads- Type
- object
- Description
Leads created with test keys
- Name
evaluations- Type
- object
- Description
- Name
generations- Type
- object
- Description
Profiles / criteria generated from a description
- Name
byWorkspace- Type
- array of object
- Description
GET/v1/billing
Plan, subscription and this period's usage
Request
GET
/v1/billingcurl https://core.leadveyor.com/v1/billing \
-H "Authorization: Bearer {api_key}"
Response 200
{
"object": "billing",
"plan": "free",
"status": "active",
"cancelAtPeriodEnd": false,
"pendingPlan": "free",
"spendLimitUsd": null,
"hasSubscription": false,
"paymentsEnabled": false,
"usage": {
"object": "usage",
"plan": "free",
"periodStart": "2026-11-02T09:30:00.000Z",
"periodEnd": "2026-11-02T09:30:00.000Z",
"leads": {
"used": 0,
"included": null,
"percent": null,
"overage": 0,
"overageUsd": 0,
"spendLimitUsd": null
},
"nonLeads": {
"used": 0,
"limit": null
},
"testLeads": {
"used": 0,
"limit": null
},
"evaluations": {
"used": 0,
"free": 0
},
"generations": {
"used": 0,
"limit": null
},
"byWorkspace": [
{
"workspaceId": "work_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"leads": 0
}
]
},
"plans": [
{
"id": "free",
"name": "name",
"priceUsd": null,
"leads": null,
"overageUsd": null,
"workspaces": null,
"requestsPerSecond": 0
}
],
"allowances": {
"nonLeadMultiple": 0,
"testLeads": 0,
"freeEvaluations": 0,
"evaluationsPerLead": 0,
"generations": 0,
"thresholds": [
0
]
}
}
PATCH/v1/billing
Set the spending limit for leads beyond the plan (admin)
Required attributes
- Name
spendLimitUsd- Type
- number or null
- Description
null = the plan price
Request
PATCH
/v1/billingcurl -X PATCH https://core.leadveyor.com/v1/billing \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"spendLimitUsd": null
}'
Response 200
{
"object": "billing",
"plan": "free",
"status": "active",
"cancelAtPeriodEnd": false,
"pendingPlan": "free",
"spendLimitUsd": null,
"hasSubscription": false,
"paymentsEnabled": false,
"usage": {
"object": "usage",
"plan": "free",
"periodStart": "2026-11-02T09:30:00.000Z",
"periodEnd": "2026-11-02T09:30:00.000Z",
"leads": {
"used": 0,
"included": null,
"percent": null,
"overage": 0,
"overageUsd": 0,
"spendLimitUsd": null
},
"nonLeads": {
"used": 0,
"limit": null
},
"testLeads": {
"used": 0,
"limit": null
},
"evaluations": {
"used": 0,
"free": 0
},
"generations": {
"used": 0,
"limit": null
},
"byWorkspace": [
{
"workspaceId": "work_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"leads": 0
}
]
},
"plans": [
{
"id": "free",
"name": "name",
"priceUsd": null,
"leads": null,
"overageUsd": null,
"workspaces": null,
"requestsPerSecond": 0
}
],
"allowances": {
"nonLeadMultiple": 0,
"testLeads": 0,
"freeEvaluations": 0,
"evaluationsPerLead": 0,
"generations": 0,
"thresholds": [
0
]
}
}
GET/v1/usage
This period's usage against the plan
Leads used and included, leads beyond the plan and their cost, broken down by workspace.
Request
GET
/v1/usagecurl https://core.leadveyor.com/v1/usage \
-H "Authorization: Bearer {api_key}"
Response 200
{
"object": "usage",
"plan": "free",
"periodStart": "2026-11-02T09:30:00.000Z",
"periodEnd": "2026-11-02T09:30:00.000Z",
"leads": {
"used": 0,
"included": null,
"percent": null,
"overage": 0,
"overageUsd": 0,
"spendLimitUsd": null
},
"nonLeads": {
"used": 0,
"limit": null
},
"testLeads": {
"used": 0,
"limit": null
},
"evaluations": {
"used": 0,
"free": 0
},
"generations": {
"used": 0,
"limit": null
},
"byWorkspace": [
{
"workspaceId": "work_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"leads": 0
}
]
}
POST/v1/billing/checkout
Start a subscription (admin): returns a Stripe Checkout link
Required attributes
- Name
plan- Type
- 'starter' | 'pro' | 'agency'
- Description
Request
POST
/v1/billing/checkoutcurl -X POST https://core.leadveyor.com/v1/billing/checkout \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"plan": "starter"
}'
Response 200
{
"object": "checkout_session",
"url": "https://example.com"
}
POST/v1/billing/plan
Change plan (admin): upgrades apply now, downgrades from the next period
Required attributes
- Name
plan- Type
- 'starter' | 'pro' | 'agency'
- Description
Request
POST
/v1/billing/plancurl -X POST https://core.leadveyor.com/v1/billing/plan \
-H "Authorization: Bearer {api_key}" \
-H "Content-Type: application/json" \
-d '{
"plan": "starter"
}'
Response 200
{
"object": "billing",
"plan": "free",
"status": "active",
"cancelAtPeriodEnd": false,
"pendingPlan": "free",
"spendLimitUsd": null,
"hasSubscription": false,
"paymentsEnabled": false,
"usage": {
"object": "usage",
"plan": "free",
"periodStart": "2026-11-02T09:30:00.000Z",
"periodEnd": "2026-11-02T09:30:00.000Z",
"leads": {
"used": 0,
"included": null,
"percent": null,
"overage": 0,
"overageUsd": 0,
"spendLimitUsd": null
},
"nonLeads": {
"used": 0,
"limit": null
},
"testLeads": {
"used": 0,
"limit": null
},
"evaluations": {
"used": 0,
"free": 0
},
"generations": {
"used": 0,
"limit": null
},
"byWorkspace": [
{
"workspaceId": "work_9Kx2Lq7Vt4Wz8Nb3Pc6Rd1Hm",
"leads": 0
}
]
},
"plans": [
{
"id": "free",
"name": "name",
"priceUsd": null,
"leads": null,
"overageUsd": null,
"workspaces": null,
"requestsPerSecond": 0
}
],
"allowances": {
"nonLeadMultiple": 0,
"testLeads": 0,
"freeEvaluations": 0,
"evaluationsPerLead": 0,
"generations": 0,
"thresholds": [
0
]
}
}
POST/v1/billing/portal
Card, invoices and cancelling (admin): returns a Stripe portal link
Request
POST
/v1/billing/portalcurl -X POST https://core.leadveyor.com/v1/billing/portal \
-H "Authorization: Bearer {api_key}"
Response 200
{
"object": "checkout_session",
"url": "https://example.com"
}