Overview​

The checkout extension APIs cover core use cases including data processing, UI interactions, and analytics. With these APIs, you can rapidly build complex, custom checkout apps and streamline integrations.

Using the extension APIs​

The extension APIs are passed through the component's props object. For detailed guidance on each API, refer to its corresponding API reference.

Use cases​

The following examples show how to use the extension APIs in JavaScript.

Global React object​

You can access the React object globally using properties like React.useState or React.useEffect.

Access properties​

You can access specific properties via props.{feature}. In the following example, the current shop information object is retrieved using props.shop, and then the shop's name is rendered as shop.name using the Text component.

render('Checkout::Dynamic::Render', (props) => {
  const { shop } = props;
  
  return <Text>Shop name: {shop.name}</Text>
});

Render translation strings​

Multilingual translations are stored in the extension development directory under locales/{lang}.json, where lang represents the corresponding language. Files ending with {lang}.default.json designate lang as the default language. For example, en.default.json designates English as the default language.

During the extension runtime, the user's preferred language will be prioritized. If the preferred language is unavailable, the default language will be used instead. You can use props.i18n.translate(key) to render the multilingual text corresponding to the specified key.

/* Refer to the following locales/en.default.json file to obtain the translation keys and values for this example */
render('Checkout::Dynamic::Render', (props) => {
  const { i18n } = props;
  return <Text>{i18n.translate("welcome", { name: "tony" })}</Text>;
});

{
  "welcome": "Welcome to our store {{name}}!"
}

Access checkout editor settings​

For example, if you define the checkout settings that merchants can edit in the checkout editor as follows:

type = "checkout_ui_customizer"
name = "my-checkout-customizer"
extension_points = [
  'Checkout::Dynamic::Render'
]
[settings]
  [[settings.fields]]
  key = "banner_title"
  type = "single_line_text_field"
  name = "Banner title"
  description = "Enter a title for the banner."
    [[settings.fields.validations]]
    name = "min"
    value = "5"
    [[settings.fields.validations]]
    name = "max"
    value = "20"

You can retrieve the key value set by the merchant through props.settings.{key} in the extension.

render('Checkout::Dynamic::Render', (props) => {
  const { settings } = props;
  
  return <Banner title={settings.banner_title}></Banner>;
});

Call hooks​

Retrieve the complete API​

You can obtain the complete API within the extension using the useApi hook, which is suitable for deeply nested components.

render('Checkout::Dynamic::Render', () => {
  const { settings } = useApi();
  
  return <Banner title={settings.banner_title}></Banner>;
});

Retrieve the line item information​

You can use the useCheckoutLineTarget hook within the extension to access the current line item information, which is suitable for deeply nested components.

render('Checkout::CheckoutLineDetails::RenderAfter', () => {
  const { variantId } = useCheckoutLineTarget();
  
  return <Banner title={variantId}></Banner>;
});

Block the checkout process and show an error​

Use Interceptor to intercept and prevent the buyer from checking out, and display an error message on the extension UI.

In the following example, when the buyer attempts to place an order, the callback method within interceptor.validate is invoked for validation. During the validation process, if the total amount is greater than 5000, the order can proceed. Otherwise, the validation fails, and The total amount must be greater than 5000 is displayed.

render(
  'Checkout::Dynamic::Render',
  (props) => {
    const { interceptor, cost } = props;
    const [isValid, setIsValid] = React.useState(false);
    React.useEffect(() => {
      const interceptorHandle = interceptor.validate(() => {
        const success = cost.totalAmount > 5000;
        setIsValid(success);
        return { success };
      });
      return () => {
        interceptorHandle.unsubscribe();
      };
    }, []);
    return isValid ? null : <Banner>The total amount must be greater than 5000</Banner>;
  }
)