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/billing
curl 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/billing
curl -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/usage
curl 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

Required attributes

  • Name
    plan
    Type
    'starter' | 'pro' | 'agency'
    Description

     

Request

POST
/v1/billing/checkout
curl -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/plan
curl -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

Request

POST
/v1/billing/portal
curl -X POST https://core.leadveyor.com/v1/billing/portal \
  -H "Authorization: Bearer {api_key}"

Response 200

{
  "object": "checkout_session",
  "url": "https://example.com"
}

Was this page helpful?