Choose a version:

CheckoutApi

Requires access to protected customer data for some properties.

This API object is provided to extensions registered for the extension points that appear exclusively pre-purchase.

It extends the StandardApi and provides the write apis for the checkout data.

Anchor to propertiesProperties

See the StandardApi examples for more information on how to use the API.

Anchor to applyAttributeChange applyAttributeChange (change: ) => Promise<> required: Performs an update on an attribute attached to the cart and checkout. If successful, this mutation results in an update to the value retrieved through the attributes property.

Note
This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Anchor to applyCartLinesChange applyCartLinesChange (change: ) => Promise<> required: Performs an update on the merchandise line items. It resolves when the new line items have been negotiated and results in an update to the value retrieved through the lines property.

Note
This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Anchor to applyDiscountCodeChange applyDiscountCodeChange (change: ) => Promise<> required: Performs an update on the discount codes. It resolves when the new discount codes have been negotiated and results in an update to the value retrieved through the discountCodes property.

Caution
See security considerations if your extension retrieves discount codes through a network call.
Note
This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Anchor to applyGiftCardChange applyGiftCardChange (change: ) => Promise<> required: Performs an update on the gift cards. It resolves when gift card change have been negotiated and results in an update to the value retrieved through the appliedGiftCards property.

Caution
See security considerations if your extension retrieves gift card codes through a network call.
Note
This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.
Anchor to applyMetafieldChange applyMetafieldChange (change: ) => Promise<> required: Performs an update on a piece of metadata attached to the cart or checkout:

If type is updateMetafield or removeMetafield, this mutation results in an update to the value retrieved through the metafields property. Metafields written by updateMetafield are carried over to the order.

If type is updateCartMetafield or removeCartMetafield, this mutation updates the metafield attached to the cart and results in an update to the value retrieved through the appMetafields property. Metafields written by updateCartMetafields are updated on the cart object only and are not carried over to the order.

Tip
Cart metafields are only available on carts created via the Storefront API version 2023-04 or later.
Anchor to applyNoteChange applyNoteChange (change: ) => Promise<> required: Performs an update on the note attached to the cart and checkout. If successful, this mutation results in an update to the value retrieved through the note property.

Note
This method will return an error if the buyer is using an accelerated checkout method, such as Apple Pay, Google Pay, or Meta Pay.

AttributeUpdateChange

Updates an attribute on the order. If an attribute with the provided key does not already exist, it gets created.

type
The type of the `AttributeUpdateChange` API.
```
"updateAttribute"
```
key
Key of the attribute to add or update
```
string
```
value
Value for the attribute to add or update
```
string
```

export interface AttributeUpdateChange {
  /**
   * The type of the `AttributeUpdateChange` API.
   */
  type: 'updateAttribute';

  /**
   * Key of the attribute to add or update
   */
  key: string;

  /**
   * Value for the attribute to add or update
   */
  value: string;
}

AttributeChangeResult

AttributeChangeResultSuccess | AttributeChangeResultError

AttributeChangeResultSuccess

The returned result of a successful update to an attribute.

type
The type of the `AttributeChangeResultSuccess` API.
```
"success"
```

export interface AttributeChangeResultSuccess {
  /**
   * The type of the `AttributeChangeResultSuccess` API.
   */
  type: 'success';
}

AttributeChangeResultError

The returned result of an unsuccessful update to an attribute with a message detailing the type of error that occurred.

type
The type of the `AttributeChangeResultError` API.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface AttributeChangeResultError {
  /**
   * The type of the `AttributeChangeResultError` API.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

CartLineChange

CartLineAddChange | CartLineRemoveChange | CartLineUpdateChange

CartLineAddChange

type
An identifier for changes that add line items.
```
"addCartLine"
```
merchandiseId
The merchandise ID being added.
```
string
```
quantity
The quantity of the merchandise being added.
```
number
```
attributes
The attributes associated with the line item.
```
Attribute[]
```
sellingPlanId
The identifier of the selling plan that the merchandise is being purchased with.
```
string
```

export interface CartLineAddChange {
  /**
   * An identifier for changes that add line items.
   */
  type: 'addCartLine';

  /**
   * The merchandise ID being added.
   * @example 'gid://shopify/ProductVariant/123'
   */
  merchandiseId: string;

  /**
   * The quantity of the merchandise being added.
   */
  quantity: number;

  /**
   * The attributes associated with the line item.
   */
  attributes?: Attribute[];

  /**
   * The identifier of the selling plan that the merchandise is being purchased
   * with.
   */
  sellingPlanId?: SellingPlan['id'];
}

Attribute

key
The key for the attribute.
```
string
```
value
The value for the attribute.
```
string
```

export interface Attribute {
  /**
   * The key for the attribute.
   */
  key: string;

  /**
   * The value for the attribute.
   */
  value: string;
}

CartLineRemoveChange

type
An identifier for changes that remove line items.
```
"removeCartLine"
```
id
Line Item ID.
```
string
```
quantity
The quantity being removed for this line item.
```
number
```

export interface CartLineRemoveChange {
  /**
   * An identifier for changes that remove line items.
   */
  type: 'removeCartLine';

  /**
   * Line Item ID.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The quantity being removed for this line item.
   */
  quantity: number;
}

CartLineUpdateChange

type
An identifier for changes that update line items.
```
"updateCartLine"
```
id
Line Item ID.
```
string
```
merchandiseId
The new merchandise ID for the line item.
```
string
```
quantity
The new quantity for the line item.
```
number
```
attributes
The new attributes for the line item.
```
Attribute[]
```
sellingPlanId
The identifier of the selling plan that the merchandise is being purchased with or `null` to remove the the product from the selling plan.
```
string
```

export interface CartLineUpdateChange {
  /**
   * An identifier for changes that update line items.
   */
  type: 'updateCartLine';

  /**
   * Line Item ID.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The new merchandise ID for the line item.
   * @example 'gid://shopify/ProductVariant/123'
   */

  merchandiseId?: string;
  /**
   * The new quantity for the line item.
   */
  quantity?: number;

  /**
   * The new attributes for the line item.
   */
  attributes?: Attribute[];

  /**
   * The identifier of the selling plan that the merchandise is being purchased
   * with or `null` to remove the the product from the selling plan.
   */
  sellingPlanId?: SellingPlan['id'] | null;
}

CartLineChangeResult

CartLineChangeResultSuccess | CartLineChangeResultError

CartLineChangeResultSuccess

type
Indicates that the line item was changed successfully.
```
"success"
```

export interface CartLineChangeResultSuccess {
  /**
   * Indicates that the line item was changed successfully.
   */
  type: 'success';
}

CartLineChangeResultError

type
Indicates that the line item was not changed successfully. Refer to the `message` property for details about the error.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface CartLineChangeResultError {
  /**
   * Indicates that the line item was not changed successfully. Refer to the `message` property for details about the error.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

DiscountCodeChange

DiscountCodeAddChange | DiscountCodeRemoveChange

DiscountCodeAddChange

type
The type of the `DiscountCodeChange` API.
```
"addDiscountCode"
```
code
The code for the discount
```
string
```

export interface DiscountCodeAddChange {
  /**
   * The type of the `DiscountCodeChange` API.
   */
  type: 'addDiscountCode';

  /**
   * The code for the discount
   */
  code: string;
}

DiscountCodeRemoveChange

type
The type of the `DiscountCodeChange` API.
```
"removeDiscountCode"
```
code
The code for the discount
```
string
```

export interface DiscountCodeRemoveChange {
  /**
   * The type of the `DiscountCodeChange` API.
   */
  type: 'removeDiscountCode';

  /**
   * The code for the discount
   */
  code: string;
}

DiscountCodeChangeResult

DiscountCodeChangeResultSuccess | DiscountCodeChangeResultError

DiscountCodeChangeResultSuccess

type
Indicates that the discount code change was applied successfully.
```
"success"
```

export interface DiscountCodeChangeResultSuccess {
  /**
   * Indicates that the discount code change was applied successfully.
   */
  type: 'success';
}

DiscountCodeChangeResultError

type
Indicates that the discount code change failed.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface DiscountCodeChangeResultError {
  /**
   * Indicates that the discount code change failed.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

GiftCardChange

GiftCardAddChange | GiftCardRemoveChange

GiftCardAddChange

type
The type of the `GiftCardChange` API.
```
"addGiftCard"
```
code
Gift card code.
```
string
```

export interface GiftCardAddChange {
  /**
   * The type of the `GiftCardChange` API.
   */
  type: 'addGiftCard';

  /**
   * Gift card code.
   */
  code: string;
}

GiftCardRemoveChange

type
The type of the `GiftCardChange` API.
```
"removeGiftCard"
```
code
Gift card code.
```
string
```

export interface GiftCardRemoveChange {
  /**
   * The type of the `GiftCardChange` API.
   */
  type: 'removeGiftCard';

  /**
   * Gift card code.
   */
  code: string;
}

GiftCardChangeResult

GiftCardChangeResultSuccess | GiftCardChangeResultError

GiftCardChangeResultSuccess

type
Indicates that the gift card change was applied successfully.
```
"success"
```

export interface GiftCardChangeResultSuccess {
  /**
   * Indicates that the gift card change was applied successfully.
   */
  type: 'success';
}

GiftCardChangeResultError

type
Indicates that the gift card change failed.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface GiftCardChangeResultError {
  /**
   * Indicates that the gift card change failed.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

MetafieldChange

MetafieldRemoveChange | MetafieldUpdateChange | MetafieldRemoveCartChange | MetafieldUpdateCartChange

MetafieldRemoveChange

Removes a metafield.

type
The type of the `MetafieldRemoveChange` API.
```
"removeMetafield"
```
key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```

export interface MetafieldRemoveChange {
  /**
   * The type of the `MetafieldRemoveChange` API.
   */
  type: 'removeMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}

MetafieldUpdateChange

Updates a metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

type
The type of the `MetafieldUpdateChange` API.
```
"updateMetafield"
```
key
The name of the metafield to update.
```
string
```
namespace
The namespace of the metafield to add.
```
string
```
value
The new information to store in the metafield.
```
string | number
```
valueType
The metafield’s information type.
```
"string" | "integer" | "json_string"
```

export interface MetafieldUpdateChange {
  /**
   * The type of the `MetafieldUpdateChange` API.
   */
  type: 'updateMetafield';

  /** The name of the metafield to update. */
  key: string;

  /** The namespace of the metafield to add. */
  namespace: string;

  /** The new information to store in the metafield. */
  value: string | number;

  /**
   * The metafield’s information type.
   */
  valueType: 'integer' | 'string' | 'json_string';
}

MetafieldRemoveCartChange

Removes a cart metafield.

type
The type of the `MetafieldRemoveCartChange` API.
```
"removeCartMetafield"
```
key
The name of the metafield to remove.
```
string
```
namespace
The namespace of the metafield to remove.
```
string
```

export interface MetafieldRemoveCartChange {
  /**
   * The type of the `MetafieldRemoveCartChange` API.
   */
  type: 'removeCartMetafield';

  /**
   * The name of the metafield to remove.
   */
  key: string;

  /**
   * The namespace of the metafield to remove.
   */
  namespace: string;
}

MetafieldUpdateCartChange

Updates a cart metafield. If a metafield with the provided key and namespace does not already exist, it gets created.

type
The type of the `MetafieldUpdateCartChange` API.
```
"updateCartMetafield"
```

metafield

{ key: string; namespace: string; value: string; type: string; }

export interface MetafieldUpdateCartChange {
  /**
   * The type of the `MetafieldUpdateCartChange` API.
   */
  type: 'updateCartMetafield';

  metafield: {
    /** The name of the metafield to update. */
    key: string;

    /** The namespace of the metafield to add. */
    namespace: string;

    /** The new information to store in the metafield. */
    value: string;

    /**
     * The metafield’s information type.
     * See the [`metafields documentation`](/docs/apps/custom-data/metafields/types) for a list of supported types.
     */
    type: string;
  };
}

MetafieldChangeResult

MetafieldChangeResultSuccess | MetafieldChangeResultError

MetafieldChangeResultSuccess

type
The type of the `MetafieldChangeResultSuccess` API.
```
"success"
```

export interface MetafieldChangeResultSuccess {
  /**
   * The type of the `MetafieldChangeResultSuccess` API.
   */
  type: 'success';
}

MetafieldChangeResultError

type
The type of the `MetafieldChangeResultError` API.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface MetafieldChangeResultError {
  /**
   * The type of the `MetafieldChangeResultError` API.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

NoteChange

NoteRemoveChange | NoteUpdateChange

NoteRemoveChange

Removes a note

type
The type of the `NoteRemoveChange` API.
```
"removeNote"
```

export interface NoteRemoveChange {
  /**
   * The type of the `NoteRemoveChange` API.
   */
  type: 'removeNote';
}

NoteUpdateChange

An Update to a note on the order. for example, the buyer could request detailed packaging instructions in an order note

type
The type of the `NoteUpdateChange` API.
```
"updateNote"
```
note
The new value of the note.
```
string
```

export interface NoteUpdateChange {
  /**
   * The type of the `NoteUpdateChange` API.
   */
  type: 'updateNote';
  /**
   * The new value of the note.
   */
  note: string;
}

NoteChangeResult

NoteChangeResultSuccess | NoteChangeResultError

NoteChangeResultSuccess

type
The type of the `NoteChangeResultSuccess` API.
```
"success"
```

export interface NoteChangeResultSuccess {
  /**
   * The type of the `NoteChangeResultSuccess` API.
   */
  type: 'success';
}

NoteChangeResultError

type
The type of the `NoteChangeResultError` API.
```
"error"
```
message
A message that explains the error. This message is useful for debugging. It is **not** localized, and therefore should not be presented directly to the buyer.
```
string
```

export interface NoteChangeResultError {
  /**
   * The type of the `NoteChangeResultError` API.
   */
  type: 'error';

  /**
   * A message that explains the error. This message is useful for debugging.
   * It is **not** localized, and therefore should not be presented directly
   * to the buyer.
   */
  message: string;
}

Examples

import {

render,

Checkbox,

useApplyAttributeChange,

} from '@shopify/checkout-ui-extensions-react';

// 1. Choose an extension point

render('Checkout::Dynamic::Render', () => (

));

function Extension() {

const applyAttributeChange =

useApplyAttributeChange();

// 2. Render a UI

return (

I would like to receive a free gift with my

order

</Checkbox>

);

// 3. Call API methods to modify the checkout

async function onCheckboxChange(isChecked) {

const result = await applyAttributeChange({

key: 'requestedFreeGift',

type: 'updateAttribute',

value: isChecked ? 'yes' : 'no',

});

console.log(

'applyAttributeChange result',

result,

);

}

Examples

React

import {
  render,
  Checkbox,
  useApplyAttributeChange,
} from '@shopify/checkout-ui-extensions-react';

// 1. Choose an extension point
render('Checkout::Dynamic::Render', () => (
  <Extension />
));

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

  // 2. Render a UI
  return (
    <Checkbox onChange={onCheckboxChange}>
      I would like to receive a free gift with my
      order
    </Checkbox>
  );

  // 3. Call API methods to modify the checkout
  async function onCheckboxChange(isChecked) {
    const result = await applyAttributeChange({
      key: 'requestedFreeGift',
      type: 'updateAttribute',
      value: isChecked ? 'yes' : 'no',
    });
    console.log(
      'applyAttributeChange result',
      result,
    );
  }
}

JavaScript

import {
  extend,
  Checkbox,
} from '@shopify/checkout-ui-extensions';

// 1. Choose an extension point
extend(
  'Checkout::Dynamic::Render',
  (root, api) => {
    // 2. Render a UI
    root.appendChild(
      root.createComponent(
        Checkbox,
        {
          onChange: onCheckboxChange,
        },
        'I would like to receive a free gift with my order',
      ),
    );

    // 3. Call API methods to modify the checkout
    async function onCheckboxChange(isChecked) {
      const result =
        await api.applyAttributeChange({
          key: 'requestedFreeGift',
          type: 'updateAttribute',
          value: isChecked ? 'yes' : 'no',
        });
      console.log(
        'applyAttributeChange result',
        result,
      );
    }
  },
);

Anchor to relatedRelated

APIsStandardApi

APIsOrderStatusApi

APIsCartLineDetailsApi

APIsPickupPointsApi

APIsPickupLocationsApi

APIsShippingMethodDetailsApi

APIsExtensionPoints

Was this page helpful?