React hooks for the billing.io API -- checkouts, customers, subscriptions, payouts, revenue & more
npm install @billing-io/reactReact hooks for the billing.io crypto checkout API.
No UI opinions -- bring your own components. This package provides hooks only.
``bash`
npm install @billing-io/react @billing-io/sdk react
react (>=18) and @billing-io/sdk (>=1.0.0) are peer dependencies.
`tsx
import { BillingProvider } from "@billing-io/react";
function App() {
return (
baseUrl="https://api.billing.io/v1" {/ optional /}
>
);
}
`
`tsx
import { useCreateCheckout } from "@billing-io/react";
function CheckoutButton() {
const { createCheckout, data, error, isLoading } = useCreateCheckout();
async function handleClick() {
const checkout = await createCheckout({
amount_usd: 49.99,
chain: "tron",
token: "USDT",
metadata: { order_id: "ord_12345" },
});
console.log("Deposit to:", checkout.deposit_address);
}
return (
Error: {error.message}
}Send funds to: {data.deposit_address}
}$3
tsx
import { useCheckoutStatus } from "@billing-io/react";function PaymentStatus({ checkoutId }: { checkoutId: string }) {
const {
status,
confirmations,
requiredConfirmations,
txHash,
isPolling,
error,
} = useCheckoutStatus(checkoutId);
if (error) return
Error: {error.message}
;
if (!status) return Loading...
; return (
Status: {status}
{txHash && TX: {txHash}
}
Confirmations: {confirmations} / {requiredConfirmations}
{isPolling && Waiting for confirmations...
}
{status === "confirmed" && Payment confirmed!
}
);
}
`The hook uses the server-provided
by default. You can
override it or pause polling entirely:`tsx
// Custom interval
useCheckoutStatus("co_abc123", { pollingInterval: 5000 });// Pause polling
useCheckoutStatus("co_abc123", { enabled: false });
`Polling stops automatically on terminal statuses:
, expired, failed.$3
`tsx
import { useCheckouts } from "@billing-io/react";function CheckoutHistory() {
const { data, error, isLoading, refetch } = useCheckouts({
limit: 10,
status: "confirmed",
});
if (isLoading) return
Loading...
;
if (error) return Error: {error.message}
; return (
{data?.data.map((checkout) => (
{checkout.checkout_id} -- ${checkout.amount_usd} -- {checkout.status}
))}
{data?.has_more && }
);
}
`$3
tsx
import { useWebhookEndpoints } from "@billing-io/react";function Webhooks() {
const { data, error, isLoading } = useWebhookEndpoints({ limit: 25 });
if (isLoading) return
Loading...
;
if (error) return Error: {error.message}
; return (
{data?.data.map((endpoint) => (
{endpoint.url} ({endpoint.status})
))}
);
}
`$3
tsx
import { useEvents } from "@billing-io/react";function EventLog() {
const { data, error, isLoading } = useEvents({
type: "checkout.completed",
limit: 50,
});
if (isLoading) return
Loading...
;
if (error) return Error: {error.message}
; return (
{data?.data.map((event) => (
[{event.type}] {event.checkout_id} at {event.created_at}
))}
);
}
`Direct client access
For operations not covered by a hook (e.g., deleting a webhook), use the
client directly:
tsx
import { useBillingClient } from "@billing-io/react";function DeleteWebhookButton({ webhookId }: { webhookId: string }) {
const client = useBillingClient();
async function handleDelete() {
await client.webhooks.delete(webhookId);
}
return ;
}
`Error handling
All hooks surface errors through an
property. The error object is the
original error thrown by @billing-io/sdk, which includes structured error
information from the API:`tsx
const { error } = useCheckouts();if (error) {
// error.message -- human-readable message
// For API errors thrown by @billing-io/sdk you can also inspect:
// error.type -- "invalid_request" | "authentication_error" | ...
// error.code -- machine-readable code like "api_key_invalid"
// error.statusCode -- HTTP status code
}
`Mutation hooks (
) both set error on the return value
and re-throw so you can try/catch in your handler.Re-exported types
For convenience, key types from
@billing-io/sdk are re-exported:`ts
import type {
Checkout,
CheckoutStatus,
CreateCheckoutRequest,
Chain,
Token,
EventType,
} from "@billing-io/react";
`API reference
| Hook | Type | Description |
| --------------------- | -------- | ------------------------------------ |
|
| Client | Raw BillingIO client from context |
| useCreateCheckout() | Mutation | Create a new checkout |
| useCheckoutStatus() | Polling | Poll checkout status in real time |
| useCheckouts() | Query | Paginated checkout list |
| useWebhookEndpoints() | Query | Paginated webhook endpoint list |
| useEvents()` | Query | Paginated event list |MIT