Skip to main content

Anchor to Cart Transform Function APICart Transform Function API

A cart represents the merchandise that a customer intends to purchase, and the estimated cost associated with the cart. Transforming a cart refers to changing the pricing and presentation of items in a cart. To modify the appearance of cart items, such as updating titles and images, changing prices, and bundling items, you can only use the Cart Transform API.

Shopify Functions enable you to customize Shopify's backend logic. The Cart Transform API integrates this logic into the checkout flow.

Use the API to add product bundles to a store or break down bundled products into individual components, with associated data such as buyer identity, quantity, cost, and subscription information.

Note

You can have a maximum of one cart transform function on each app.

Anchor to Use casesUse cases

  • Expand a cart line item to display the bundled items it contains.
  • Merge multiple cart lines into a single line that represents a bundle.
  • Update the presentation of line items in a cart to override their price, title, or image.
Note

Only development stores or stores on a Shopify Plus plan can use apps with lineUpdate operations.

Note

Only development stores or stores on a Shopify Plus plan can use apps with update operations.

Compatibility with Shopify surfaces
Supported (7)
Partially supported (1)
Unsupported (5)
Was this section helpful?

Anchor to Getting startedGetting started

Scaffolding the function using Shopify CLI will automatically configure your TOML file. You can alter the default configuration to customize the way your function operates.

TutorialBuild a cart transform function
Was this section helpful?

Anchor to TargetsTargets

A target is an identifier in shopify.extension.toml that specifies where you're injecting code into Shopify Function APIs, or other parts of the Shopify platform. Each target is composed of three to four namespaces. The name begins with a broad Shopify context and ends with the behavior of the extensible element.

Anchor to Run targetRun target

cart.transform.run

The run target modifies the pricing and presentation of items in a cart either using Shopify data or hardcoded values. The target returns a list of operations to be applied to cart line items.

For example, you might use this to automatically add a warranty when a specific product is added to a cart.

Anchor to InputInput
OBJECT

The Input object is the complete GraphQL schema that your function can query as input to customize the presentation of items in a cart. Your function receives only the fields that you request in the input query. To optimize performance, we highly recommend that you request only the fields that your function requires.

Anchor to cartcart
•
Cart!
non-null

The cart where the Function is running. A cart contains the merchandise that a customer intends to purchase and information about the customer, such as the customer's email address and phone number.

Anchor to attributeattribute
•
Attribute

The custom attributes associated with a cart to store additional information. Cart attributes allow you to collect specific information from customers on the Cart page, such as order notes, gift wrapping requests, or custom product details. Attributes are stored as key-value pairs.

Arguments

Anchor to keykey
•
String

The key of the cart attribute to retrieve. For example, "gift_wrapping".

Fields

Anchor to keykey
•
String!
non-null

The key or name of the attribute. For example, "customer_first_order".

Anchor to valuevalue
•
String

The value of the attribute. For example, "true".

Anchor to buyerIdentitybuyerIdentity
•
BuyerIdentity

Information about the customer that's interacting with the cart. It includes details such as the customer's email and phone number, and the total amount of money the customer has spent in the store. This information helps personalize the checkout experience and ensures that accurate pricing and delivery options are displayed to customers.

Anchor to customercustomer
•
Customer

The customer that's interacting with the cart.

Anchor to amountSpentamountSpent
•
MoneyV2!
non-null

The total amount that the customer has spent on orders. The amount is converted from the shop's currency to the currency of the cart using a market rate.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to displayNamedisplayName
•
String!
non-null

The full name of the customer, based on the values for firstName and lastName. If firstName and lastName aren't specified, then the value is the customer's email address. If the email address isn't specified, then the value is the customer's phone number.

Anchor to emailemail
•
String

The customer's email address.

Anchor to firstNamefirstName
•
String

The customer's first name.

Anchor to hasAnyTaghasAnyTag
•
Boolean!
non-null

Whether the customer is associated with any of the specified tags. The customer must have at least one tag from the list to return true.

Anchor to hasTagshasTags
•
[HasTagResponse!]!
non-null

Whether the customer is associated with the specified tags.

Arguments

Anchor to tagstags
•
[String!]!
requiredDefault:[]

A comma-separated list of searchable keywords that are associated with the customer. For example, "VIP, Gold" returns customers with both the VIP and Gold tags.

Fields

Anchor to hasTaghasTag
•
Boolean!
non-null

Whether the Shopify resource has the tag.

Anchor to tagtag
•
String!
non-null

A searchable keyword that's associated with a Shopify resource, such as a product or customer. For example, a merchant might apply the sports and summer tags to products that are associated with sportswear for summer.

Anchor to idid
•
ID!
non-null

A globally-unique ID for the customer.

Anchor to lastNamelastName
•
String

The customer's last name.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to numberOfOrdersnumberOfOrders
•
Int!
non-null

The total number of orders that the customer has made at the store.

Anchor to emailemail
•
String

The email address of the customer that's interacting with the cart.

Anchor to isAuthenticatedisAuthenticated
•
Boolean!
non-null

Whether the customer is authenticated through their customer account.

Anchor to phonephone
•
String

The phone number of the customer that's interacting with the cart.

Anchor to purchasingCompanypurchasingCompany
•
PurchasingCompany

The company of a B2B customer that's interacting with the cart. Used to manage and track purchases made by businesses rather than individual customers.

Anchor to companycompany
•
Company!
non-null

The company associated to the order or draft order.

Anchor to createdAtcreatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company was created in Shopify.

Anchor to externalIdexternalId
•
String

A unique externally-supplied ID for the company.

Anchor to idid
•
ID!
non-null

The ID of the company.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to namename
•
String!
non-null

The name of the company.

Anchor to updatedAtupdatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company was last modified.

Anchor to contactcontact
•
CompanyContact

The company contact associated to the order or draft order.

Anchor to createdAtcreatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company contact was created in Shopify.

Anchor to idid
•
ID!
non-null

The ID of the company.

Anchor to localelocale
•
String

The company contact's locale (language).

Anchor to titletitle
•
String

The company contact's job title.

Anchor to updatedAtupdatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company contact was last modified.

Anchor to locationlocation
•
CompanyLocation!
non-null

The company location associated to the order or draft order.

Anchor to createdAtcreatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company location was created in Shopify.

Anchor to externalIdexternalId
•
String

A unique externally-supplied ID for the company.

Anchor to idid
•
ID!
non-null

The ID of the company.

Anchor to localelocale
•
String

The preferred locale of the company location.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to namename
•
String!
non-null

The name of the company location.

Anchor to updatedAtupdatedAt
•
DateTime!
non-null

The date and time (ISO 8601 format) at which the company location was last modified.

Anchor to lineslines
•
[CartLine!]!
non-null

The items in a cart that the customer intends to purchase. A cart line is an entry in the customer's cart that represents a single unit of a product variant. For example, if a customer adds two different sizes of the same t-shirt to their cart, then each size is represented as a separate cart line.

Anchor to attributeattribute
•
Attribute

The custom attributes associated with a cart to store additional information. Cart attributes allow you to collect specific information from customers on the Cart page, such as order notes, gift wrapping requests, or custom product details. Attributes are stored as key-value pairs.

Cart line attributes are equivalent to the line_item object in Liquid.

Arguments

Anchor to keykey
•
String

The key of the cart attribute to retrieve. For example, "gift_wrapping".

Fields

Anchor to keykey
•
String!
non-null

The key or name of the attribute. For example, "customer_first_order".

Anchor to valuevalue
•
String

The value of the attribute. For example, "true".

Anchor to costcost
•
CartLineCost!
non-null

The cost of an item in a cart that the customer intends to purchase. Cart lines are entries in the customer's cart that represent a single unit of a product variant. For example, if a customer adds two different sizes of the same t-shirt to their cart, then each size is represented as a separate cart line.

Anchor to amountPerQuantityamountPerQuantity
•
MoneyV2!
non-null

The cost of a single unit. For example, if a customer purchases three units of a product that are priced at $10 each, then the amountPerQuantity is $10.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to compareAtAmountPerQuantitycompareAtAmountPerQuantity
•
MoneyV2

The cost of a single unit before any discounts are applied. This field is used to calculate and display savings for customers. For example, if a product's compareAtAmountPerQuantity is $25 and its current price is $20, then the customer sees a $5 discount. This value can change based on the buyer's identity and is null when the value is hidden from buyers.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to subtotalAmountsubtotalAmount
•
MoneyV2!
non-null

The cost of items in the cart before applying any discounts to certain items. This amount serves as the starting point for calculating any potential savings customers might receive through promotions or discounts.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to totalAmounttotalAmount
•
MoneyV2!
non-null

The total cost of items in a cart.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to idid
•
ID!
non-null

The ID of the cart line.

Anchor to merchandisemerchandise
•
Merchandise!
non-null

The item that the customer intends to purchase.

Anchor to CustomProduct
CustomProduct
•OBJECT

A custom product represents a product that doesn't map to Shopify's standard product categories. For example, you can use a custom product to manage gift cards, shipping requirements, localized product information, or weight measurements and conversions.

Anchor to isGiftCardisGiftCard
•
Boolean!
non-null

Whether the merchandise is a gift card.

Anchor to requiresShippingrequiresShipping
•
Boolean!
non-null

Whether the item needs to be shipped to the customer. For example, a digital gift card doesn't need to be shipped, but a t-shirt does need to be shipped.

Anchor to titletitle
•
String!
non-null

The localized name for the product that displays to customers. The title is used to construct the product's handle, which is a unique, human-readable string of the product's title. For example, if a product is titled "Black Sunglasses", then the handle is black-sunglasses.

Anchor to weightweight
•
Float

The product variant's weight, in the system of measurement set in the weightUnit field.

Anchor to weightUnitweightUnit
•
WeightUnit!
non-null

The unit of measurement for weight.

GRAMS, KILOGRAMS, OUNCES, POUNDS
Anchor to ProductVariant
ProductVariant
•OBJECT

A specific version of a product that comes in more than one option, such as size or color. For example, if a merchant sells t-shirts with options for size and color, then a small, blue t-shirt would be one product variant and a large, blue t-shirt would be another.

Anchor to idid
•
ID!
non-null

A globally-unique ID for the product variant.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to productproduct
•
Product!
non-null

The product associated with the product variant. For example, if a merchant sells t-shirts with options for size and color, then a small, blue t-shirt would be one product variant and a large, blue t-shirt would be another. The product associated with the product variant would be the t-shirt itself.

Anchor to handlehandle
•
Handle!
non-null

A unique, human-readable string of the product's title. A handle can contain letters, hyphens (-), and numbers, but not spaces. The handle is used in the online store URL for the product. For example, if a product is titled "Black Sunglasses", then the handle is black-sunglasses.

Anchor to hasAnyTaghasAnyTag
•
Boolean!
non-null

Whether the product is associated with any of the specified tags. The product must have at least one tag from the list to return true.

Anchor to hasTagshasTags
•
[HasTagResponse!]!
non-null

Whether the product is associated with the specified tags.

Arguments

Anchor to tagstags
•
[String!]!
requiredDefault:[]

A comma-separated list of searchable keywords that are associated with the product. For example, "sports, summer" returns products with both the sports and summer tags.

Fields

Anchor to hasTaghasTag
•
Boolean!
non-null

Whether the Shopify resource has the tag.

Anchor to tagtag
•
String!
non-null

A searchable keyword that's associated with a Shopify resource, such as a product or customer. For example, a merchant might apply the sports and summer tags to products that are associated with sportswear for summer.

Anchor to idid
•
ID!
non-null

A globally-unique ID for the product.

Anchor to inAnyCollectioninAnyCollection
•
Boolean!
non-null

Whether the product is in any of the specified collections. The product must be in at least one collection from the list to return true.

A collection is a group of products that can be displayed in online stores and other sales channels in categories, which makes it easy for customers to find them. For example, an athletics store might create different collections for running attire and accessories.

Anchor to inCollectionsinCollections
•
[CollectionMembership!]!
non-null

Whether the product is in the specified collections. The product must be in all of the collections in the list to return true.

A collection is a group of products that can be displayed in online stores and other sales channels in categories, which makes it easy for customers to find them. For example, an athletics store might create different collections for running attire and accessories.

Arguments

Anchor to idsids
•
[ID!]!
requiredDefault:[]

A comma-separated list of globally-unique collection IDs that are associated with the product. For example, gid://shopify/Collection/123, gid://shopify/Collection/456.

Fields

Anchor to collectionIdcollectionId
•
ID!
non-null

A globally-unique ID for the collection.

Anchor to isMemberisMember
•
Boolean!
non-null

Whether the product is in the specified collection.

Anchor to isGiftCardisGiftCard
•
Boolean!
non-null

Whether the product is a gift card.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to productTypeproductType
•
String

A custom category for a product. Product types allow merchants to define categories other than the ones available in Shopify's standard product categories.

Anchor to titletitle
•
String!
non-null

The localized name for the product that displays to customers. The title is used to construct the product's handle, which is a unique, human-readable string of the product's title. For example, if a product is titled "Black Sunglasses", then the handle is black-sunglasses.

Anchor to vendorvendor
•
String

The name of the product's vendor.

Anchor to requiresShippingrequiresShipping
•
Boolean!
non-null

Whether the item needs to be shipped to the customer. For example, a digital gift card doesn't need to be shipped, but a t-shirt does need to be shipped.

Anchor to skusku
•
String

A case-sensitive identifier for the product variant in the merchant's store. For example, "BBC-1". A product variant must have a SKU to be connected to a fulfillment service.

Anchor to titletitle
•
String

The localized name for the product variant that displays to customers.

Anchor to weightweight
•
Float

The product variant's weight, in the system of measurement set in the weightUnit field.

Anchor to weightUnitweightUnit
•
WeightUnit!
non-null

The unit of measurement for weight.

GRAMS, KILOGRAMS, OUNCES, POUNDS
Anchor to quantityquantity
•
Int!
non-null

The quantity of the item that the customer intends to purchase.

Anchor to sellingPlanAllocationsellingPlanAllocation
•
SellingPlanAllocation

The selling plan associated with the cart line, including information about how a product variant can be sold and purchased.

Anchor to priceAdjustmentspriceAdjustments
•
[SellingPlanAllocationPriceAdjustment!]!
non-null

A list of price adjustments, with a maximum of two. When there are two, the first price adjustment goes into effect at the time of purchase, while the second one starts after a certain number of orders. A price adjustment represents how a selling plan affects pricing when a variant is purchased with a selling plan. Prices display in the customer's currency if the shop is configured for it.

Anchor to perDeliveryPriceperDeliveryPrice
•
MoneyV2!
non-null

The effective price for a single delivery. For example, for a prepaid subscription plan that includes 6 deliveries at the price of $48.00, the per delivery price is $8.00.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to priceprice
•
MoneyV2!
non-null

The price of the variant when it's purchased with a selling plan For example, for a prepaid subscription plan that includes 6 deliveries of $10.00 granola, where the customer gets 20% off, the price is 6 x $10.00 x 0.80 = $48.00.

Anchor to amountamount
•
Decimal!
non-null

A monetary value in decimal format, allowing for precise representation of cents or fractional currency. For example, 12.99.

Anchor to currencyCodecurrencyCode
•
CurrencyCode!
non-null

The three-letter currency code that represents a world currency used in a store. Currency codes include standard standard ISO 4217 codes, legacy codes, and non-standard codes. For example, USD.

AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, 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, JEP, JMD, JOD, JPY, KES, KGS, KHR, KID, KMF, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, 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, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USDC, UYU, UZS, VED, VES, VND, VUV, WST, XAF, XCD, XOF, XPF, XXX, YER, ZAR, ZMW, BYR, STD, VEF
Anchor to sellingPlansellingPlan
•
SellingPlan!
non-null

A representation of how products and variants can be sold and purchased. For example, an individual selling plan could be '6 weeks of prepaid granola, delivered weekly'.

Anchor to descriptiondescription
•
String

The description of the selling plan.

Anchor to idid
•
ID!
non-null

A globally-unique identifier.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to namename
•
String!
non-null

The name of the selling plan. For example, '6 weeks of prepaid granola, delivered weekly'.

Anchor to recurringDeliveriesrecurringDeliveries
•
Boolean!
non-null

Whether purchasing the selling plan will result in multiple deliveries.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to retailLocationretailLocation
•
Location

The physical location where a retail order is created or completed.

Anchor to addressaddress
•
LocationAddress!
non-null

The address of this location.

Anchor to address1address1
•
String

The first line of the address for the location.

Anchor to address2address2
•
String

The second line of the address for the location.

Anchor to citycity
•
String

The city of the location.

Anchor to countrycountry
•
String

The country of the location.

Anchor to countryCodecountryCode
•
String

The country code of the location.

Anchor to formattedformatted
•
[String!]!
non-null

A formatted version of the address for the location.

Anchor to latitudelatitude
•
Float

The approximate latitude coordinates of the location.

Anchor to longitudelongitude
•
Float

The approximate longitude coordinates of the location.

Anchor to phonephone
•
String

The phone number of the location.

Anchor to provinceprovince
•
String

The province of the location.

Anchor to provinceCodeprovinceCode
•
String

The code for the province, state, or district of the address of the location.

Anchor to zipzip
•
String

The ZIP code of the location.

Anchor to handlehandle
•
Handle!
non-null

The location handle.

Anchor to idid
•
ID!
non-null

The location id.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to namename
•
String!
non-null

The name of the location.

Anchor to cartTransformcartTransform
•
CartTransform!
non-null

A customization that changes the pricing and presentation of items in a cart. For example, you can modify the appearance of cart items, such as updating titles and images, or bundling items.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to localizationlocalization
•
Localization!
non-null

The regional and language settings that determine how the Function handles currency, numbers, dates, and other locale-specific values during discount calculations. These settings are based on the store's configured localization practices.

Anchor to countrycountry
•
Country!
non-null

The country for which the store is customized, reflecting local preferences and regulations. Localization might influence the language, currency, and product offerings available in a store to enhance the shopping experience for customers in that region.

Anchor to isoCodeisoCode
•
CountryCode!
non-null

The ISO code of the country.

AC, AD, AE, AF, AG, AI, AL, AM, AN, AO, AR, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MK, ML, MM, MN, MO, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PS, PT, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TA, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW, ZZ
Anchor to languagelanguage
•
Language!
non-null

The language for which the store is customized, ensuring content is tailored to local customers. This includes product descriptions and customer communications that resonate with the target audience.

Anchor to isoCodeisoCode
•
LanguageCode!
non-null

The ISO code.

AF, AK, AM, AR, AS, AZ, BE, BG, BM, BN, BO, BR, BS, CA, CE, CKB, CS, CU, CY, DA, DE, DZ, EE, EL, EN, EO, ES, ET, EU, FA, FF, FI, FIL, FO, FR, FY, GA, GD, GL, GU, GV, HA, HE, HI, HR, HU, HY, IA, ID, IG, II, IS, IT, JA, JV, KA, KI, KK, KL, KM, KN, KO, KS, KU, KW, KY, LB, LG, LN, LO, LT, LU, LV, MG, MI, MK, ML, MN, MR, MS, MT, MY, NB, ND, NE, NL, NN, NO, OM, OR, OS, PA, PL, PS, PT, PT_BR, PT_PT, QU, RM, RN, RO, RU, RW, SA, SC, SD, SE, SG, SI, SK, SL, SN, SO, SQ, SR, SU, SV, SW, TA, TE, TG, TH, TI, TK, TO, TR, TT, UG, UK, UR, UZ, VI, VO, WO, XH, YI, YO, ZH, ZH_CN, ZH_TW, ZU
Anchor to marketmarket
•
Market!
non-nullDeprecated
Anchor to handlehandle
•
Handle!
non-null

A human-readable unique string for the market automatically generated from its title.

Anchor to idid
•
ID!
non-null

A globally-unique identifier.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to regionsregions
•
[MarketRegion!]!
non-null

A geographic region which comprises a market.

Anchor to namename
•
String

The name of the region in the language of the current localization.

Anchor to presentmentCurrencyRatepresentmentCurrencyRate
•
Decimal!
non-null

The exchange rate used to convert discounts between the shop's default currency and the currency that displays to the customer during checkout. For example, if a store operates in USD but a customer is viewing discounts in EUR, then the presentment currency rate handles this conversion for accurate pricing.

Anchor to shopshop
•
Shop!
non-null

Information about the shop where the Function is running, including the shop's timezone setting and associated metafields.

Anchor to localTimelocalTime
•
LocalTime!
non-null

The current time based on the store's timezone setting.

Anchor to datedate
•
Date!
non-null

The current date relative to the parent object.

Anchor to dateTimeAfterdateTimeAfter
•
Boolean!
non-null

Returns true if the current date and time is at or past the given date and time, and false otherwise.

Anchor to dateTimeBeforedateTimeBefore
•
Boolean!
non-null

Returns true if the current date and time is before the given date and time, and false otherwise.

Anchor to dateTimeBetweendateTimeBetween
•
Boolean!
non-null

Returns true if the current date and time is between the two given date and times, and false otherwise.

Anchor to timeAftertimeAfter
•
Boolean!
non-null

Returns true if the current time is at or past the given time, and false otherwise.

Anchor to timeBeforetimeBefore
•
Boolean!
non-null

Returns true if the current time is at or past the given time, and false otherwise.

Anchor to timeBetweentimeBetween
•
Boolean!
non-null

Returns true if the current time is between the two given times, and false otherwise.

Anchor to metafieldmetafield
•
Metafield

A custom field that stores additional information about a Shopify resource, such as products, orders, and many more. Using metafields with Shopify Functions enables you to customize the checkout experience.

Arguments

Anchor to namespacenamespace
•
String

A category that organizes a group of metafields. Namespaces are used to prevent naming conflicts between different apps or different parts of the same app. If omitted, then the app-reserved namespace is used.

Anchor to keykey
•
String!
required

The unique identifier for the metafield within its namespace. A metafield is composed of a namespace and a key, in the format namespace.key.

Fields

Anchor to jsonValuejsonValue
•
JSON!
non-null

The data that's stored in the metafield, using JSON format.

Anchor to typetype
•
String!
non-null

The type of data that the metafield stores in the value field.

Anchor to valuevalue
•
String!
non-null

The data that's stored in the metafield. The data is always stored as a string, regardless of the metafield's type.

Anchor to Run functionRun function

The logic that processes the input data to generate a standardized list of operations that change the pricing and presentation of items in a cart.

Each operation specifies how to display the items in a cart. Shopify processes your response to present the cart items to customers during checkout, including data such as price and quantity.

This return must follow the schema defined in the CartTransformRunResult object.

Anchor to CartTransformRunResultCartTransformRunResult
OBJECT

The CartTransformRunResult object is the output of the function run target. The object contains the operations to change the pricing and presentation of items in a cart.

Anchor to operationsoperations
•
[Operation!]!
non-null

The ordered list of operations to apply to the cart. For example, you can expand a cart line item to display its bundled items, merge multiple cart lines into a single line representing a bundle, and update the presentation of line items in the cart to override their price, title, or image.

Anchor to lineExpandlineExpand
•
LineExpandOperation

An operation that expands a single cart line item to form a bundle of components.

Anchor to cartLineIdcartLineId
•
ID!
non-null

A globally-unique ID for a line item in a cart. A cart line represents a single unit of a product variant that a customer intends to purchase.

Anchor to expandedCartItemsexpandedCartItems
•
[ExpandedItem!]!
non-null

The cart items to expand. Each item in the list is a component of the bundle. A bundle is a group of products that are sold together as a single unit.

Anchor to attributesattributes
•
[AttributeOutput!]

The custom attributes associated with a cart line to store additional information. Cart attributes allow you to collect specific information from customers on the Cart page, such as order notes, gift wrapping requests, or custom product details. Attributes are stored as key-value pairs.

Anchor to keykey
•
String!
non-null

The key of the cart line attribute to retrieve. For example, "gift_wrapping".

Anchor to valuevalue
•
String!
non-null

The value of the cart line attribute to retrieve. For example, "true".

Anchor to merchandiseIdmerchandiseId
•
ID!
non-null

A globally-unique ID for the product variant that represents the expanded item.

Anchor to priceprice
•
ExpandedItemPriceAdjustment

A change to the original price of the expanded item. Price adjustments include discounts or additional charges that affect the final price the customer pays. Price adjustments are often used for promotions, special offers, or any price changes that the customer qualifies for.

Anchor to adjustmentadjustment
•
ExpandedItemPriceAdjustmentValue!
non-null

The value of the price adjustment to apply to the expanded item.

Anchor to fixedPricePerUnitfixedPricePerUnit
•
ExpandedItemFixedPricePerUnitAdjustment

A fixed price per unit adjustment to apply to the expanded item.

Anchor to amountamount
•
Decimal!
non-null

The fixed price amount per quantity of the expanded item in presentment currency.

Anchor to quantityquantity
•
Int!
non-null

The quantity of the expanded item. The maximum quantity is 2000.

Anchor to imageimage
•
ImageInput

The image that replaces the existing image for the group of cart line items. The image must have a publicly accessible URL.

Anchor to urlurl
•
URL!
non-null

The URL of the image.

Anchor to priceprice
•
PriceAdjustment

A change to the original price of a group of items. Price adjustments include discounts or additional charges that affect the final price the customer pays. Price adjustments are often used for promotions, special offers, or any price changes that the customer qualifies for.

Anchor to percentageDecreasepercentageDecrease
•
PriceAdjustmentValue

The percentage price decrease of the price adjustment.

Anchor to valuevalue
•
Decimal!
non-null

The value of the price adjustment.

Anchor to titletitle
•
String

The title that replaces the existing title for the cart line item. If you don't provide a title, then the title of the product variant is used.

Anchor to linesMergelinesMerge
•
LinesMergeOperation

An operation that merges multiple cart line items into a single line, representing a bundle of components.

Anchor to attributesattributes
•
[AttributeOutput!]

The custom attributes associated with a cart line to store additional information. Cart attributes allow you to collect specific information from customers on the Cart page, such as order notes, gift wrapping requests, or custom product details. Attributes are stored as key-value pairs.

Anchor to keykey
•
String!
non-null

The key of the cart line attribute to retrieve. For example, "gift_wrapping".

Anchor to valuevalue
•
String!
non-null

The value of the cart line attribute to retrieve. For example, "true".

Anchor to cartLinescartLines
•
[CartLineInput!]!
non-null

The cart items to merge. Each item in the list is a component of the bundle.

Anchor to cartLineIdcartLineId
•
ID!
non-null

A globally-unique ID for a line item in a cart. A cart line represents a single unit of a product variant that a customer intends to purchase.

Anchor to quantityquantity
•
Int!
non-null

The quantity of the cart line to be merged.The max quantity is 2000.

Anchor to imageimage
•
ImageInput

The image that replaces the existing image for the group of cart line items. The image must have a publicly accessible URL.

Anchor to urlurl
•
URL!
non-null

The URL of the image.

Anchor to parentVariantIdparentVariantId
•
ID!
non-null

The globally-unique ID of the product variant that represents the collection of cart line items.

Anchor to priceprice
•
PriceAdjustment

A change to the original price of a group of items. Price adjustments include discounts or additional charges that affect the final price the customer pays. Price adjustments are often used for promotions, special offers, or any price changes that the customer qualifies for.

Anchor to percentageDecreasepercentageDecrease
•
PriceAdjustmentValue

The percentage price decrease of the price adjustment.

Anchor to valuevalue
•
Decimal!
non-null

The value of the price adjustment.

Anchor to titletitle
•
String

The title that replaces the existing title for a group of cart line items. If you don't provide a title, then the title of the parent variant is used.

Anchor to lineUpdatelineUpdate
•
LineUpdateOperation

An operation that allows you to override the price, title, and image of a cart line item. Only stores on a Shopify Plus plan can use apps with update operations.

Anchor to cartLineIdcartLineId
•
ID!
non-null

A globally-unique ID for a line item in a cart. A cart line represents a single unit of a product variant that a customer intends to purchase.

Anchor to imageimage
•
ImageInput

The image that replaces the existing image for the cart line item. The image must have a publicly accessible URL.

Anchor to urlurl
•
URL!
non-null

The URL of the image.

Anchor to priceprice
•
LineUpdateOperationPriceAdjustment

A change to an item's original price. Price adjustments include discounts or additional charges that affect the final price the customer pays. Price adjustments are often used for promotions, special offers, or any price changes for which the customer qualifies.

Anchor to adjustmentadjustment
•
LineUpdateOperationPriceAdjustmentValue!
non-null

The price adjustment per unit to apply to the cart line item.

Anchor to fixedPricePerUnitfixedPricePerUnit
•
LineUpdateOperationFixedPricePerUnitAdjustment

A fixed price per unit adjustment to apply to a cart line.

Anchor to amountamount
•
Decimal!
non-null

The fixed price amount per quantity of the cart line item in presentment currency.

Anchor to titletitle
•
String

The title that replaces the existing title for the cart line item. If you don't provide a title, then the title of the product variant is used.

Was this section helpful?

Anchor to Multiple operationsMultiple operations

Sometimes, a function might return multiple expand, merge, and update operations for the same cart line, which can lead to collisions. For example, a collision might happen when you execute different operations in quick succession, or when multiple changes are applied to the same cart line. To avoid potential issues, try to minimize these collisions in your implementation.

If a collision does occur, then Shopify handles it by executing a subset of operations based on the following criteria:

  • If multiple lineExpand operations target the same cart line, then the first lineExpand operation in the list is executed, and all other lineExpand operations for the same cart line are discarded.
  • If multiple linesMerge operations target the same cart line, then the first linesMerge operation in the list is executed, and all other linesMerge operations for the same cart line are discarded.
  • If both lineExpand and linesMerge operations target the same cart line, then the lineExpand operation is executed, and the merge operation is discarded.
  • If multiple lineUpdate operations target the same cart line, then the first lineUpdate operation in the list is executed, and all other lineUpdate operations for the same cart line are discarded.
  • If lineExpand, linesMerge, and lineUpdate operations target the same cart line, then the lineExpand operation is executed while the merge and lineUpdate operations are discarded.
  • If both fixed lineExpand and customized lineExpand operations target the same cart line, then the fixed lineExpand operation is executed and the customized lineExpand operation is discarded.
Was this section helpful?

Anchor to Pricing adjustmentsPricing adjustments

You can use linesMerge and lineExpand operations to adjust pricing. The bundle base price varies depending on the operation:

  • linesMerge: The adjustment is based on the components' price sum.
  • lineExpand: The adjustment is based on the bundle product price.

This distinction ensures that the correct price appears for expand operations on the Product details page and in Liquid.

For example, to arrive at the final bundle price, you can use the following post-processing operations:

  • linesMerge: The final price is the sum of the individual component prices, plus the adjustment, if present.
  • lineExpand: The final price is the sum of the individual component fixedPricePerUnit values, or the bundle product price, plus the adjustment, if present.

Anchor to Component pricingComponent pricing

Expand operations allow you to adjust the price of each individual component in the bundle by providing a price on the expandedCartItems field in the ExpandOperation object.

The costs returned by the input query reflect prices in the presentment currency, and all operation outputs are also processed in this currency. Presentment currency is the currency that customers see when they view prices in a store.

If you need to set a new price based on the cost in the store's currency, then you should do the following:

  1. To get the conversion rate from shop currency to presentment currency, include the presentmentCurrencyRate field in your input query.
  2. Convert the amount from the shop currency to presentment currency using the rate.
  3. Return the converted price in your operation output.

Anchor to Weight price algorithmWeight price algorithm

When you don't provide a fixed price per unit on lineExpand operations, Shopify allocates the bundle price to its component lines based on the weight of each component line. The weight of a component is calculated as the unit price multiplied by quantity, as unit price * quantity.

The algorithm considers the item's price as if the item was bought individually and the quantity inside the bundle. For example, if a bundle has 10 t-shirts and 1 pair of shorts, and the shorts and t-shirt cost $5 if they were bought individually, then Shopify allocates more weight to the t-shirt. The total weight of all component lines is then used to calculate the weight of each component line.

Anchor to ExampleExample

Amount to be allocated: $100

Component lines:

  • unit_price: $10, quantity: 1, id: 1 # weight 10
  • unit_price: $20, quantity: 2, id: 2 # weight 40
  • unit_price: $30, quantity: 3, id: 3 # weight 90

Total weight: 140

Result:

  • Component 1: $7.14 -> (10 / 140) * $100 = 7.14
  • Component 2: $28.57 -> (40 / 140) * $100 = 28.57
  • Component 3: $64.29 -> (90 / 140) * $100 = 64.29
Was this section helpful?

Anchor to Overriding images and titlesOverriding images and titles

  • Uploading images: For optimal performance and security, you can only use upload images for cart lines from Shopify CDN. You can upload images through the Shopify admin or using the GraphQL Admin API. Using images from outside of the CDN will result in an invalid_image_url error.
  • Image sizes: Image URLs shouldn't include a size suffix. The cart will automatically request the appropriately sized image from the CDN by adding a size suffix to the image name, such as custom-image_64x64.png.
  • Showing overrides: Title and image overrides appear across various surfaces, including the cart, checkout, and order notification emails. To see title overrides applied by cart transform functions in these areas, you'll need to modify your themes. Use item.title for the cart and line.title for order notification emails to display the updated titles.
Was this section helpful?

Anchor to ErrorsErrors

The following errors can occur when using the Cart Transform API:

Errors that can occur when using the Cart Transform API
Operation typeError codeMessage
lineExpandcannot_combine_price_adjustment_and_price_per_componentCannot combine both an overall price adjustment and individual prices for components.
component_merchandise_not_foundOne or more of the expanded cart items have a merchandise ID that does not exist.
exceeded_maximum_number_of_supported_expanded_cart_itemsExceeded the maximum number of supported expanded cart items (150).
expanded_items_missing_pricesOne or more expanded cart items are missing prices. Either all must have a price, or none.
image_feature_not_availableThe feature to update the image is not accessible for the given shop.
image_not_foundImage not found for the shop.
invalid_cart_line_idThe cart line ID is invalid.
invalid_component_merchandise_idOne or more of the expanded cart items have an invalid merchandise ID.
invalid_component_quantityOne or more of the expanded cart items have an invalid quantity.
invalid_component_priceOne or more of the expanded cart items have an invalid price.
invalid_image_urlThe base image URL must be any of the following: https://cdn.shopify.com, https://cdn.shopifycdn.net, or the shop's domain with a path of /cdn/*.
invalid_price_adjustment_percentage_decreaseThe percentage decrease value must be less than or equal to 100.
price_per_component_feature_not_availableThe feature to price an expanded cart item is not accessible for the given shop.
title_feature_not_availableThe feature to update the title is not accessible for the given shop.
linesMergeexceeded_maximum_number_of_supported_merged_cart_itemsExceeded the maximum number of supported merged cart items.
image_not_foundImage not found for the shop.
insufficient_component_quantity_to_mergeThere are not enough items in the cart to satisfy one or more of the component quantities.
invalid_component_cart_line_idOne or more of the cart lines have an invalid cart line ID.
invalid_component_quantityOne or more of the cart lines have an invalid quantity.
invalid_image_urlThe base image URL must be any of the following: https://cdn.shopify.com, https://cdn.shopifycdn.net, or the shop's domain with a path of /cdn/*.
invalid_parent_variant_idThe parent variant ID isn't valid.
invalid_price_adjustment_percentage_decreaseThe percentage decrease value must be less than or equal to 100.
parent_variant_not_foundThe parent variant doesn't exist.
lineUpdatefixed_price_adjustment_cannot_be_negativeFixed price adjustments cannot be negative.
image_not_foundImage not found for the shop.
invalid_cart_line_idThe cart line ID is invalid.
invalid_image_urlThe base image URL must be any of the following: https://cdn.shopify.com, https://cdn.shopifycdn.net, or the shop's domain with a path of /cdn/*.
update_feature_not_availableThe update operation feature is not accessible for the given shop.
Was this section helpful?

Anchor to Invalid scenariosInvalid scenarios

Shopify rejects lineExpand, linesMerge, and lineUpdate operations if a selling plan is present. Rejections are different from error scenarios, which might involve implementation issues not directly related to the operations being performed.

The following table describes invalid scenarios by operation type:

Invalid scenarios by operation type
Operation typeScenarios
lineExpand
  • One of the component quantities is less than 0.
  • The line to be expanded doesn't exist.
  • One of the component variant IDs doesn't exist.
  • Both ExpandedItem.Price and PriceAdjustment are returned in the operation.
  • One of the components is given a price less than 0.
  • Some of the components have a customized price and others don't.
linesMerge
  • The merge operation contains an invalid quantity for the children (less than 0 or the quantity to merge is bigger than the line's quantity).
  • The parent variant ID doesn't exist.
  • One of the lines to be merged doesn't exist.
lineUpdate
  • The operation includes a price < 0.
  • The line to be updated doesn't exist.
  • The operation targets a line that is going to be expanded or merged.
  • The shop is not on a Plus plan or a Development store plan.
Was this section helpful?

Anchor to Additional resourcesAdditional resources

Explore comprehensive guides and references to help you build, deploy, and optimize your Shopify Functions.

Anchor to Working with FunctionsWorking with Functions

These guides cover essential concepts for building Shopify Functions effectively. Learn how functions process data, execute during checkout, and handle versioning, localization, and external APIs.

Function anatomy

Explore how functions process input data and generate operations.

Execution order in checkout

Learn when Function APIs execute during the checkout process.

Schema and versioning

Understand schema versioning, release and upgrade requirements.

API availability

Check which Shopify plans support functions in custom apps.

Localization practices

Localize functions for international markets.

Anchor to Performance and troubleshootingPerformance and troubleshooting

Optimize function performance and ensure reliable operation from development through production deployment.

Resource limits and performance

Understand function performance requirements and resource limitations for optimal execution.

Test and debug Shopify Functions

Explore comprehensive testing workflows from local development to production deployment.

Considerations for programming languages

Choose languages that compile to WebAssembly for optimal function performance.

Monitoring and handling errors in production

Master testing and debugging workflows for reliable function development.

Was this section helpful?