# Billing

Manage credit allocation, retrieve billing information, and calculate costs. Partners can allocate credits to organizations and monitor usage across the billing period.

## Allocate Credits

Allocate credits to an organization from the partner credit pool.

**Request:**

```
PUT /partner/organizations/{organizationId}/credits
```

**Body:**

```json
{
  "credits": 500,
  "notes": "Monthly allocation for Acme Corp"
}
```

| Field     | Type    | Required | Description                      |
| --------- | ------- | -------- | -------------------------------- |
| `credits` | integer | Yes      | Number of credits to allocate    |
| `notes`   | string  | No       | Optional note for the allocation |

**Response:**

```json
{
  "allocation": {
    "id": "uuid",
    "partnerId": "uuid",
    "organizationId": "uuid",
    "creditsAllocated": 500,
    "creditsUsed": 0,
    "creditsAvailable": 500,
    "allocatedAt": "2025-02-27T10:30:00Z"
  }
}
```

**Example:**

```bash
curl -X PUT "https://api.app.bullseye.so/api/v1/partner/organizations/org-uuid/credits" \
  -H "X-Partner-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"credits": 500, "notes": "Monthly allocation"}'
```

***

## Get Billing Info

Retrieve billing configuration and credit pool status for the partner account.

**Request:**

```
GET /partner/billing
```

**Response:**

```json
{
  "partnerId": "uuid",
  "billingMode": "pooled",
  "billingPeriod": "monthly",
  "billingDayOfMonth": 1,
  "billingPeriodStart": "2025-02-01T00:00:00Z",
  "nextBillingDate": "2025-03-01T00:00:00Z",
  "stripeCustomerId": "cus_xxx",
  "pricingTiers": [
    {
      "tier": "trial",
      "pricePerIdentification": 0,
      "minUsage": 0,
      "maxUsage": 1000
    },
    {
      "tier": "standard",
      "pricePerIdentification": 0.05,
      "minUsage": 1001,
      "maxUsage": 10000
    }
  ],
  "creditPoolTotal": 10000,
  "creditPoolUsed": 2500,
  "creditPoolAvailable": 7500
}
```

**Example:**

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/partner/billing" \
  -H "X-Partner-API-Key: your-api-key"
```

***

## Get Billing Period Usage

Retrieve usage and estimated cost for the current billing period.

**Request:**

```
GET /partner/billing/usage
```

**Response:**

```json
{
  "partnerId": "uuid",
  "periodStart": "2025-02-01T00:00:00Z",
  "periodEnd": "2025-02-28T23:59:59Z",
  "totalIdentifications": 2500,
  "totalAudienceBuilds": 150,
  "totalUsage": 2650,
  "estimatedCost": 132.50,
  "currency": "USD"
}
```

***

## Calculate Billing

Calculate the cost for a given usage amount. Useful for estimating costs before allocation.

**Request:**

```
GET /partner/billing/calculate?usage=5000
```

**Query Parameters:**

| Parameter | Type    | Required | Description                           |
| --------- | ------- | -------- | ------------------------------------- |
| `usage`   | integer | Yes      | Number of identifications/usage units |

**Response:**

```json
{
  "usage": 5000,
  "totalCost": 250.00,
  "currency": "USD",
  "tierBreakdown": [
    {
      "tier": "trial",
      "usage": 1000,
      "cost": 0
    },
    {
      "tier": "standard",
      "usage": 4000,
      "cost": 200.00
    }
  ]
}
```

**Example:**

```bash
curl -X GET "https://api.app.bullseye.so/api/v1/partner/billing/calculate?usage=5000" \
  -H "X-Partner-API-Key: your-api-key"
```


---

# 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-api/billing.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.