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:

{
  "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:

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

Example:

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:

{
  "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:

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:

{
  "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:

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

Example:

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