Customer Management API

The Customer Management API allows you to create, retrieve, update, and delete customer records in your React Native application.

Methods

getCustomers

Retrieve a list of all customers with optional pagination and filtering.

const { getCustomers } = useEasy();

// Get all customers
const allCustomers = await getCustomers({
  limit: 50,
  offset: 0,
});

// Get specific customers by ID
const result = await getCustomers({
  ids: ["cust_123", "cust_456"],
});

Parameters

• params (optional)
  • ids (string[], optional): Filter by specific customer IDs
  • limit (number): Maximum number of customers to return (default: 10, max: 100)
  • offset (number): Number of customers to skip for pagination

Returns

ApiResponse<CustomerData[]>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { FlatList, Text, View } from "react-native";

function CustomerList() {
  const { getCustomers } = useEasy();
  const [customers, setCustomers] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchCustomers = async () => {
      try {
        const result = await getCustomers({ limit: 50 });
        setCustomers(result.data);
      } catch (error) {
        console.error("Failed to fetch customers:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchCustomers();
  }, [getCustomers]);

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

  return (
    <FlatList
      data={customers}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View>
          <Text>
            {item.first_name} {item.last_name}
          </Text>
          <Text>{item.email}</Text>
        </View>
      )}
    />
  );
}

---

getCustomer

Retrieve a specific customer by their ID.

const { getCustomer } = useEasy();

const result = await getCustomer("cust_123");

Parameters

• customerId (string, required): The ID of the customer to retrieve

Returns

ApiResponse<CustomerData>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { View, Text, ActivityIndicator } from "react-native";

function CustomerProfile({ customerId }) {
  const { getCustomer } = useEasy();
  const [customer, setCustomer] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchCustomer = async () => {
      try {
        const result = await getCustomer(customerId);
        setCustomer(result.data);
      } catch (error) {
        console.error("Failed to fetch customer:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchCustomer();
  }, [customerId, getCustomer]);

  if (loading) return <ActivityIndicator />;
  if (!customer) return <Text>Customer not found</Text>;

  return (
    <View>
      <Text>
        {customer.first_name} {customer.last_name}
      </Text>
      <Text>{customer.email}</Text>
      {customer.phone && <Text>{customer.phone}</Text>}
    </View>
  );
}

---

createCustomer

Create a new customer record.

const { createCustomer } = useEasy();

const result = await createCustomer({
  first_name: "Jane",
  last_name: "Smith",
  email: "jane@example.com",
  phone: "+1234567890",
  personal_address: {
    line1: "456 Oak St",
    city: "Another City",
    state: "NY",
    postal_code: "67890",
    country: "US",
  },
  tags: {
    source: "mobile-app",
    signup_date: "2024-01-15",
  },
});

Parameters

interface CreateCustomer {
  first_name: string;
  last_name: string;
  email: string;
  phone?: string;
  personal_address?: Address;
  tags?: Record<string, unknown>;
}

interface Address {
  line1: string;
  line2?: string;
  city: string;
  state: string; // 2-letter state code
  postal_code: string;
  country: string; // 2-letter country code
}

Returns

ApiResponse<CustomerData>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState } from "react";
import { View, TextInput, Button, Alert } from "react-native";

function CreateCustomerForm() {
  const { createCustomer } = useEasy();
  const [firstName, setFirstName] = useState("");
  const [lastName, setLastName] = useState("");
  const [email, setEmail] = useState("");
  const [loading, setLoading] = useState(false);

  const handleSubmit = async () => {
    if (!firstName || !lastName || !email) {
      Alert.alert("Error", "Please fill in all required fields");
      return;
    }

    setLoading(true);

    try {
      const result = await createCustomer({
        first_name: firstName,
        last_name: lastName,
        email: email,
      });

      Alert.alert("Success", `Customer created: ${result.data.id}`);

      // Reset form
      setFirstName("");
      setLastName("");
      setEmail("");
    } catch (error) {
      Alert.alert("Error", error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View>
      <TextInput
        placeholder="First Name"
        value={firstName}
        onChangeText={setFirstName}
      />
      <TextInput
        placeholder="Last Name"
        value={lastName}
        onChangeText={setLastName}
      />
      <TextInput
        placeholder="Email"
        value={email}
        onChangeText={setEmail}
        keyboardType="email-address"
      />
      <Button
        title={loading ? "Creating..." : "Create Customer"}
        onPress={handleSubmit}
        disabled={loading}
      />
    </View>
  );
}

---

updateCustomer

Update an existing customer's information.

const { updateCustomer } = useEasy();

const result = await updateCustomer("cust_123", {
  phone: "+0987654321",
  tags: {
    ...customer.tags,
    updated_at: new Date().toISOString(),
  },
});

Parameters

• customerId (string, required): The ID of the customer to update
• updates (Partial<CreateCustomer>, required): Fields to update

Returns

ApiResponse<CustomerData>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState } from "react";
import { View, TextInput, Button, Alert } from "react-native";

function UpdateCustomerPhone({ customerId, currentPhone }) {
  const { updateCustomer } = useEasy();
  const [phone, setPhone] = useState(currentPhone || "");
  const [loading, setLoading] = useState(false);

  const handleUpdate = async () => {
    setLoading(true);

    try {
      await updateCustomer(customerId, { phone });
      Alert.alert("Success", "Phone number updated");
    } catch (error) {
      Alert.alert("Error", error.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <View>
      <TextInput
        placeholder="Phone Number"
        value={phone}
        onChangeText={setPhone}
        keyboardType="phone-pad"
      />
      <Button
        title={loading ? "Updating..." : "Update Phone"}
        onPress={handleUpdate}
        disabled={loading}
      />
    </View>
  );
}

---

getCustomerPaymentInstruments

Retrieve all payment instruments for a specific customer.

const { getCustomerPaymentInstruments } = useEasy();

const result = await getCustomerPaymentInstruments("cust_123");

Parameters

• customerId (string, required): The ID of the customer

Returns

ApiResponse<PaymentInstrumentData[]>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { FlatList, View, Text } from "react-native";

function CustomerPaymentMethods({ customerId }) {
  const { getCustomerPaymentInstruments } = useEasy();
  const [paymentMethods, setPaymentMethods] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchPaymentMethods = async () => {
      try {
        const result = await getCustomerPaymentInstruments(customerId);
        setPaymentMethods(result.data);
      } catch (error) {
        console.error("Failed to fetch payment methods:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchPaymentMethods();
  }, [customerId]);

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

  return (
    <FlatList
      data={paymentMethods}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View>
          <Text>{item.name || "Payment Method"}</Text>
          <Text>
            {item.type === "PAYMENT_CARD"
              ? `Card ending in ${item.last_four}`
              : `Bank account ending in ${item.last_four}`}
          </Text>
        </View>
      )}
    />
  );
}

---

getCustomerOrders

Retrieve all orders for a specific customer.

const { getCustomerOrders } = useEasy();

const result = await getCustomerOrders("cust_123", {
  limit: 20,
  offset: 0,
});

Parameters

• customerId (string, required): The ID of the customer
• params (optional)
  • limit (number): Maximum number of orders to return
  • offset (number): Number of orders to skip for pagination

Returns

ApiResponse<OrderData[]>;

Example

import { useEasy } from "@easylabs/react-native";
import { useState, useEffect } from "react";
import { FlatList, View, Text } from "react-native";

function CustomerOrderHistory({ customerId }) {
  const { getCustomerOrders } = useEasy();
  const [orders, setOrders] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchOrders = async () => {
      try {
        const result = await getCustomerOrders(customerId, { limit: 50 });
        setOrders(result.data);
      } catch (error) {
        console.error("Failed to fetch orders:", error);
      } finally {
        setLoading(false);
      }
    };

    fetchOrders();
  }, [customerId]);

  if (loading) return <Text>Loading orders...</Text>;
  if (orders.length === 0) return <Text>No orders found</Text>;

  return (
    <FlatList
      data={orders}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View>
          <Text>Order #{item.order_number}</Text>
          <Text>${(item.amount / 100).toFixed(2)}</Text>
          <Text>{new Date(item.created_at).toLocaleDateString()}</Text>
        </View>
      )}
    />
  );
}

Type Definitions

CustomerData

interface CustomerData {
  id: string;
  first_name: string;
  last_name: string;
  email: string;
  phone?: string;
  personal_address?: Address;
  tags?: Record<string, unknown>;
  created_at: string;
  updated_at: string;
}

Best Practices

1. Error Handling

Always wrap customer operations in try-catch blocks:

try {
  const result = await createCustomer(customerData);
  Alert.alert("Success", "Customer created");
} catch (error) {
  Alert.alert("Error", error.message || "Failed to create customer");
}

2. Loading States

Show loading indicators during async operations:

const [loading, setLoading] = useState(false);

const handleCreate = async () => {
  setLoading(true);
  try {
    await createCustomer(data);
  } finally {
    setLoading(false);
  }
};

3. Validation

Validate customer data before submission:

const validateCustomer = (data) => {
  if (!data.first_name?.trim()) {
    throw new Error("First name is required");
  }
  if (!data.email?.includes("@")) {
    throw new Error("Valid email is required");
  }
  return true;
};

Next Steps

• Process Payments with Checkout
• View Customer Management Example
• Learn about the useEasy Hook