Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.billingos.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Hooks

​
useSubscription

Fetch a single subscription by ID. 
import { useSubscription } from "@billingos/sdk";

function SubscriptionDetails({ id }: { id: string }) {
  const { data, isLoading } = useSubscription(id);

  if (isLoading) return <Spinner />;

  return (
    <div>
      <p>Status: {data.status}</p>
      <p>Renews: {new Date(data.current_period_end).toLocaleDateString()}</p>
    </div>
  );
}
Parameters:
NameTypeDescription
idstringSubscription ID
optionsUseQueryOptionsTanStack Query options
Returns: UseQueryResult<Subscription>

​
useSubscriptions

Fetch a paginated list of subscriptions. 
const { data } = useSubscriptions({ page: 1, page_size: 10 });
Parameters:
NameTypeDescription
params.customer_idstringFilter by customer
params.pagenumberPage number
params.page_sizenumberItems per page
Returns: UseQueryResult<PaginatedResponse<Subscription>>

​
useCreateSubscription

Create a new subscription. 
const { mutateAsync: createSubscription } = useCreateSubscription();

await createSubscription({
  customer_id: "cus_123",
  price_id: "price_pro_monthly",
  trial_days: 14,
});

​
useUpdateSubscription

Update an existing subscription. 
const { mutateAsync: updateSubscription } = useUpdateSubscription(subscriptionId);

await updateSubscription({
  price_id: "price_enterprise_monthly",
  cancel_at_period_end: false,
});

​
useCancelSubscription

Cancel a subscription. 
const { mutateAsync: cancel } = useCancelSubscription(subscriptionId);

// Cancel at end of billing period
await cancel({ immediately: false });

// Cancel immediately
await cancel({ immediately: true });

​
useReactivateSubscription

Reactivate a cancelled subscription (before the period ends). 
const { mutateAsync: reactivate } = useReactivateSubscription(subscriptionId);

await reactivate();

​
useSubscriptionPreview

Preview proration for a subscription update. 
const { data } = useSubscriptionPreview(subscriptionId, {
  price_id: "price_enterprise_monthly",
});

// data.proration_amount — charge/credit
// data.next_invoice_amount
// data.next_invoice_date

​
useAvailablePlans

Fetch available upgrade and downgrade options for a subscription. 
const { data } = useAvailablePlans(subscriptionId);

// data.available_upgrades: AvailablePlan[]
// data.available_downgrades: AvailablePlan[]
// data.current_plan: { product_name, price_id, amount, interval }

​
usePreviewPlanChange

Preview what a plan change will cost (proration, next invoice, etc.). 
const { mutateAsync: preview } = usePreviewPlanChange();

const result = await preview({
  subscriptionId: "sub_123",
  input: { new_price_id: "price_enterprise_monthly" },
});

// result.proration — { amount, credited, charged }
// result.change_type — "upgrade" | "downgrade"
// result.next_billing_date

​
useChangePlan

Execute a plan change. 
const { mutateAsync: changePlan } = useChangePlan();

await changePlan({
  subscriptionId: "sub_123",
  input: {
    new_price_id: "price_enterprise_monthly",
    effective_date: "immediate", // or "period_end"
  },
});

​
Subscription object

interface Subscription {
  id: string
  customer_id: string
  price_id: string
  status: "active" | "canceled" | "incomplete" | "incomplete_expired"
         | "past_due" | "trialing" | "unpaid"
  current_period_start: string
  current_period_end: string
  cancel_at_period_end: boolean
  trial_start?: string
  trial_end?: string
  canceled_at?: string
  metadata?: Record<string, string>
  created_at: string
  updated_at: string
}