@aftership/shop-now

Returns shop now library

🚀 Pre requirement

Exchange for other items SDK requires Premium or above plan. Log in to AfterShip Returns Admin to upgrade your subscription.

📦 Background

The returns efa on store flow will jump from the return page to the store with related parameters in the URL. The shop-now SDK will handle the parameters carried in the store URL and provide related capabilities, allowing you to easily complete the returns efa flow in your self-built store

✨ Features

• 🏄🏼‍♂️ Easy to learn and use.
• ⚛️ Supports React.
• 🪄 Multiple custom APIs that support exchange for anything on store.
• 🎪 Support multiple e-commerce platforms, including Shopify, Bigcommerce, and Salesforce Commerce Cloud.
• 🎯 Written in TypeScript with predictable static types.
• 💦 Support SSR

📦 Install

npm i @aftership/shop-now

🤹‍♀️ Getting Started

React

Here is an example to use

import {useReturnsShopNow} from '@aftership/shop-now/react';

useReturnsShopNow is a collection of logical data, it doesn't include UI. You can implement the UI yourself or use the UI banner provided by the SDK

1、First step, determine if it's in the returns efa process.You can use isFromEFA from useReturnsShopNow to determine if it's in the efa process.

import {useReturnsShopNow} from '@aftership/shop-now/react';

function YourComponent() {
  const {isFromEFA} = useReturnsShopNow({
    platform: 'shopify',
  });

  if (isFromEFA) {
    // EFA process logic here
    return <EFAFlowComponent />;
  }

  // Regular flow logic here
  return <RegularFlowComponent />;
}

2、Second step, when confirmed it's an efa process, the new page needs to call the initCart method to calculate the current shopping cart item prices.

import {useEffect} from 'react';
const {initCart, isFromEFA, shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

const {isMounted, isLoading} = shopContext;

useEffect(() => {
  if (isFromEFA && isMounted) {
    initCart?.(lineItems as LineItems);
  }
}, [isFromEFA, initCart, isMounted]);

We also provide the isLoading status of the calculation API and the isMounted status of the hook. You can perform initCart after the isMounted status is true. When you have special scenarios that require using initCart, you can use isMounted. In general, using updateCart is sufficient.

shopContext contains some information you can use

export type PlatformContext = Partial<{
  shopInfo: {
    currency: string;
    // return page language
    language: string;
    // return page redirect url
    redirectUrl: string;
    // return page origin
    rc_origin: string;
    // return page navigate from path
    rc_navigate_from_path: string;
  };
  // price calculation
  price: {amount: number; currency: string};
  // returns admin page editor style
  style: {
    background: string;
    font: string;
  };
}> & {
  /**
   * fetch calculation api loading
   */
  isLoading: boolean;
  /**
   * EFA process hook loading status
   */
  isMounted: boolean;
};

Additionally, all line items should conform to the following format 👇

type LineItem = {
  external_product_id: string;
  external_variant_id: string;
  quantity: number;
};

type LineItems = LineItem[];

Once the price calculation is successful, you will get the price from shopContext.You can access the price object under shopContext to get the amount and currency. shopContext?.price;

interface Price {
  amount: number;
  currency: string;
}

3、Third step, when the shopping cart changes, you should call the updateCart method to update the cart, pass in lineItems. shopContext is a subscribed state, so when the items are calculated successfully, it will update automatically

const {updateCart} = useReturnsShopNow({
  platform: 'shopify',
});

updateCart?.(lineItems);

It is recommended to use updateCart to trigger calculations. When the cart changes, you can pass the cart data for calculation, which can effectively aggregate calculations.

In addition, I provide addToCart and removeFromCart methods based on individual item changes, allowing you to only pass in the current lineItem

const {addToCart, removeFromCart} = useReturnsShopNow({
  platform: 'shopify',
});

addToCart(lineItem);
removeFromCart(lineItem);

When you want to know the actual quantity and information of items stored inside the SDK, You can access the cart property in the shop context.

const {shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

const cart = shopContext?.cart ?? [];

3.1、Setting Discount Codes

If your store has shopify discount codes applied to the cart, you can set them using the setDiscountCodes method. This will ensure the discount codes are saved along with the return intention.

const {setDiscountCodes} = useReturnsShopNow({
  platform: 'shopify',
});

// Set discount codes (e.g., from Shopify cart.js discount_codes where applicable: true)
setDiscountCodes?.(['DISCOUNT10', 'SUMMER2024']);

4、Fourth step, you can call checkout, goBack, buyNow three methods to return to the returns page."

4.1、checkout When users click the shopping cart button in the shop to check out, you should call checkout, and it will automatically redirect to the return page

const {checkout} = useReturnsShopNow({
  platform: 'shopify',
});

checkout?.();

4.2、buyNow When users click the buy now button in the shop to check out, you should call buyNow, passing in the lineItem, and it will automatically redirect to the return page

const {buyNow} = useReturnsShopNow({
  platform: 'shopify',
});

buyNow?.(lineItem);

4.3、goBack When users click the go back button in the returns page, you should call goBack, and it will automatically redirect to the shop page

const {goBack} = useReturnsShopNow({
  platform: 'shopify',
});

goBack?.();

🎉 Congratulations, you are now familiar with the core process of the efa sdk

📦 In addition, some out-of-the-box capabilities are provided

If you want to use the default Returns UI banner for display, we have already packaged it as a React component for your use.

1、ReturnsShopNowBanner

import {ReturnsShopNowBanner} from '@aftership/shop-now/react';

export interface IBannerStyleConfig {
  background?: string;
  font?: string;
  opacity?: number;
}
interface IReturnsShopNowBannerProps {
  styleConfig: IBannerStyleConfig;
  creditText: string;
}

const {shopContext} = useReturnsShopNow({
  platform: 'shopify',
});

<ReturnsShopNowBanner styleConfig={shopContext?.style} creditText={} />;

You can call shopContext?.style to get the banner styles configured in returns admin, or you can override them yourself

2、Error Handling For error handling, the SDK provides an error field to let external code be aware of errors that occur within the SDK

The SDK will return errors from the calculation API, which can be categorized into session expiration and internal API errors. If the session has expired, you need to return to the return page and initiate the return process again. If there is an internal API error, please contact us.

Note: The maximum duration for a single return EFA on store process is 30 minutes. If it exceeds 30 minutes, the session will expire.

const {error} = useReturnsShopNow({
  platform: 'shopify',
});

const isSessionExpired = error.type === 'SESSION_EXPIRED';
const isApiError = error.type === 'API_ERROR';

console.log(error);

error is a state. If you want to clear the error, you can call the clearError method to clear it.

const {clearError} = useReturnsShopNow({
  platform: 'shopify',
});

3、Use returns credit translation If you want the credit text font to be consistent with returns admin, you can call getCreditTranslationText method after calling initTranslation, passing in amount and currency to get the credit text

const {shopContext, initTranslation, getCreditTranslationText} =
  useReturnsShopNow({
    platform: 'shopify',
  });

useEffect(() => {
  initTranslation?.();
}, [initTranslation]);

const creditText = useMemo(() => {
  return (
    getCreditTranslationText?.(
      shopContext?.price?.amount,
      shopContext?.price?.currency,
    ) ?? '--'
  );
}, [shopContext]);