Skip to main content

useEasy Hook

The useEasy hook is the primary way to access Easy SDK functionality in your React components. It provides methods for customer management, payment processing, product management, and more.

Basic Usage​

import { useEasy } from "@easylabs/react";

function MyComponent() {
  const { checkout, createCustomer, createTransfer } = useEasy();

  // Use the methods
}
Requirements

The useEasy hook must be used within a component that is wrapped by EasyProvider.

Available Methods​

The hook returns an object with all Easy SDK methods:

Customer Management​

const {
  createCustomer,
  updateCustomer,
  getCustomer,
  getCustomers,
  getCustomerPaymentInstruments,
  getCustomerOrders,
} = useEasy();

Payment Instruments​

const {
  tokenizePaymentInstrument,
  createPaymentInstrument,
  updatePaymentInstrument,
} = useEasy();

Transfers & Payments​

const { createTransfer, getTransfer, getTransfers, updateTransferTags } =
  useEasy();

Products & Pricing​

const {
  getProducts,
  getProduct,
  getProductWithPrice,
  getProductWithPrices,
  createProduct,
  updateProduct,
  archiveProduct,
  getProductPrices,
  getProductPrice,
  createProductPrice,
  updateProductPrice,
  archiveProductPrice,
} = useEasy();

Subscriptions​

const {
  getSubscriptions,
  getSubscription,
  createSubscription,
  cancelSubscription,
  getSubscriptionPlans,
  getSubscriptionPlan,
  createSubscriptionPlan,
  updateSubscriptionPlan,
} = useEasy();

Checkout​

const { checkout } = useEasy();
  • checkout - Complete checkout flow (recommended)

Example Usage​

Simple Payment​

import { useEasy, CardElement } from "@easylabs/react";
import { useRef, useState } from "react";

function PaymentForm() {
  const { checkout } = useEasy();
  const cardRef = useRef(null);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    setLoading(true);

    try {
      const result = await checkout({
        customer_creation: true,
        customer_details: {
          first_name: "John",
          last_name: "Doe",
          email: "john@example.com",
        },
        source: {
          type: "PAYMENT_CARD",
          cardElement: cardRef,
          name: "Primary Card",
        },
        line_items: [{ price_id: "price_123", quantity: 1 }],
      });

      console.log("Success:", result);
    } catch (error) {
      console.error("Error:", error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement ref={cardRef} />
      <button type="submit" disabled={loading}>
        {loading ? "Processing..." : "Pay Now"}
      </button>
    </form>
  );
}

Customer Management​

import { useEasy } from "@easylabs/react";
import { useState } from "react";

function CustomerDashboard() {
  const { getCustomer, getCustomerOrders } = useEasy();
  const [customer, setCustomer] = useState(null);
  const [orders, setOrders] = useState([]);

  const loadCustomer = async (customerId) => {
    const customerData = await getCustomer(customerId);
    setCustomer(customerData.data);

    const orderData = await getCustomerOrders(customerId);
    setOrders(orderData.data);
  };

  return (
    <div>
      {customer && (
        <>
          <h2>
            {customer.first_name} {customer.last_name}
          </h2>
          <p>Email: {customer.email}</p>
          <h3>Orders</h3>
          <ul>
            {orders.map((order) => (
              <li key={order.id}>{order.order_number}</li>
            ))}
          </ul>
        </>
      )}
    </div>
  );
}

Type Safety​

The hook is fully typed with TypeScript:

import { useEasy } from "@easylabs/react";
import type {
  CreateCustomer,
  ApiResponse,
  CustomerData,
} from "@easylabs/react";

function MyComponent() {
  const { createCustomer } = useEasy();

  const handleCreate = async () => {
    const customerData: CreateCustomer = {
      first_name: "John",
      last_name: "Doe",
      email: "john@example.com",
    };

    const result: ApiResponse<CustomerData> =
      await createCustomer(customerData);
  };
}

Error Handling​

All methods can throw errors. Always wrap calls in try-catch blocks:

const { checkout } = useEasy();

try {
  const result = await checkout({
    /* ... */
  });
} catch (error) {
  console.error("Checkout failed:", error.message);
  // Handle error (show user message, etc.)
}

Common Patterns​

With React Query​

import { useEasy } from "@easylabs/react";
import { useQuery } from "@tanstack/react-query";

function CustomerList() {
  const { getCustomers } = useEasy();

  const { data, isLoading } = useQuery({
    queryKey: ["customers"],
    queryFn: () => getCustomers({ limit: 20 }),
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <ul>
      {data.data.map((customer) => (
        <li key={customer.id}>{customer.email}</li>
      ))}
    </ul>
  );
}

With Form Libraries​

import { useEasy } from "@easylabs/react";
import { useForm } from "react-hook-form";

function CustomerForm() {
  const { createCustomer } = useEasy();
  const { register, handleSubmit } = useForm();

  const onSubmit = async (data) => {
    await createCustomer({
      first_name: data.firstName,
      last_name: data.lastName,
      email: data.email,
    });
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register("firstName")} />
      <input {...register("lastName")} />
      <input {...register("email")} />
      <button type="submit">Create</button>
    </form>
  );
}

Next Steps​