@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

``bash
npm i @aftership/shop-now
`

🤹‍♀️ Getting Started

$3

Here is an example to use

`typescript
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.

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

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

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

// Regular flow logic here
return ;
}
`

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.

`typescript
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

`typescript
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 👇

`typescript
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;

`typescript
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

`typescript
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

`typescript
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.

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

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

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

`typescript
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

`typescript
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

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

goBack?.();
`

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

| Step | Feature | Key Methods/Properties | Description |
| ---- | ------------------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| 1 | Flow Detection | isFromEFA from useReturnsShopNow | Determines if current flow is EFA process |
| 2 | Cart Initialization | initCart(lineItems) | Initializes cart and calculates prices |
| 3 | Cart Operations | updateCart(lineItems)
addCart(lineItem)
removeFromCart(lineItem) | Methods for managing cart items |
| 4 | Navigation Methods | checkout()
buyNow()
goBack() | Methods to return to returns page |
| 5 | Price Access | price from shopContext | Access to amount and currency information |

#### 📦 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

`typescript
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',
});

;
`

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.

`typescript
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.

`typescript
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

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

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

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