BigCommerce

Frontend Customer

useCustomerState

The useCustomerState hook can be used to get the current state of the customer.

import { useCustomerState } from 'frontend-customer'

const state: {
  id: string | null
  firstName: string | null
  lastName: string | null
  email: string | null
  phone: string | null
  company: string | null
  notes: string | null
  customerGroupId: number | null
  addressCount: number | null
  addresses: BigCommerceSdkOrderAddress[] | null
  taxExemptCategory: string | null
  attributeCount: number | null
  storeCredit:
    | {
        value: number
        currencyCode: string
      }[]
    | null
  isLoggedIn: boolean // Does the current user authorized
  status: 'initial' | 'loading' | 'loaded' | 'error' // Status of loading user's data
} = useCustomerState()

interface BigCommerceSdkOrder {
  id: number
  dateModified: string
  dateShipped: string
  cartId: string
  status: string
  subtotalTax: string
  shippingCostTax: string
  shippingCostTaxClassId: number
  handlingCostTax: string
  handlingCostTaxClassId: number
  wrappingCostTax: string
  wrappingCostTaxClassId: number
  paymentStatus: string
  storeCreditAmount: string
  giftCertificateAmount: string
  currencyId: string
  currencyCode: string
  currencyExchangeRate: string
  defaultCurrencyId: number
  couponDiscount: string
  shippingAddressCount: number
  isEmailOptIn: boolean
  orderSource: string
  coupons: BigCommerceSdkOrderCoupon[]
  products: BigCommerceSdkOrderProduct[]
  shippingAddresses: BigCommerceSdkOrderAddress[]
  statusId: number
  baseHandlingCost: string
  baseShippingCost: string
  baseWrappingCost: string | number
  billingAddress: BigCommerceSdkOrderAddress
  channelId: number
  customerId: number
  customerMessage: string
  dateCreated: string
  defaultCurrencyCode: string
  discountAmount: string
  ebayOrderId: string
  externalId: string | null
  externalSource: string | null
  geoIpCountry: string
  geoIpCountryIso2: string
  handlingCostExTax: string
  handlingCostIncTax: string
  ipAddress: string
  isDeleted: boolean
  itemsShipped: number
  itemsTotal: number
  orderIsDigital: boolean
  paymentMethod: string
  paymentProviderId: string | number
  refundedAmount: string
  shippingCostExTax: string
  shippingCostIncTax: string
  staffNotes: string
  subtotalExTax: string
  subtotalIncTax: string
  taxProviderId: string
  totalExTax: string
  totalIncTax: string
  wrappingCostExTax: string
  wrappingCostIncTax: string
  messages?: BigCommerceSdkOrderMessage[]
}

interface BigCommerceSdkOrderCoupon {
  id: number
  couponId: number
  orderId: number
  code: string | null
  amount: string | number
  type: number
  discount: number
}

interface BigCommerceSdkOrderAddress {
  firstName: string
  lastName: string
  company: string
  street1: string
  street2: string
  city: string
  state: string
  zip: number
  country: string
  countryIso2: string
  phone: number
  email: string
}

interface BigCommerceSdkOrderProduct {
  id: number
  orderId: number
  productId: number
  orderAddressId: number
  name: string
  sku: string
  type: string
  basePrice: string
  priceExTax: string
  priceIncTax: string
  priceTax: string
  baseTotal: string
  totalExTax: string
  totalIncTax: string
  totalTax: string
  quantity: number
  baseCostPrice: string
  costPriceIncTax: string
  costPriceExTax: string
  costPriceTax: string
  weight: number | string
  isRefunded: boolean
  refundedAmount: string
  returnId: number
  wrappingCost: string | number
  wrappingCostExTax: string
  wrappingCostIncTax: string
  wrappingCostTax: string
  wrappingMessage: string
  quantityShipped: number
  eventName: string | null
  eventDate: string | null
  fixedShippingCost: string
  ebayItemId: string
  ebayTransactionId: string
  optionSetId: number | null
  parentOrderProductId: number | null
  isBundledProduct: boolean
  binPickingNumber: string
  appliedDiscounts: {
    id: string
    amount: string
    name: string
    code: string | null
    target: string
  }[]
  productOptions: {
    id: number
    option_id: number
    order_product_id: number
    product_option_id: number
    display_name: string
    display_value: string
    value: string
    type: string
    name: string
    display_style: string
    display_name_customer: string
    display_name_merchant: string
    display_value_customer: string
    display_value_merchant: string
  }[]
  externalId: string | null
  upc: string
  variantId: number
  nameCustomer: string
  nameMerchant: string
}

interface BigCommerceSdkOrderMessage {
  id: number
  orderId: number
  staffId: number
  customerId: number
  type: string
  subject: string
  message: string
  status: string
  isFlagged: boolean
  dateCreated: string
}

interface BigCommerceSdkAddress {
  id: string
  firstName: string
  lastName: string
  company?: string
  address1: string
  address2?: string
  city: string
  state: string
  postalCode: string
  countryCode: string
  phone?: string
  addressType?: string
  country?: string
}

useCustomerActions

Customer actions SDK based on BigCommerce Management API.

import { useCustomerActions } from 'frontend-customer'

register

/**
 * Register user
 *
 * Customer = {
 *   email: string
 *   password: string
 *   firstName: string
 *   lastName: string
 *   address1: string
 *   city: string
 *   countryCode: string
 *   state: string
 *   postalCode: string
 *   company?: string
 *   phone?: string
 *   address2? string
 *   forceResetPassword: boolean
 * }
 *
 * register: (customer: Customer) => Promise<{ customer: Customer } | { errors: CustomerUserError[] }>
 */
const { register } = useCustomerActions()

await register({
  email: '[email protected]',
  password: 'password123',
  firstName: 'John',
  lastName: 'Lennon',
  address1: '3698  Single Street',
  city: 'Charlestown',
  countryCode: 'US',
  state: 'Charlestown',
  postalCode: '02129',
  company: '', // optional
  phone: '', // optional
  address2: '', // optional
  forceResetPassword: false, // optional
})

login

/**
 * Authorize customer
 *
 * login: ({ email: string; password: string }) => Promise<{ customer: Customer } | { errors: CustomerUserError[] }>
 */
const { login } = useCustomerActions()

await login({
  email: '[email protected]',
  password: 'password123',
})

logout

/**
 * Logout customer
 *
 * logout: () => Promise<{ errors?: UserError[] }>
 */
const { logout } = useCustomerActions()

await logout()

recoverPassword

/**
 * Send email to customer with password recovery link.
 * The link url will open a page `/login?action=change_password` where should be used resetPassword action
 *
 * recoverPassword: (email: string) => Promise
 */
const { recoverPassword } = useCustomerActions()

await recoverPassword('[email protected]')

/** 
 * It's a good practice to show a message after
 * calling `recoverPassword`. See example below
 * of how to show such message using a third party library
 * like `sweetalert2`
 */
await recoverPassword('[email protected]')
  .finally(() => {
    Swal.fire({
      icon: 'info',
      text: `
        If the entered email address is associated with this store, you will receive a password reset email.
        If you don\'t receive this e-mail, please check your junk mail folder or contact us for further assistance.
      `,
    }).then(() => push('/'))
  })

resetPassword

/**
 * Reset customer's password
 * Should be placed in `/account/reset` page.
 * The page will be opened from the recovery link on url `/account/reset/.../...`
 * Reset url: 'https://mystore.com/login.php?action=change_password&c=351940&t=e929de5c617c08f161ad31a6a5e2e197'
 * 
 * resetPassword: ({ resetUrl: string; password: string }) => Promise<{ customer?: Customer } | { errors: CustomerUserError[] }>
 */
const { resetPassword } = useCustomerActions()

await resetPassword({
  resetUrl: '',
  password: 'password1234',
})

updateCustomer

/**
 * Update BigCommerce customer's information.
 *
 * Customer = {
 *   firstName?: string
 *   lastName?: string
 *   email?: string
 *   phone?: string
 *   company?: string
 *   newPassword?: string
 * }
 * 
 * updateCustomer: (customer: Customer) => Promise<{ customer?: Customer } | { errors: CustomerUserError[] }>
 */
const { updateCustomer } = useCustomerActions()

await updateCustomer({
  firstName: 'John', // optional
  lastName: 'Lennon', // optional
  email: '[email protected]', // optional
  phone: '', // optional
  company: '', // optional
  newPassword: '', // optional
})

getAllAddresses

/**
 * Gets all addresses from an authenticated BigCommerce customer.
 *
 * getAllAddresses: () => Promise<Customer['addresses'] | null>
 */
const { getAllAddresses } = useCustomerActions()

await getAllAddresses()

createAddress

/**
 * Creates an address for a customer.
 * Responds with the created customer address.
 *
 * Address = {
 *   firstName: string
 *   lastName: string
 *   company: string
 *   address1: string
 *   city: string
 *   state: string
 *   postalCode: string
 *   countryCode: string
 *   address2?: string
 *   phone?: string
 *   addressType?: string
 *   country?: string
 *   formFields?: BigCommerceApiAddress['form_fields']
 * }
 *
 * updateAddress: ({id: number, address: Partial<Omit<BigCommerceSdkAddress, 'id'>> }) => Promise<BigCommerceSdkCreateAddressPayload>
 */
const { createAddress } = useCustomerActions()

await createAddress({
  firstName: 'John',
  lastName: 'Lennon'
  company: 'Music',
  address1: '2986  Pearlman Avenue',
  city: 'Framingham',
  state: 'MA',
  postalCode: '01701',
  countryCode: 'US',
  address2: '',  // optional
  phone: '',  // optional
  addressType: 'residential',  // optional
  country: 'United States',  // optional
  formFields: [],  // optional
})

updateAddress

/**
 * Updates an existing customer Address.
 * Responds with the updated customer address.
 *
 * updateAddress: ({id: number, address: Partial<Omit<BigCommerceSdkAddress, 'id'>> }) => Promise<BigCommerceSdkUpdateAddressPayload>
 */
const { updateAddress } = useCustomerActions()

await updateAddress({
  id: 1234,
  address: {
    firstName: 'John', // optional
    lastName: 'Lennon' // optional
    company: 'Music', // optional
    address1: '2986  Pearlman Avenue', // optional
    city: 'Framingham', // optional
    state: 'MA', // optional
    postalCode: '01701', // optional
    countryCode: 'US', // optional
    address2: '',  // optional
    phone: '',  // optional
    addressType: 'residential',  // optional
    country: 'United States',  // optional
    formFields: [],  // optional
  }
})

deleteAddress

/**
 * Deletes an existing customer Address.
 * Responds with the deleted customer address id.
 *
 * deleteAddress: (id: number) => Promise<BigCommerceSdkDeleteAddressPayload>
 */
const { deleteAddress } = useCustomerActions()

await deleteAddress(1234)

getAllOrders

/**
 * Gets all orders from the authenticated customer.
 * Responds with a list of customer orders.
 *
 * getAllOrders: () => Promise<BigCommerceSdkGetAllOrdersPayload>
 */
const { getAllOrders } = useCustomerActions()

await getAllOrders()

getOrder

/**
 * Gets an order given an id from a BigCommerce customer.
 * Respond with the requested customer order.
 *
 * getOrder: (id: string | number) => Promise<BigCommerceSdkGetOrderPayload>
 */
const { getOrder } = useCustomerActions()

await getOrder(1234)

getOrderMessages

/**
 * Get customer's order messages given an order id.
 * Respond with a list of order messages from the customer.
 *
 * getOrderMessages: (id: number) => Promise<BigCommerceSdkCreateOrderMessagePayload>
 */
const { getOrderMessages } = useCustomerActions()

await getOrderMessages(1234)

createOrderMessage

/**
 * Creates an order message given an order id.
 * Respond with a list of order messages from the customer.
 *
 * createOrderMessage: ({ oderId: number, subject: string, message: string }) => Promise<BigCommerceSdkCreateOrderMessagePayload>
 */
const { createOrderMessage } = useCustomerActions()

await createOrderMessage({
  orderId: 1,
  subject: 'test',
  message: 'Hello!',
})