1eye Docs – Buyer Signals API, Webhooks, MCP & Integrations

Retrieve the billing arrangement, configured pricing, balance or unbilled charges, payment method, and billing history for the workspace associated with your API key.

GET /v1/billing

This endpoint is read-only. It does not buy credits, change plans or payment methods, update auto-reload settings, or pay invoices.

Authentication

All requests require a workspace API key:

Authorization: Bearer 1eye_live_xxxxxxxxx

The examples use $API_KEY for your API key. The key determines the workspace; you do not supply a workspace ID. See Authentication.

Request

curl "https://api.1eye.ai/v1/billing" \
  -H "Authorization: Bearer $API_KEY"

No query parameters, sorting, or pagination are supported.

Response

200 OK — returns one Billing object directly. All workspaces use the same top-level structure. plan and payment_collection identify the billing arrangement:

Arrangement	`plan`	`payment_collection`
Standard prepaid	`prepaid`	`card`
Contract prepaid	`prepaid`	`invoice`
Card postpaid	`postpaid`	`card`
Invoice postpaid	`postpaid`	`invoice`

Exactly one accounting object is populated: prepaid workspaces have prepaid and postpaid: null; postpaid workspaces have prepaid: null and postpaid.

Example: standard prepaid

{
  "client_id": "wor_123456789012345678",
  "plan": "prepaid",
  "payment_collection": "card",
  "currency": "USD",
  "price_per_credit": "0.05",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": {
    "credit_balance": 8000,
    "total_credits_added": 9000,
    "total_credits_consumed": 1000,
    "spent_this_month": "200.00",
    "auto_reload": {
      "enabled": true,
      "threshold": 1000,
      "amount": "20.00",
      "credits": 400
    },
    "monthly_limit": {
      "enabled": true,
      "amount": "1000.00"
    }
  },
  "postpaid": null,
  "payment_method": {
    "type": "card",
    "network": "visa",
    "last4": "4242"
  },
  "billing_history": [
    {
      "id": "pay_123456789012345678",
      "type": "reload",
      "status": "paid",
      "amount": "200.00",
      "credits": 4000,
      "invoice_url": "https://example.com/invoices/snowbricks-prepaid.pdf",
      "created_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "grt_123456789012345678",
      "type": "grant",
      "status": "paid",
      "amount": "0.00",
      "credits": 5000,
      "invoice_url": null,
      "created_at": "2026-10-18T18:00:00Z"
    }
  ]
}

All names, domains, identifiers, amounts, URLs, and timestamps in these examples are illustrative.

Billing fields

Field	Type	Description
`client_id`	string	Authenticated Workspace ID.
`plan`	string	`prepaid` or `postpaid`.
`payment_collection`	string	`card` or `invoice`.
`currency`	string	Billing currency, initially `USD`.
`price_per_credit`	decimal string	Current configured money price per credit.
`credit_costs`	object	Credits per `buyer`, `signal`, `email`, and `phone` activity.
`prepaid`	object or null	Balance, lifetime credit totals, and purchase settings.
`postpaid`	object or null	Current-month consumption, accrued charges, and payment terms.
`payment_method`	object or null	Configured or preferred payment method.
`billing_history`	array	Customer-facing billing transactions, invoices, and grants.

Money values are decimal strings such as "20.00"; credit quantities and activity costs are integers. Example prices are illustrative, not universal rates. credit_costs matches Usage.

Prepaid accounting

Field	Type	Description
`credit_balance`	integer	Credits currently available.
`total_credits_added`	integer	Lifetime funded purchases, grants, and positive adjustments.
`total_credits_consumed`	integer	Lifetime consumption net of reversed consumption.
`spent_this_month`	decimal string	Net confirmed prepaid payments collected this calendar month.
`auto_reload`	object or null	Automatic purchase configuration, when applicable.
`monthly_limit`	object or null	Monthly cap on automatic reload spending, when applicable.

spent_this_month measures payments, rather than credits consumed multiplied by current pricing. Lifetime credits added can include free grants. auto_reload contains enabled, the credit-balance threshold, the purchase amount, and the purchased credits. monthly_limit contains enabled and its money amount. A disabled configuration may retain its saved values; null means the feature is not applicable or has no configuration.

Example: contract prepaid

This is an alternative fictional account arrangement. Invoice collection can use a card or bank transfer; it does not require bank transfer in every case. Contract prepaid does not use auto reload or its monthly limit.

{
  "client_id": "wor_123456789012345678",
  "plan": "prepaid",
  "payment_collection": "invoice",
  "currency": "USD",
  "price_per_credit": "0.04",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": {
    "credit_balance": 10000,
    "total_credits_added": 11000,
    "total_credits_consumed": 1000,
    "spent_this_month": "400.00",
    "auto_reload": null,
    "monthly_limit": null
  },
  "postpaid": null,
  "payment_method": {
    "type": "bank_transfer"
  },
  "billing_history": [
    {
      "id": "inv_123456789012345678",
      "type": "prepaid",
      "status": "paid",
      "amount": "400.00",
      "credits": 10000,
      "invoice_url": "https://example.com/invoices/snowbricks-contract-prepaid.pdf",
      "created_at": "2026-10-20T18:00:00Z"
    },
    {
      "id": "grt_123456789012345678",
      "type": "grant",
      "status": "paid",
      "amount": "0.00",
      "credits": 1000,
      "invoice_url": null,
      "created_at": "2026-10-18T18:00:00Z"
    }
  ]
}

Postpaid accounting

Field	Type	Description
`credits_consumed_this_month`	integer	Credits consumed in the current calendar month.
`unbilled_amount_this_month`	decimal string	Accrued charges not yet invoiced this month.
`payment_terms_days`	integer	Nonnegative number of days allowed after invoice issuance.

Postpaid usage resets with the authoritative billing calendar month. Historical invoices remain in billing_history. Usage and Billing follow the same accounting boundaries.

Example: card postpaid

Payment is due immediately and collected using the configured card; payment_terms_days is 0.

{
  "client_id": "wor_123456789012345678",
  "plan": "postpaid",
  "payment_collection": "card",
  "currency": "USD",
  "price_per_credit": "0.05",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": null,
  "postpaid": {
    "credits_consumed_this_month": 145,
    "unbilled_amount_this_month": "7.25",
    "payment_terms_days": 0
  },
  "payment_method": {
    "type": "card",
    "network": "visa",
    "last4": "4242"
  },
  "billing_history": [
    {
      "id": "pay_987654321098765432",
      "type": "postpaid",
      "status": "paid",
      "amount": "50.00",
      "credits": 1000,
      "invoice_url": "https://example.com/invoices/snowbricks-card-postpaid.pdf",
      "created_at": "2026-10-01T07:00:00Z"
    }
  ]
}

Example: invoice postpaid

The customer pays issued invoices under the configured terms. This example uses Net 30; the actual value follows the billing agreement and is not a fixed enum. Invoice collection may use a card or bank transfer.

{
  "client_id": "wor_123456789012345678",
  "plan": "postpaid",
  "payment_collection": "invoice",
  "currency": "USD",
  "price_per_credit": "0.04",
  "credit_costs": {
    "buyer": 2,
    "signal": 1,
    "email": 2,
    "phone": 5
  },
  "prepaid": null,
  "postpaid": {
    "credits_consumed_this_month": 145,
    "unbilled_amount_this_month": "5.80",
    "payment_terms_days": 30
  },
  "payment_method": {
    "type": "bank_transfer"
  },
  "billing_history": [
    {
      "id": "inv_987654321098765432",
      "type": "postpaid",
      "status": "unpaid",
      "amount": "100.00",
      "credits": 2500,
      "invoice_url": "https://example.com/invoices/snowbricks-invoice-postpaid.pdf",
      "created_at": "2026-10-01T07:00:00Z"
    }
  ]
}

Payment method

Card display metadata uses type, network, and last4. A bank-transfer method uses {"type": "bank_transfer"}. payment_method: null means no method is configured. payment_collection describes the collection arrangement; payment_method describes the preferred or configured method. They should not be inferred from one another. Full card or bank account information and processor credentials are never returned.

Billing history

History is ordered newest first by created_at and includes the workspace’s customer-facing history across prior billing arrangements. The same transaction structure is used for all models.

Field	Type	Description
`id`	string	Stable public transaction, grant, or invoice identifier.
`type`	string	`grant`, `reload`, `prepaid`, or `postpaid`.
`status`	string	`paid`, `unpaid`, or `voided`.
`amount`	decimal string	Transaction or invoice amount.
`credits`	integer	Credit quantity associated with the record.
`invoice_url`	string or null	Authorized invoice document link, when available.
`created_at`	datetime	Transaction or invoice issuance timestamp in UTC.

Types and statuses

grant: free credits; amount is "0.00", status is paid, and an invoice link may be absent.
reload: self-service prepaid credit purchase.
prepaid: funded contract prepaid purchase.
postpaid: monthly usage invoice.

paid means fully settled or a free grant. unpaid includes an issued invoice awaiting payment, including a partially paid invoice or one with a failed payment attempt. voided means canceled and no longer payable. These are financial statuses; the API does not expose every internal payment-attempt state. An unavailable invoice document uses invoice_url: null. History is returned in the Billing response rather than through a paginated subresource. Use Usage for daily and monthly activity reporting and Workspace Info for the billing contact. Financial configuration changes follow the existing 1eye billing workflows.

Errors

Status	Error code	Description
400	`invalid_parameter`	A request field or query parameter is invalid.
401	`authentication_error`	The API key is missing, invalid, or revoked.
403	`permission_denied`	The key does not have permission for this operation.
429	`rate_limit_exceeded`	The workspace API rate limit was exceeded.
500	`internal_error`	An unexpected server error occurred.
503	`service_unavailable`	The service is temporarily unavailable.

Errors use the standard error envelope. Use request_id when contacting support.

Get Started

Buyers

Signals

Target Lists

Destinations

Knowledge Base

Workspace

Billing

Authentication

Request

Response

Example: standard prepaid

Billing fields

Prepaid accounting

Example: contract prepaid

Postpaid accounting

Example: card postpaid

Example: invoice postpaid

Payment method

Billing history

Types and statuses

Errors

​Authentication

​Request

​Response

​Example: standard prepaid

​Billing fields

​Prepaid accounting

​Example: contract prepaid

​Postpaid accounting

​Example: card postpaid

​Example: invoice postpaid

​Payment method

​Billing history

​Types and statuses

​Related APIs

​Errors

Authentication

Request

Response

Example: standard prepaid

Billing fields

Prepaid accounting

Example: contract prepaid

Postpaid accounting

Example: card postpaid

Example: invoice postpaid

Payment method

Billing history

Types and statuses

Related APIs

Errors