Cart Instructions

Instructions used to create the checkout.

import {
  Banner,
  Button,
  useApplyDiscountCodeChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyDiscountCodeChange =
    useApplyDiscountCodeChange();
  const instructions = useInstructions();

  if (
    instructions.discounts.canUpdateDiscountCodes
  ) {
    return (
      <Button
        onPress={() =>
          applyDiscountCodeChange({
            type: 'addDiscountCode',
            code: 'FREE_SHIPPING',
          })
        }
      >
        Apply your loyalty discount
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty discounts are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.discounts
        .canUpdateDiscountCodes
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyDiscountCodeChange({
                type: 'addDiscountCode',
                code: 'FREE_SHIPPING',
              }),
          },
          'Apply your loyalty discount',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty discounts are unavailable',
        ),
      );
    }
  },
);

StandardApi

The base API object provided to `purchase` extension targets.

Docs_Standard_CartInstructionsApi

instructions

The cart instructions used to create the checkout and possibly limit extension capabilities. These instructions should be checked prior to performing any actions that may be affected by them. For example, if you intend to add a discount code via the `applyDiscountCodeChange` method, check `discounts.canUpdateDiscountCodes` to ensure it's supported in this checkout. > Caution: As of version `2024-07`, UI extension code must check for instructions before calling select APIs in case those APIs are not available. See the [update guide](/docs/api/checkout-ui-extensions/instructions-update) for more information.

CartInstructions

attributes

Cart instructions related to cart attributes.

delivery

Cart instructions related to delivery.

discounts

Cart instructions related to discounts.

lines

Cart instructions related to cart lines.

metafields

Cart instructions related to metafields.

notes

Cart instructions related to notes.

AttributesCartInstructions

canUpdateAttributes

Indicates whether or not cart attributes can be updated.

DeliveryCartInstructions

canSelectCustomAddress

Indicates whether a buyer can select a custom address. When true, this implies extensions can update the delivery address.

DiscountsCartInstructions

canUpdateDiscountCodes

Indicates whether or not discount codes can be updated.

CartLinesCartInstructions

canAddCartLine

Indicates whether or not new cart lines can be added.

canRemoveCartLine

Indicates whether or not cart lines can be removed.

canUpdateCartLine

Indicates whether or not cart lines can be updated.

MetafieldsCartInstructions

canDeleteCartMetafield

Indicates whether or not cart metafields can be deleted.

canSetCartMetafields

Indicates whether or not cart metafields can be added or updated.

NotesCartInstructions

canUpdateNote

Indicates whether or not notes can be updated.

useInstructions

Returns the cart instructions used to create the checkout and possibly limit extension capabilities.

UseInstructionsGeneratedType

Returns the cart instructions used to create the checkout and possibly limit extension capabilities.

Returns: CartInstructions

export function useInstructions< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): CartInstructions { return useSubscription(useApi<Target>().instructions); }

CartInstructions

attributes

Cart instructions related to cart attributes.

delivery

Cart instructions related to delivery.

discounts

Cart instructions related to discounts.

lines

Cart instructions related to cart lines.

metafields

Cart instructions related to metafields.

notes

Cart instructions related to notes.

AttributesCartInstructions

canUpdateAttributes

Indicates whether or not cart attributes can be updated.

DeliveryCartInstructions

canSelectCustomAddress

Indicates whether a buyer can select a custom address. When true, this implies extensions can update the delivery address.

DiscountsCartInstructions

canUpdateDiscountCodes

Indicates whether or not discount codes can be updated.

CartLinesCartInstructions

canAddCartLine

Indicates whether or not new cart lines can be added.

canRemoveCartLine

Indicates whether or not cart lines can be removed.

canUpdateCartLine

Indicates whether or not cart lines can be updated.

MetafieldsCartInstructions

canDeleteCartMetafield

Indicates whether or not cart metafields can be deleted.

canSetCartMetafields

Indicates whether or not cart metafields can be added or updated.

NotesCartInstructions

canUpdateNote

Indicates whether or not notes can be updated.

Related

• Targets
• Components
• Configuration
• Tutorials

Examples

Instructions used to create the checkout.

Check `instructions.attributes.canUpdateAttributes` before calling `applyAttributeChange()`.

import {
  Banner,
  Button,
  useApplyAttributeChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyAttributeChange =
    useApplyAttributeChange();
  const instructions = useInstructions();

  if (
    instructions.attributes.canUpdateAttributes
  ) {
    return (
      <Button
        onPress={() =>
          applyAttributeChange({
            type: 'updateAttribute',
            key: 'loyaltyPoints',
            value: '100',
          })
        }
      >
        Apply 100 loyalty points
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty points are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.attributes
        .canUpdateAttributes
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyAttributeChange({
                type: 'updateAttribute',
                key: 'loyaltyPoints',
                value: '100',
              }),
          },
          'Apply 100 loyalty points',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty points are unavailable',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyAttributeChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyAttributeChange =
    useApplyAttributeChange();
  const instructions = useInstructions();

  if (
    instructions.attributes.canUpdateAttributes
  ) {
    return (
      <Button
        onPress={() =>
          applyAttributeChange({
            type: 'updateAttribute',
            key: 'loyaltyPoints',
            value: '100',
          })
        }
      >
        Apply 100 loyalty points
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty points are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.attributes
        .canUpdateAttributes
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyAttributeChange({
                type: 'updateAttribute',
                key: 'loyaltyPoints',
                value: '100',
              }),
          },
          'Apply 100 loyalty points',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty points are unavailable',
        ),
      );
    }
  },
);

Check `instructions.delivery.canSelectCustomAddress` before calling `applyShippingAddressChange()`. When `true`, this instruction implies that extensions can change the shipping address.

import {
  Banner,
  Button,
  useApplyShippingAddressChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyShippingAddressChange =
    useApplyShippingAddressChange();
  const instructions = useInstructions();

  if (
    instructions.delivery.canSelectCustomAddress
  ) {
    return (
      <Button
        onPress={() =>
          applyShippingAddressChange({
            type: 'updateShippingAddress',
            address: {
              zip: '90201',
            },
          })
        }
      >
        Change your postal code
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Shipping address cannot be modified
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.delivery
        .canSelectCustomAddress
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyShippingAddressChange({
                type: 'updateShippingAddress',
                address: {
                  zip: '90201',
                },
              }),
          },
          'Change your postal code',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Shipping address cannot be modified',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyShippingAddressChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyShippingAddressChange =
    useApplyShippingAddressChange();
  const instructions = useInstructions();

  if (
    instructions.delivery.canSelectCustomAddress
  ) {
    return (
      <Button
        onPress={() =>
          applyShippingAddressChange({
            type: 'updateShippingAddress',
            address: {
              zip: '90201',
            },
          })
        }
      >
        Change your postal code
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Shipping address cannot be modified
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.delivery
        .canSelectCustomAddress
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyShippingAddressChange({
                type: 'updateShippingAddress',
                address: {
                  zip: '90201',
                },
              }),
          },
          'Change your postal code',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Shipping address cannot be modified',
        ),
      );
    }
  },
);

Check `instructions.discounts.canUpdateDiscountCodes` before calling `applyDiscountCodeChange()`.

import {
  Banner,
  Button,
  useApplyDiscountCodeChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyDiscountCodeChange =
    useApplyDiscountCodeChange();
  const instructions = useInstructions();

  if (
    instructions.discounts.canUpdateDiscountCodes
  ) {
    return (
      <Button
        onPress={() =>
          applyDiscountCodeChange({
            type: 'addDiscountCode',
            code: 'FREE_SHIPPING',
          })
        }
      >
        Apply your loyalty discount
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty discounts are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.discounts
        .canUpdateDiscountCodes
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyDiscountCodeChange({
                type: 'addDiscountCode',
                code: 'FREE_SHIPPING',
              }),
          },
          'Apply your loyalty discount',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty discounts are unavailable',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyDiscountCodeChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyDiscountCodeChange =
    useApplyDiscountCodeChange();
  const instructions = useInstructions();

  if (
    instructions.discounts.canUpdateDiscountCodes
  ) {
    return (
      <Button
        onPress={() =>
          applyDiscountCodeChange({
            type: 'addDiscountCode',
            code: 'FREE_SHIPPING',
          })
        }
      >
        Apply your loyalty discount
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty discounts are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.discounts
        .canUpdateDiscountCodes
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyDiscountCodeChange({
                type: 'addDiscountCode',
                code: 'FREE_SHIPPING',
              }),
          },
          'Apply your loyalty discount',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty discounts are unavailable',
        ),
      );
    }
  },
);

Check `instructions.lines.canAddCartLine` or `instructions.lines.canRemoveCartLine` or `instructions.lines.canUpdateCartLine` before calling `applyCartLinesChange()`.

import {
  Banner,
  Button,
  useApplyCartLinesChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyCartLinesChange =
    useApplyCartLinesChange();
  const instructions = useInstructions();

  if (instructions.lines.canAddCartLine) {
    return (
      <Button
        onPress={() =>
          applyCartLinesChange({
            type: 'addCartLine',
            merchandiseId:
              'gid://shopify/product/1234',
            quantity: 1,
          })
        }
      >
        Add a free gift to your order
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        The products in your cart cannot be
        modified
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.lines
        .canAddCartLine
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyCartLinesChange({
                type: 'addCartLine',
                merchandiseId:
                  'gid://shopify/product/1234',
                quantity: 1,
              }),
          },
          'Add a free gift to your order',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'The products in your cart cannot be modified',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyCartLinesChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyCartLinesChange =
    useApplyCartLinesChange();
  const instructions = useInstructions();

  if (instructions.lines.canAddCartLine) {
    return (
      <Button
        onPress={() =>
          applyCartLinesChange({
            type: 'addCartLine',
            merchandiseId:
              'gid://shopify/product/1234',
            quantity: 1,
          })
        }
      >
        Add a free gift to your order
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        The products in your cart cannot be
        modified
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.lines
        .canAddCartLine
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyCartLinesChange({
                type: 'addCartLine',
                merchandiseId:
                  'gid://shopify/product/1234',
                quantity: 1,
              }),
          },
          'Add a free gift to your order',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'The products in your cart cannot be modified',
        ),
      );
    }
  },
);

Check `instructions.metafields.canSetCartMetafields` or `instructions.metafields.canDeleteCartMetafields` before calling `applyMetafieldChange()` if you are working with cart metafields.

import {
  Banner,
  Button,
  useApplyMetafieldChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyMetafieldChange =
    useApplyMetafieldChange();
  const instructions = useInstructions();

  if (
    instructions.metafields.canSetCartMetafields
  ) {
    return (
      <Button
        onPress={() =>
          applyMetafieldChange({
            type: 'updateCartMetafield',
            metafield: {
              namespace: 'loyalty',
              key: 'loyaltyPoints',
              value: '100',
              type: 'string',
            },
          })
        }
      >
        Apply 100 loyalty points
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty points are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.metafields
        .canSetCartMetafields
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyMetafieldChange({
                type: 'updateCartMetafield',
                metafield: {
                  namespace: 'loyalty',
                  key: 'loyaltyPoints',
                  value: '100',
                  type: 'string',
                },
              }),
          },
          'Apply 100 loyalty points',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty points are unavailable',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyMetafieldChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyMetafieldChange =
    useApplyMetafieldChange();
  const instructions = useInstructions();

  if (
    instructions.metafields.canSetCartMetafields
  ) {
    return (
      <Button
        onPress={() =>
          applyMetafieldChange({
            type: 'updateCartMetafield',
            metafield: {
              namespace: 'loyalty',
              key: 'loyaltyPoints',
              value: '100',
              type: 'string',
            },
          })
        }
      >
        Apply 100 loyalty points
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Loyalty points are unavailable
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.metafields
        .canSetCartMetafields
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyMetafieldChange({
                type: 'updateCartMetafield',
                metafield: {
                  namespace: 'loyalty',
                  key: 'loyaltyPoints',
                  value: '100',
                  type: 'string',
                },
              }),
          },
          'Apply 100 loyalty points',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Loyalty points are unavailable',
        ),
      );
    }
  },
);

Check `instructions.notes.canUpdateNote` before calling `applyNoteChange()`.

import {
  Banner,
  Button,
  useApplyNoteChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyNoteChange = useApplyNoteChange();
  const instructions = useInstructions();

  if (instructions.notes.canUpdateNote) {
    return (
      <Button
        onPress={() =>
          applyNoteChange({
            type: 'updateNote',
            note: 'Please include a free gift.',
          })
        }
      >
        Include a free gift with your order
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Free gifts cannot be added to this order
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.notes.canUpdateNote
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyNoteChange({
                type: 'updateNote',
                note: 'Please include a free gift.',
              }),
          },
          'Include a free gift with your order',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Free gifts cannot be added to this order',
        ),
      );
    }
  },
);

import {
  Banner,
  Button,
  useApplyNoteChange,
  useInstructions,
  reactExtension,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const applyNoteChange = useApplyNoteChange();
  const instructions = useInstructions();

  if (instructions.notes.canUpdateNote) {
    return (
      <Button
        onPress={() =>
          applyNoteChange({
            type: 'updateNote',
            note: 'Please include a free gift.',
          })
        }
      >
        Include a free gift with your order
      </Button>
    );
  } else {
    return (
      <Banner status="warning">
        Free gifts cannot be added to this order
      </Banner>
    );
  }
}

import {
  extension,
  Banner,
  Button,
} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.block.render',
  (root, api) => {
    if (
      api.instructions.current.notes.canUpdateNote
    ) {
      root.appendChild(
        root.createComponent(
          Button,
          {
            onPress: () =>
              api.applyNoteChange({
                type: 'updateNote',
                note: 'Please include a free gift.',
              }),
          },
          'Include a free gift with your order',
        ),
      );
    } else {
      root.appendChild(
        root.createComponent(
          Banner,
          {},
          'Free gifts cannot be added to this order',
        ),
      );
    }
  },
);