@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.

✨ 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.

📦 Install

npm i @aftership/shop-now

🤹‍♀️ Usage

React

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

Example

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

  const {
    initCart
    updateCart,
    addToCart,
    removeFromCart,
    checkout,
    buyNow,
    shopContext,
    error,
  } = useReturnsShopNow({platform: 'shopify'});

  useQuery(
    'get-cart',
    async () => {
      return fetchCart();
    },
    {
      onSuccess: (data) => {
        updateCart(
          data.map((item) => ({
            quantity: data.quantity,
            external_product_id: data.external_product_id,
            external_variant_id: data.external_variant_id,
          }))
        );
      },
    }
  );

  const handleAddToCart = (lineItem) => {
    addToCart?.({
      quantity: lineItem.quantity,
      external_product_id: lineItem.external_product_id,
      external_variant_id: lineItem.external_variant_id,
    });
  };

  const handleRemoveFromCart = (lineItem) => {
    removeFromCart?.({
      quantity: lineItem.quantity,
      external_product_id: lineItem.external_product_id,
      external_variant_id: lineItem.external_variant_id,
    });
  };

Type

interface LineItem {
  external_product_id: string;
  external_variant_id: string;
  quantity: number;
}

type LineItems = LineItem[];

type PlatformContext = Partial<{
  shopInfo: {
    currency: string;
    language: string;
    rc_origin: string;
  };
  price: {amount: number; currency: string};
  style: {
    background: string;
    font: string;
  };
}>;

export type ReturnsError = {
  baseUrl: string;
  input: string;
  requertUrl: string;
  method?: string;
  message?: string;
  returnsAPIException: boolean;
} & Record<string, any>;

enum EventAction {
  GET_CART_TOTAL = 'getCartTotal',
  ADD_TO_CART = 'addToCart',
  UPDATE_TO_CART = 'updateToCart',
  REMOVE_FROM_CART = 'removeFromCart',
  CHECKOUT = 'checkout',
  BUY_NOW = 'buyNow',
  ON_CONTEXT_CHANGE = 'onContextChange',
  ERROR = 'error',
}

import {LineItem} from '@aftership/shop-now/dist/core/types/cart';
import {EventAction} from '@aftership/shop-now/dist/core/constant';
import {ReturnsError} from '@aftership/shop-now/dist/core/utils/CustomError';
import {PlatformContext} from '@aftership/shop-now/dist/core/types/platform';

API

initCart

initCart is used to initialize the shopping cart. When users first enter the page to perform an "EFA" (exchange for anything), they need to call "initCart" to save the shopping cart data. Similar to updateCart it can overwrite the shopping cart data by passing an array as a parameter.

initCart(lineItems)

updateCart

updateCart allows you to overwrite the shopping cart data by passing an array as a parameter.

updateCart(lineItems)

addToCart

addToCart is used to add an individual item to the shopping cart.

addToCart(lineItem)

removeFromCart

removeFromCart is used to remove a single item from the shopping cart.

removeFromCart(lineItem)

getCart

getCart is used to retrieve the data saved in the shopping cart model.

getCart() -> lineItems

checkout

The checkout action carries the information of the items saved in the shopping cart and redirects you to the store's returns page for the checkout process.

buyNow

For the buyNow action, you would need to pass the information of the current item to overwrite the shopping cart's item information. Then, you will be redirected to the store's returns page for the checkout process.

goBack

The goBack action will take you back to the returns page.

initTranslation

The initTranslation function initializes the multilingual configuration set in the returns page.

getCreditTranslationText

After initializing the multilingual settings using initTranslation, you can use the getCreditTranslationText method. By passing in the parameters amount and currency, it will return the corresponding text based on the configured language settings.

getGoBackTranslationText

The "getGoBackTranslationText" function returns the corresponding translation text for the "goback" action in the returns page.

getError

The getError function retrieves the error message.

getContext

The getContext function retrieves the context information.

setOnEventChangeCallback

The setOnEventChangeCallback function is used to set callbacks for events such as adding items to the shopping cart, context changes, or error events.

const onEventChangeCallback = (eventName: PlatformEventName, context?: PlatformContext) => {
      if (eventName === EventAction.ON_CONTEXT_CHANGE) {
      }
      if (eventName === EventAction.ERROR) {
      }
      if (eventName === EventAction.GET_CART_TOTAL) {
      }
      if (eventName === EventAction.ADD_TO_CART) {
      }
      if (eventName === EventAction.UPDATE_TO_CART) {
      }
      if (eventName === EventAction.BUY_NOW) {
      }
      if (eventName === EventAction.CHECKOUT) {
      }
    },

setOnEventChangeCallback(onEventChangeCallback)

React Component

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

// Here is an example of the default returns banner component:

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

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

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

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

note

1、If you use useReturnsShopNow will also provide a shopContext with its corresponding state and error. You don't need to worry about how to fetch the data or handle errors; it's ready to use out of the box. 2、Please refer to the PlatformContext mentioned above for the type of shopContext. Please refer to the ReturnsError mentioned above for the type of error.

shopContext

shopInfo

currency: The returns page carries the currency of the store. language: The returns page carries the language of the store. rc_origin: The returns page origin url

price amount & currency The calculated amount and currency for returns.

style The style of the returns admin banner.

error

returnsAPIException indicates whether it is an error related to the core returns API business.

3、If you want to use multilingual support for returns, you can utilize the initialization method for multilingual within the useEffect hook.

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

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