Choose a version:

useApplyCartLinesChange
hook

Returns a function to mutate the lines property of checkout.

Anchor to useApplyCartLinesChange
useApplyCartLinesChange()

Anchor to useApplyCartLinesChange-returnsReturns

(change: ) => Promise<>

UseApplyCartLinesChangeGeneratedType

Returns a function to mutate the `lines` property of checkout.

(change: CartLineChange) => Promise<CartLineChangeResult>

(change: CartLineChange) => Promise<CartLineChangeResult>

export function useApplyCartLinesChange<
  Target extends RenderExtensionTarget = RenderExtensionTarget,
>(): (change: CartLineChange) => Promise<CartLineChangeResult> {
  const api = useApi<Target>();

  if ('applyCartLinesChange' in api) {
    return api.applyCartLinesChange;
  }

  throw new ExtensionHasNoMethodError(
    'applyCartLinesChange',
    api.extension.target,
  );
}

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'];
}

CartLine

id
These line item IDs are not stable at the moment, they might change after any operations on the line items. You should always look up for an updated ID before any call to `applyCartLinesChange` because you'll need the ID to create a `CartLineChange` object.
```
string
```
merchandise
The merchandise being purchased.
```
Merchandise
```
quantity
The quantity of the merchandise being purchased.
```
number
```
cost
The details about the cost components attributed to the cart line.
```
CartLineCost
```
attributes
The line item additional custom attributes.
```
Attribute[]
```
discountAllocations
Discounts applied to the cart line.
```
CartDiscountAllocation[]
```
lineComponents
Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
```
CartBundleLineComponent[]
```

export interface CartLine {
  /**
   * These line item IDs are not stable at the moment, they might change after
   * any operations on the line items. You should always look up for an updated
   * ID before any call to `applyCartLinesChange` because you'll need the ID to
   * create a `CartLineChange` object.
   * @example 'gid://shopify/CartLine/123'
   */
  id: string;

  /**
   * The merchandise being purchased.
   */
  merchandise: Merchandise;

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

  /**
   * The details about the cost components attributed to the cart line.
   */
  cost: CartLineCost;

  /**
   * The line item additional custom attributes.
   */
  attributes: Attribute[];

  /**
   * Discounts applied to the cart line.
   */
  discountAllocations: CartDiscountAllocation[];

  /**
   * Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.
   */
  lineComponents: CartLineComponentType[];
}

Merchandise

type
```
"variant"
```
id
A globally-unique identifier.
```
string
```
title
The product variant’s title.
```
string
```
subtitle
The product variant's subtitle.
```
string
```
image
Image associated with the product variant. This field falls back to the product image if no image is available.
```
ImageDetails
```
selectedOptions
List of product options applied to the variant.
```
SelectedOption[]
```
product
The product object that the product variant belongs to.
```
Product
```
requiresShipping
Whether or not the product requires shipping.
```
boolean
```
sellingPlan
The selling plan associated with the merchandise.
```
SellingPlan
```

ProductVariant

ImageDetails

url
The image URL.
```
string
```
altText
The alternative text for the image.
```
string
```

export interface ImageDetails {
  /**
   * The image URL.
   */
  url: string;

  /**
   * The alternative text for the image.
   */
  altText?: string;
}

SelectedOption

name
The name of the merchandise option.
```
string
```
value
The value of the merchandise option.
```
string
```

export interface SelectedOption {
  /**
   * The name of the merchandise option.
   */
  name: string;

  /**
   * The value of the merchandise option.
   */
  value: string;
}

Product

id
A globally-unique identifier.
```
string
```
vendor
The product’s vendor name.
```
string
```
productType
A categorization that a product can be tagged with, commonly used for filtering and searching.
```
string
```

export interface Product {
  /**
   * A globally-unique identifier.
   */
  id: string;

  /**
   * The product’s vendor name.
   */
  vendor: string;

  /**
   * A categorization that a product can be tagged with, commonly used for filtering and searching.
   */
  productType: string;
}

SellingPlan

id
A globally-unique identifier.
```
string
```

export interface SellingPlan {
  /**
   * A globally-unique identifier.
   * @example 'gid://shopify/SellingPlan/1'
   */
  id: string;
}

CartLineCost

totalAmount
The total amount after reductions the buyer can expect to pay that is directly attributable to a single cart line.
```
Money
```

export interface CartLineCost {
  /**
   * The total amount after reductions the buyer can expect to pay that is directly attributable to a single
   * cart line.
   */
  totalAmount: Money;
}

Money

amount
The price amount.
```
number
```
currencyCode
The ISO 4217 format for the currency.
```
CurrencyCode
```

export interface Money {
  /**
   * The price amount.
   */
  amount: number;
  /**
   * The ISO 4217 format for the currency.
   * @example 'CAD' for Canadian dollar
   */
  currencyCode: CurrencyCode;
}

CurrencyCode

'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HRK' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLL' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWL'

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;
}

CartDiscountAllocation

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code
The code for the discount
```
string
```
type
The type of the code discount
```
"code"
```
discountedAmount
The money amount that has been discounted from the order
```
Money
```

export interface CartCodeDiscountAllocation extends CartDiscountAllocationBase {
  /**
   * The code for the discount
   */
  code: string;

  /**
   * The type of the code discount
   */
  type: 'code';
}

CartAutomaticDiscountAllocation

title
The title of the automatic discount
```
string
```
type
The type of the automatic discount
```
"automatic"
```
discountedAmount
The money amount that has been discounted from the order
```
Money
```

export interface CartAutomaticDiscountAllocation
  extends CartDiscountAllocationBase {
  /**
   * The title of the automatic discount
   */
  title: string;

  /**
   * The type of the automatic discount
   */
  type: 'automatic';
}

CartCustomDiscountAllocation

title
The title of the custom discount
```
string
```
type
The type of the custom discount
```
"custom"
```
discountedAmount
The money amount that has been discounted from the order
```
Money
```

export interface CartCustomDiscountAllocation
  extends CartDiscountAllocationBase {
  /**
   * The title of the custom discount
   */
  title: string;

  /**
   * The type of the custom discount
   */
  type: 'custom';
}

CartBundleLineComponent

type
```
"bundle"
```
id
A unique identifier for the bundle line component. This ID is not stable. If an operation updates the line items in any way, all IDs could change.
```
string
```
merchandise
The merchandise of this bundle line component.
```
Merchandise
```
quantity
The quantity of merchandise being purchased.
```
number
```
cost
The cost attributed to this bundle line component.
```
CartLineCost
```
attributes
Additional custom attributes for the bundle line component.
```
Attribute[]
```

export interface CartBundleLineComponent {
  type: 'bundle';

  /**
   * A unique identifier for the bundle line component.
   *
   * This ID is not stable. If an operation updates the line items in any way, all IDs could change.
   *
   * @example 'gid://shopify/CartLineComponent/123'
   */
  id: string;

  /**
   * The merchandise of this bundle line component.
   */
  merchandise: Merchandise;

  /**
   * The quantity of merchandise being purchased.
   */
  quantity: number;

  /**
   * The cost attributed to this bundle line component.
   */
  cost: CartLineCost;

  /**
   * Additional custom attributes for the bundle line component.
   *
   * @example [{key: 'engraving', value: 'hello world'}]
   */
  attributes: Attribute[];
}

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;
}

Was this section helpful?