Credit Management

Partners manage identification credits across their sub-organizations. Credits are consumed when a visitor is identified on a client's website. This guide covers the credit pool, billing modes, billing periods, and how to monitor usage.

Credit Pool Concept

When using the credit_pool billing mode, you receive a shared pool of credits from Bullseye. You allocate credits from this pool to individual sub-organizations. Each identification on any sub-organization consumes one credit from that organization's allocation.

• Pool total — The total credits available in your partner account for the billing period

• Allocated — Credits you have assigned to specific sub-organizations

• Remaining — Credits still available in the pool for allocation or use

Credits do not roll over to the next billing period. Unused credits expire when the period ends.

Allocating Credits to Sub-Organizations

Allocate credits from your pool to a sub-organization with PUT /partner/organizations/{organizationId}/credits:

{
  "credits": 500
}

This sets the organization's credit allocation to the specified amount. The allocation is drawn from your partner credit pool. If you do not have sufficient credits in the pool, the request returns a 422 error.

You can adjust allocations at any time. Increase allocation to give a client more credits; decrease to reclaim credits for other organizations.

Billing Modes

Partners can use one of three billing modes:

Mode	Description
credit_pool	Bullseye bills you for a credit pool. You allocate credits to sub-organizations from this pool. Centralized billing with flexible allocation.
external	You handle billing outside of Bullseye. Credits are provisioned based on your agreement with Bullseye. Use webhooks to sync usage data to your billing system.
usage_based	Sub-organizations are billed based on actual usage. Credits are tracked per organization and billed accordingly.

Your billing mode is configured when you onboard as a partner. Contact Bullseye to change your billing mode.

Billing Periods

Credit renewal cycles can be configured as:

Period	Description
monthly	Credits renew each month
quarterly	Credits renew every three months
annually	Credits renew once per year

The billing period applies to your partner account and determines when your credit pool refreshes (for credit_pool mode) or when usage is aggregated for billing (for usage_based mode).

Monitoring Usage

Billing Info

GET /partner/billing returns your billing configuration, including:

• Billing mode

• Billing period

• Credit pool total (for credit_pool mode)

• Credits used and remaining

Billing Period Usage

GET /partner/billing/usage returns usage for the current billing period, including credits consumed across all sub-organizations.

Usage Summary

GET /partner/usage returns a usage summary for a date range:

• startDate and endDate query parameters (ISO format, e.g., 2024-01-01)

• Defaults to the start of the current month through today

• Returns total quantity and total events

Partner Analytics

GET /partner/analytics returns aggregate analytics across all sub-organizations:

• Total organizations and active organizations

• Total identifications in the date range

• Credits remaining and credits used

See Partner Analytics for full details.

Best Practices

• Monitor regularly — Use the analytics and usage endpoints to track consumption and avoid overages

• Allocate conservatively — Start with lower allocations for new clients and increase as usage stabilizes

• Use external IDs — Map organizations to your billing system for accurate client invoicing

• Webhooks — Configure the billing webhook to receive usage events for external billing integration