# 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`:

```json
{
  "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](/partner-program/analytics.md) 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bullseye.so/partner-program/credit-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.