React

React hooks for billing.io

React hooks for billing.io. Built on top of @billing-io/sdk with built-in state management, auto-polling, and TypeScript support.

npm

@billing-io/react

GitHub

billing-io/sdk-react

Installation

npm install @billing-io/react @billing-io/sdk

@billing-io/sdk and react >= 18 are peer dependencies.

Setup

Wrap your app with BillingProvider:

import { BillingProvider } from "@billing-io/react";

function App() {
  return (
    <BillingProvider apiKey="sk_live_...">
      <YourApp />
    </BillingProvider>
  );
}

Create a Checkout

import { useCreateCheckout } from "@billing-io/react";

function CheckoutButton() {
  const { createCheckout, data, loading, error } = useCreateCheckout();

  const handleClick = async () => {
    await createCheckout({
      amount_usd: 49.99,
      chain: "tron",
      token: "USDT",
    });
  };

  return (
    <div>
      <button onClick={handleClick} disabled={loading}>
        {loading ? "Creating..." : "Pay $49.99"}
      </button>
      {data && <p>Send payment to: {data.deposit_address}</p>}
      {error && <p>Error: {error.message}</p>}
    </div>
  );
}

Poll Checkout Status

useCheckoutStatus automatically polls at the interval returned by the API:

import { useCheckoutStatus } from "@billing-io/react";

function CheckoutTracker({ checkoutId }: { checkoutId: string }) {
  const { data, loading } = useCheckoutStatus(checkoutId);

  if (loading) return <p>Loading...</p>;

  return (
    <div>
      <p>Status: {data.status}</p>
      <p>
        Confirmations: {data.confirmations}/{data.required_confirmations}
      </p>
    </div>
  );
}

List Checkouts

import { useCheckouts } from "@billing-io/react";

function CheckoutList() {
  const { data, loading, error } = useCheckouts({ limit: 10 });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data.map((checkout) => (
        <li key={checkout.checkout_id}>
          {checkout.checkout_id} - {checkout.status}
        </li>
      ))}
    </ul>
  );
}

Access the SDK Client Directly

Use useBillingClient for operations not covered by hooks:

import { useBillingClient } from "@billing-io/react";

function CustomComponent() {
  const billing = useBillingClient();

  const handleAction = async () => {
    const invoice = await billing.invoices.create({
      /* ... */
    });
  };

  return <button onClick={handleAction}>Create Invoice</button>;
}

Customers

import { useCustomers, useCreateCustomer } from "@billing-io/react";

function CustomerList() {
  const { data, loading } = useCustomers({ limit: 20 });
  const { createCustomer } = useCreateCustomer();

  return (
    <div>
      <button onClick={() => createCustomer({ email: "[e-mail]", name: "Alice" })}>
        Add Customer
      </button>
      {data?.map((c) => <p key={c.id}>{c.name} - {c.email}</p>)}
    </div>
  );
}

Subscriptions

import { useSubscriptions, useCreateSubscription } from "@billing-io/react";

function SubscriptionManager() {
  const { data: subs, loading } = useSubscriptions({ status: "active" });
  const { createSubscription } = useCreateSubscription();

  const handleSubscribe = () => {
    createSubscription({
      customer_id: "cus_abc123",
      plan_id: "plan_abc123",
      payment_method_id: "pm_abc123",
    });
  };

  if (loading) return <p>Loading...</p>;

  return (
    <div>
      <button onClick={handleSubscribe}>Subscribe</button>
      {subs?.map((sub) => (
        <p key={sub.id}>{sub.customer_id} - {sub.status}</p>
      ))}
    </div>
  );
}

Payouts

import { usePayouts, useCreatePayout, useExecutePayout } from "@billing-io/react";

function PayoutDashboard() {
  const { data: payouts } = usePayouts({ limit: 10 });
  const { createPayout } = useCreatePayout();
  const { executePayout } = useExecutePayout();

  return (
    <div>
      {payouts?.map((p) => (
        <div key={p.id}>
          {p.amount} {p.token} - {p.status}
          {p.status === "approved" && (
            <button onClick={() => executePayout(p.id)}>
              Submit TX
            </button>
          )}
        </div>
      ))}
    </div>
  );
}

Available Hooks

Hook	Description
Checkouts
useCreateCheckout	Create a checkout with loading/error state
useCheckoutStatus	Poll checkout status with auto-refresh
useCheckouts	List checkouts with pagination
Customers
useCustomers	List customers
useCustomer	Get a single customer by ID
useCreateCustomer	Create a new customer
useUpdateCustomer	Update a customer
Payment Methods
usePaymentMethods	List payment methods
useCreatePaymentMethod	Create a payment method
useUpdatePaymentMethod	Update a payment method
useDeletePaymentMethod	Delete a payment method
useSetDefaultPaymentMethod	Set default payment method
Payment Links
usePaymentLinks	List payment links
useCreatePaymentLink	Create a payment link
Subscriptions
useSubscriptions	List subscriptions
useCreateSubscription	Create a subscription
useUpdateSubscription	Update/cancel a subscription
useSubscriptionPlans	List plans
useCreateSubscriptionPlan	Create a plan
useUpdateSubscriptionPlan	Update/archive a plan
useRenewals	List subscription renewals
useRetryRenewal	Retry a failed renewal
Entitlements
useEntitlements	List entitlements
useCreateEntitlement	Create an entitlement
useUpdateEntitlement	Update an entitlement
useDeleteEntitlement	Delete an entitlement
useCheckEntitlement	Check feature access for a customer
Payouts
usePayouts	List payout intents
useCreatePayout	Create a payout intent
useUpdatePayout	Update a payout intent
useExecutePayout	Submit tx hash for execution
useSettlements	List settlements
Revenue
useRevenueEvents	List revenue events
useAccounting	Get accounting summary
useAdjustments	List adjustments
useCreateAdjustment	Create an adjustment
Other
useWebhookEndpoints	Manage webhook endpoints
useEvents	List billing events
useBillingClient	Access the raw SDK client