# Billing API

> Plans, subscriptions, payment methods, invoices, usage and prepaid credits.

Base URL: `https://api.socialit.com/v1`. Authenticate with `Authorization: Bearer <API key or OAuth token>`.

## Get usage

`GET /usage`

Plan, limits and consumption for the current period: connected accounts against the allowance (plan included + extra accounts + lifetime + Apple seats), members, profiles, webhooks, API keys, posts, storage, API requests this hour, X API pass-through calls and spend, and prepaid credits. Also covers the deprecated usage-stats snapshot.

Access: `read` · MCP tool: `get-usage` · Zernio: `GET /v1/usage`, `GET /v1/usage-stats`

```bash
curl "https://api.socialit.com/v1/usage" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "usage",
  "plan": "free",
  "interval": "string",
  "period_start": "2026-10-13T09:00:00.000Z",
  "period_end": "2026-10-13T09:00:00.000Z",
  "accounts": {
    "used": 1,
    "included": 1,
    "extra_purchased": 1,
    "lifetime": 1,
    "apple": 1,
    "legacy_subscribed": 1,
    "limit": 1,
    "available": 1,
    "over_limit": 1,
    "paused": 1
  },
  "members": {
    "used": 1,
    "limit": 1
  },
  "profiles": {
    "used": 1,
    "limit": 1
  },
  "webhooks": {
    "used": 1,
    "limit": 1
  },
  "api_keys": {
    "used": 1,
    "limit": 1
  },
  "posts": {
    "this_month": 1,
    "limit_per_month": 1
  },
  "storage": {
    "used_bytes": 1,
    "limit_bytes": 1
  },
  "api": {
    "requests_this_hour": 1,
    "limit_per_hour": 1
  },
  "x_api": {
    "calls": 1,
    "spend_cents": 1,
    "calls_by_operation": {
      "key": 1
    }
  },
  "credits_cents": 1
}
```

## Get X API usage

`GET /usage/x-api`

Metering of X API pass-through calls (debited from prepaid credits at cost) over a window: totals, per-operation breakdown and a day/month series. Pair with GET /billing/x-pricing. Profile-restricted keys only see their profiles’ accounts.

Access: `read` · MCP tool: `get-x-api-usage`

### Query parameters

- `range` (string; one of cycle, prev_cycle, 7d, 30d, 90d, 12mo, custom)
- `from` (string (date))
- `to` (string (date))
- `granularity` (string; one of day, month, total)
- `account_id` (string; pattern ^sa_[0-9A-Za-z]{27}$)

```bash
curl "https://api.socialit.com/v1/usage/x-api" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "x_api_usage",
  "range": "string",
  "from": "+15551234567",
  "to": "+15551234567",
  "granularity": "string",
  "totals": {
    "calls": 1,
    "spend_cents": 1,
    "spend_micro_usd": 1
  },
  "by_operation": [
    {
      "operation": "string",
      "calls": 1,
      "spend_cents": 1
    }
  ],
  "days": [
    {
      "date": "string",
      "calls": 1,
      "spend_cents": 1
    }
  ]
}
```

## Get billing overview

`GET /billing`

Plan, billing interval, subscription status and period, extra accounts, recurring price, account allowance and publishing pause, payment method, invoices summary, upcoming invoice, credits and the dashboard banner.

Access: `read` · MCP tool: `get-billing` · Zernio: `GET /v1/billing`

```bash
curl "https://api.socialit.com/v1/billing" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "billing",
  "plan": "free",
  "plan_name": "string",
  "interval": "string",
  "status": "string",
  "provider": "none",
  "customer_id": "string",
  "subscription_id": "string",
  "current_period_start": "2026-10-13T09:00:00.000Z",
  "current_period_end": "2026-10-13T09:00:00.000Z",
  "cancel_at_period_end": true,
  "canceled_at": "2026-10-13T09:00:00.000Z",
  "extra_accounts": 1,
  "price": {
    "currency": "USD",
    "base_cents": 1,
    "extra_account_cents": 1,
    "extra_accounts_cents": 1,
    "total_cents": 1,
    "period": "string"
  },
  "accounts": {
    "used": 1,
    "included": 1,
    "extra_purchased": 1,
    "lifetime": 1,
    "apple": 1,
    "legacy_subscribed": 1,
    "limit": 1,
    "available": 1,
    "over_limit": 1,
    "paused": 1
  },
  "publishing_paused": {
    "active": true,
    "account_ids": [
      "string"
    ]
  },
  "banner": {
    "type": "string",
    "severity": "string",
    "message": "string",
    "action": "string"
  },
  "payment_method": {
    "object": "payment_method",
    "id": "string",
    "type": "string",
    "brand": "string",
    "last4": "string",
    "exp_month": 1,
    "exp_year": 1,
    "wallet": "string",
    "is_default": true,
    "created_at": "2026-10-13T09:00:00.000Z"
  },
  "has_payment_method": true,
  "invoices": {
    "latest": {
      "object": "invoice",
      "id": "string",
      "number": "string",
      "status": "string",
      "currency": "USD",
      "amount_due_cents": 1,
      "amount_paid_cents": 1,
      "amount_remaining_cents": 1,
      "subtotal_cents": 1,
      "tax_cents": 1,
      "total_cents": 1,
      "billing_reason": "string",
      "description": "string",
      "period_start": "2026-10-13T09:00:00.000Z",
      "period_end": "2026-10-13T09:00:00.000Z",
      "hosted_invoice_url": "https://example.com",
      "invoice_pdf": "string",
      "due_date": "2026-10-13T09:00:00.000Z",
      "paid_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "lines": [
        {
          "description": "string",
          "amount_cents": 1,
          "quantity": 1,
          "period_start": "2026-10-13T09:00:00.000Z",
          "period_end": "2026-10-13T09:00:00.000Z"
        }
      ]
    },
    "open_count": 1,
    "open_amount_cents": 1
  },
  "upcoming_invoice": {
    "amount_due_cents": 1,
    "currency": "USD",
    "next_payment_attempt": "2026-10-13T09:00:00.000Z"
  },
  "credits_cents": 1,
  "x_usage_blocked": true,
  "legacy": {
    "billing_mode": "string",
    "lifetime_seats": 1,
    "subscribed_seats": 1,
    "apple_seats": 1,
    "source": "string",
    "metered": true
  }
}
```

## List plans

`GET /billing/plans`

Prices (price_cents per month, year = per month billed yearly; billed_cents per billing period), extra account prices, limits and features of every plan.

Access: `read` · MCP tool: `list-plans`

```bash
curl "https://api.socialit.com/v1/billing/plans" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "plan",
      "id": "free",
      "name": "string",
      "rank": 1,
      "self_serve": true,
      "current": true,
      "price_cents": {
        "month": 1,
        "year": 1
      },
      "billed_cents": {
        "month": 1,
        "year": 1
      },
      "extra_account_cents": {
        "month": 1,
        "year": 1
      },
      "extra_account_billed_cents": {
        "month": 1,
        "year": 1
      },
      "limits": {},
      "features": {}
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get X API pricing

`GET /billing/x-pricing`

The X API pass-through price table (zero markup) by operation and tier. Safe to cache for a billing period.

Access: `read` · MCP tool: `get-x-pricing` · Zernio: `GET /v1/billing/x-pricing`

```bash
curl "https://api.socialit.com/v1/billing/x-pricing" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "x_pricing",
  "currency": "USD",
  "markup": "string",
  "source": "string",
  "last_verified": "string",
  "tiers": [
    {
      "tier": "string",
      "price_per_call_usd": 1.5,
      "operation_count": 1
    }
  ],
  "operations": [
    {
      "operation": "string",
      "display_name": "string",
      "price_per_call_usd": 1.5,
      "price_per_call_cents": 1.5,
      "price_micro_usd": 1,
      "tier": "string",
      "triggered_by": [
        "string"
      ]
    }
  ]
}
```

## Get prepaid credits

`GET /billing/credits`

Credit balance (USD cents) used for X API pass-through calls, whether X actions are blocked, and the credit packs for sale.

Access: `read` · MCP tool: `get-billing-credits`

```bash
curl "https://api.socialit.com/v1/billing/credits" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "credits",
  "balance_cents": 1,
  "x_usage_blocked": true,
  "packs": [
    {
      "id": "string",
      "price_cents": 1,
      "credits_cents": 1,
      "ios_product_id": "string"
    }
  ]
}
```

## Preview a plan change

`GET /billing/preview`

Recurring price and the proration due now for switching plan, interval or extra accounts. Without a subscription the preview is the first period (requires_checkout: true). Upgrades are invoiced immediately; downgrades credit the next invoice.

Access: `read` · MCP tool: `preview-billing-change`

### Query parameters

- `plan` (string; required; one of free, pro, business, enterprise)
- `interval` (string; one of month, year)
- `extra_accounts` (integer; 0–100000)

```bash
curl "https://api.socialit.com/v1/billing/preview?plan=value" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "billing_preview",
  "plan": "string",
  "interval": "string",
  "extra_accounts": 1,
  "change_type": "new",
  "requires_checkout": true,
  "currency": "USD",
  "recurring": {
    "base_cents": 1,
    "extra_accounts_cents": 1,
    "total_cents": 1,
    "period": "string"
  },
  "amount_due_now_cents": 1,
  "proration_date": 1,
  "lines": [
    {
      "description": "string",
      "amount_cents": 1,
      "proration": true,
      "period_start": "2026-10-13T09:00:00.000Z",
      "period_end": "2026-10-13T09:00:00.000Z"
    }
  ],
  "next_invoice_at": "2026-10-13T09:00:00.000Z",
  "accounts": {
    "used": 1,
    "limit_after": 1,
    "over_limit_after": 1
  }
}
```

## List invoices

`GET /billing/invoices`

Stripe invoices of the workspace, newest first, with hosted page and PDF links.

Access: `read` · MCP tool: `list-billing-invoices`

### Query parameters

- `page` (integer; 1–50)
- `limit` (integer; 1–100)
- `status` (string; one of draft, open, paid, uncollectible, void)

```bash
curl "https://api.socialit.com/v1/billing/invoices" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "string",
      "number": "string",
      "status": "string",
      "currency": "USD",
      "amount_due_cents": 1,
      "amount_paid_cents": 1,
      "amount_remaining_cents": 1,
      "subtotal_cents": 1,
      "tax_cents": 1,
      "total_cents": 1,
      "billing_reason": "string",
      "description": "string",
      "period_start": "2026-10-13T09:00:00.000Z",
      "period_end": "2026-10-13T09:00:00.000Z",
      "hosted_invoice_url": "https://example.com",
      "invoice_pdf": "string",
      "due_date": "2026-10-13T09:00:00.000Z",
      "paid_at": "2026-10-13T09:00:00.000Z",
      "created_at": "2026-10-13T09:00:00.000Z",
      "lines": [
        {
          "description": "string",
          "amount_cents": 1,
          "quantity": 1,
          "period_start": "2026-10-13T09:00:00.000Z",
          "period_end": "2026-10-13T09:00:00.000Z"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1,
  "total": 1,
  "has_more": true,
  "next_page_url": "https://example.com",
  "previous_page_url": "https://example.com"
}
```

## Get an invoice

`GET /billing/invoices/{id}`

Access: `read` · MCP tool: `get-billing-invoice`

### Path parameters

- `id` (string; required; pattern ^in_[A-Za-z0-9_]+$)

```bash
curl "https://api.socialit.com/v1/billing/invoices/ID" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Response 200:

```json
{
  "object": "invoice",
  "id": "string",
  "number": "string",
  "status": "string",
  "currency": "USD",
  "amount_due_cents": 1,
  "amount_paid_cents": 1,
  "amount_remaining_cents": 1,
  "subtotal_cents": 1,
  "tax_cents": 1,
  "total_cents": 1,
  "billing_reason": "string",
  "description": "string",
  "period_start": "2026-10-13T09:00:00.000Z",
  "period_end": "2026-10-13T09:00:00.000Z",
  "hosted_invoice_url": "https://example.com",
  "invoice_pdf": "string",
  "due_date": "2026-10-13T09:00:00.000Z",
  "paid_at": "2026-10-13T09:00:00.000Z",
  "created_at": "2026-10-13T09:00:00.000Z",
  "lines": [
    {
      "description": "string",
      "amount_cents": 1,
      "quantity": 1,
      "period_start": "2026-10-13T09:00:00.000Z",
      "period_end": "2026-10-13T09:00:00.000Z"
    }
  ]
}
```


---

Source: https://socialit.com/docs/api-reference/billing/
