--- title: Delivery API description: |2- The APIs for interacting with delivery and shipping options. > Tip: Not all extension targets implement all APIs. Check the documentation for the extension target you are using to see which APIs are available. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/delivery-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/delivery-api.md --- # Delivery API The APIs for interacting with delivery and shipping options. **Tip:** Not all extension targets implement all APIs. Check the documentation for the extension target you are using to see which APIs are available. ### Support Targets (31) ### Supported targets * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **deliveryGroups** **SubscribableSignalLike\** **required** The delivery groups for this checkout. Each group contains one or more cart lines and the available delivery options (shipping, pickup point, or pickup location) for those items. ### SubscribableSignalLike Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility. * current The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context. ```ts T ``` * destroy Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread. ```ts () => Promise ``` * subscribe Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value. ```ts (fn: (value: T) => void) => () => void ``` * value The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup. ```ts T ``` ### DeliveryGroup A group of cart lines that share the same set of delivery options. For example, physical items might form one delivery group while digital items form another. * deliveryOptions The delivery options available for this group, including shipping, pickup point, and pickup location options. The buyer selects one of these to determine how their items are delivered. ```ts DeliveryOption[] ``` * groupType Whether this group contains items for a one-time purchase or a subscription. Subscription delivery groups might have different shipping options. See \`DeliveryGroupType\` for possible values. ```ts DeliveryGroupType ``` * id A unique identifier for the delivery group. The value is \`undefined\` if the underlying delivery line doesn't have an ID assigned. ```ts string ``` * isDeliveryRequired Whether physical delivery is required for the items in this group. Digital-only groups don't require delivery. ```ts boolean ``` * selectedDeliveryOption The delivery option the buyer has selected for this group. The value is \`undefined\` if the buyer hasn't selected a delivery option yet. Contains a \`handle\` you can match against \`deliveryOptions\` entries. ```ts DeliveryOptionReference ``` * targetedCartLines The cart lines that belong to this delivery group. Each reference contains the cart line's \`id\`, which you can match against \`lines\` to get the full cart line details. ```ts CartLineReference[] ``` ### DeliveryOption A delivery option available to the buyer. Use the \`type\` property to determine which kind of option it is: - \`ShippingOption\` (\`type: 'shipping' | 'local'\`): Items shipped by a carrier or delivered locally by the merchant. - \`PickupPointOption\` (\`type: 'pickupPoint'\`): Items shipped to a third-party collection point for the buyer to pick up. - \`PickupLocationOption\` (\`type: 'pickup'\`): Items picked up directly from a merchant's store or warehouse. ```ts ShippingOption | PickupPointOption | PickupLocationOption ``` ### ShippingOption Represents a delivery option that's a shipping option. * carrier Information about the carrier providing this shipping option, including the carrier's display name. ```ts ShippingOptionCarrier ``` * code The carrier service code or rate identifier for this delivery option. ```ts string ``` * cost The cost of this delivery option before any shipping discounts are applied. Compare with \`costAfterDiscounts\` to show savings. ```ts Money ``` * costAfterDiscounts The cost of this delivery option after shipping discounts have been applied. This is the price the buyer actually pays for shipping. ```ts Money ``` * deliveryEstimate The estimated delivery time for this shipping option. Use the \`timeInTransit\` range to display an estimated arrival window to the buyer. ```ts DeliveryEstimate ``` * description Additional details about the delivery option provided by the carrier or merchant, such as estimated delivery windows or service level notes. ```ts string ``` * handle The unique identifier of the delivery option. Use this to match against \`DeliveryOptionReference.handle\` or \`DeliverySelectionGroup\` entries. ```ts string ``` * metafields Custom \[metafields]\(/docs/apps/build/custom-data/metafields) attached to this delivery option by the carrier or a \[Shopify Function]\(/docs/apps/build/functions). Use these to display additional information about the option. ```ts Metafield[] ``` * title The merchant-facing or carrier-provided display name for the delivery option, such as "Standard Shipping" or "Express". ```ts string ``` * type Identifies the delivery method. \`'shipping'\` means items are shipped by a carrier. \`'local'\` means the merchant handles delivery themselves, for example same-day local delivery. ```ts 'shipping' | 'local' ``` ### ShippingOptionCarrier * name The display name of the shipping carrier, such as "Canada Post" or "UPS". The value is \`undefined\` if the carrier name isn't available. ```ts string ``` ### Money * amount The decimal amount of the price. For example, \`29.99\` represents twenty-nine dollars and ninety-nine cents. ```ts number ``` * currencyCode The three-letter currency code in \[ISO 4217]\(https://en.wikipedia.org/wiki/ISO\_4217) format. ```ts CurrencyCode ``` ### CurrencyCode ```ts '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' ``` ### DeliveryEstimate * timeInTransit The estimated time in transit for the delivery, expressed as a range in seconds. Undefined when the carrier doesn't provide an estimate. When present, either the lower or upper bound of the range might still be omitted. ```ts NumberRange ``` ### NumberRange * lower The lower bound of the range. Undefined if only an upper bound is provided. ```ts number ``` * upper The upper bound of the range. Undefined if only a lower bound is provided. ```ts number ``` ### Metafield Metadata associated with the checkout. See the \[metafields documentation]\(/docs/apps/build/custom-data/metafields) for more information on how metafields work. * key The name of the metafield. ```ts string ``` * namespace A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. ```ts string ``` * value The information to be stored as metadata. ```ts string | number ``` * valueType The metafield's information type. - \`'integer'\`: A whole number value. - \`'string'\`: A plain text value. - \`'json\_string'\`: A JSON-encoded string value. ```ts 'integer' | 'string' | 'json_string' ``` ### PickupPointOption * carrier Information about the carrier that ships items to this pickup point, including the carrier's name and code. ```ts PickupPointCarrier ``` * code The carrier service code or rate identifier for this delivery option. ```ts string ``` * cost The cost of this delivery option before any shipping discounts are applied. Compare with \`costAfterDiscounts\` to show savings. ```ts Money ``` * costAfterDiscounts The cost of this delivery option after shipping discounts have been applied. This is the price the buyer actually pays for shipping. ```ts Money ``` * description Additional details about the delivery option provided by the carrier or merchant, such as estimated delivery windows or service level notes. ```ts string ``` * handle The unique identifier of the delivery option. Use this to match against \`DeliveryOptionReference.handle\` or \`DeliverySelectionGroup\` entries. ```ts string ``` * location The physical location where the buyer picks up their order, including the address and display name of the collection point. ```ts PickupPointLocation ``` * metafields Custom \[metafields]\(/docs/apps/build/custom-data/metafields) attached to this delivery option by the carrier or a \[Shopify Function]\(/docs/apps/build/functions). Use these to display additional information about the option. ```ts Metafield[] ``` * title The merchant-facing or carrier-provided display name for the delivery option, such as "Standard Shipping" or "Express". ```ts string ``` * type Identifies this as a pickup point option, where items are shipped to a third-party collection point for the buyer to pick up. ```ts 'pickupPoint' ``` ### PickupPointCarrier * code The carrier's unique identifier code, used to distinguish between different carriers that deliver to pickup points. ```ts string ``` * name The display name of the carrier that delivers to this pickup point. ```ts string ``` ### PickupPointLocation * address The physical address of the pickup point. ```ts MailingAddress ``` * handle The unique identifier of the pickup point. ```ts string ``` * name The display name of the pickup point, such as the name of the locker or collection point. ```ts string ``` ### MailingAddress * address1 The first line of the street address, including the street number and name. The value is \`undefined\` if the buyer hasn't entered an address yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * address2 The second line of the buyer's address, such as apartment number, suite, or unit. The value is \`undefined\` if the buyer didn't provide a second address line. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * city The city, town, or village of the address. The value is \`undefined\` if the buyer hasn't entered a city yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * company The buyer's company name. The value is \`undefined\` if the buyer didn't enter a company or the store doesn't collect company names. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * countryCode The two-letter country code in \[ISO 3166 Alpha-2]\(https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) format. The value is \`undefined\` if the buyer hasn't selected a country yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts CountryCode ``` * firstName The buyer's first name. Use this alongside \`lastName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a first name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * lastName The buyer's last name. Use this alongside \`firstName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a last name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * name The buyer's full name, typically a combination of first and last name. The value is \`undefined\` if the buyer didn't provide a name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * phone The phone number associated with the address, typically in international format. The value is \`undefined\` if the buyer didn't provide a phone number or the store doesn't collect phone numbers. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * provinceCode The province, state, prefecture, or region code of the address. The format varies by country. The value is \`undefined\` if the buyer hasn't selected one yet or the country doesn't have provinces. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * zip The postal code or ZIP code of the address, used for mail sorting and delivery routing. The value is \`undefined\` if the buyer hasn't entered one yet or the country doesn't use postal codes. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` ### CountryCode ```ts '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' ``` ### PickupLocationOption * code The carrier service code or rate identifier for this delivery option. ```ts string ``` * description Additional details about the delivery option provided by the carrier or merchant, such as estimated delivery windows or service level notes. ```ts string ``` * handle The unique identifier of the delivery option. Use this to match against \`DeliveryOptionReference.handle\` or \`DeliverySelectionGroup\` entries. ```ts string ``` * location The merchant's store or warehouse where the buyer picks up their order, including the address and display name. ```ts PickupLocation ``` * metafields Custom \[metafields]\(/docs/apps/build/custom-data/metafields) attached to this delivery option by the carrier or a \[Shopify Function]\(/docs/apps/build/functions). Use these to display additional information about the option. ```ts Metafield[] ``` * title The merchant-facing or carrier-provided display name for the delivery option, such as "Standard Shipping" or "Express". ```ts string ``` * type Identifies this as a pickup location option, where the buyer picks up items directly from a merchant's store or warehouse. ```ts 'pickup' ``` ### PickupLocation * address The physical address of the pickup location. ```ts MailingAddress ``` * name The merchant-defined display name of the pickup location, such as a store name or warehouse label. ```ts string ``` ### DeliveryGroupType The possible types of a delivery group. - \`'oneTimePurchase'\`: Items bought as a single, non-recurring purchase. - \`'subscription'\`: Items bought through a \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) that results in recurring deliveries. ```ts 'oneTimePurchase' | 'subscription' ``` ### DeliveryOptionReference A reference to the delivery option selected by the buyer for a delivery group. * handle The unique identifier of the referenced delivery option. Match this against \`DeliveryOption.handle\` from the \`deliveryOptions\` array to get the full option details. ```ts string ``` ### CartLineReference A reference to a cart line within a delivery group, identified by the cart line's ID. * id The unique identifier of the referenced cart line. Match this against \`CartLine.id\` from the \`lines\` property to get the full line item details. ```ts string ``` ## use​Delivery​Group(**[deliveryGroup](#usedeliverygroup-propertydetail-deliverygroup)**​) Returns the full expanded details of a delivery group and automatically re-renders your component when that delivery group changes. ### Parameters * **deliveryGroup** **DeliveryGroup** **required** ### Returns * **DeliveryGroupDetails | undefined** ### DeliveryGroupDetails Represents a DeliveryGroup with expanded reference fields and full details. * deliveryOptions The delivery options available for this group, including shipping, pickup point, and pickup location options. The buyer selects one of these to determine how their items are delivered. ```ts DeliveryOption[] ``` * groupType Whether this group contains items for a one-time purchase or a subscription. Subscription delivery groups might have different shipping options. See \`DeliveryGroupType\` for possible values. ```ts DeliveryGroupType ``` * id A unique identifier for the delivery group. The value is \`undefined\` if the underlying delivery line doesn't have an ID assigned. ```ts string ``` * isDeliveryRequired Whether physical delivery is required for the items in this group. Digital-only groups don't require delivery. ```ts boolean ``` * selectedDeliveryOption The full delivery option the buyer has selected for this group, with all cost and carrier details included. The value is \`undefined\` if the buyer hasn't selected an option yet. Unlike \`DeliveryGroup.selectedDeliveryOption\`, which is a reference, this contains the complete \`DeliveryOption\` object. ```ts DeliveryOption ``` * targetedCartLines The full cart line objects associated with this delivery group, with all merchandise and cost details included. Unlike \`DeliveryGroup.targetedCartLines\`, which contains references, this contains the complete \`CartLine\` objects. ```ts CartLine[] ``` ### CartLine * attributes Custom key-value attributes attached to this cart line, such as gift messages or engraving text. Use \`applyCartLinesChange()\` to update these values. ```ts Attribute[] ``` * cost The cost breakdown for this line item, including the total price after any line-level discounts have been applied. ```ts CartLineCost ``` * discountAllocations Discounts applied to this cart line, including code-based, automatic, and custom discounts. Each allocation shows the discounted amount and how the discount was triggered. ```ts CartDiscountAllocation[] ``` * id A unique identifier for the cart line in the format \`gid://shopify/CartLine/\\`. This ID isn't stable and can change after any cart operation, so avoid persisting it. Always look up the current ID before calling \`applyCartLinesChange()\`, because you'll need it to create a \`CartLineChange\` object. ```ts string ``` * lineComponents The individual components of a \[bundle]\(/docs/apps/build/product-merchandising/bundles) line item. Each component represents a separate product within the bundle. Returns an empty array if the line item isn't a bundle. ```ts CartBundleLineComponent[] ``` * merchandise The product variant or other merchandise associated with this line item. Use this to access product details such as the title, image, SKU, and selected options. ```ts Merchandise ``` * parentRelationship The parent line item that this line belongs to, or \`null\` if this is a top-level line item. Used to identify lines added as children of a bundle or other grouped product. ```ts CartLineParentRelationship | null ``` * quantity The number of units of this merchandise that the buyer purchased. ```ts number ``` ### Attribute * key The identifier for the attribute. Each key must be unique within the set of attributes on the cart or checkout. If you call \`applyAttributeChange()\` with a key that already exists, then the existing value is replaced. ```ts string ``` * value The value associated with the attribute key. This is a freeform string that can store any information the buyer or app provides. ```ts string ``` ### CartLineCost * totalAmount The total price the buyer pays for this line item after all line-level discounts have been applied, but before order-level discounts, taxes, and shipping. ```ts Money ``` ### CartDiscountAllocation A discount allocation applied to the cart. Use the \`type\` property to determine how the discount was triggered: - \`CartCodeDiscountAllocation\` (\`type: 'code'\`): Triggered by a discount code the buyer entered. - \`CartAutomaticDiscountAllocation\` (\`type: 'automatic'\`): Applied automatically based on merchant-configured rules. - \`CartCustomDiscountAllocation\` (\`type: 'custom'\`): Applied by a \[Shopify Function]\(/docs/api/functions/latest/discount). ```ts CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation ``` ### CartCodeDiscountAllocation * code The discount code string that the buyer entered during checkout, such as \`"SAVE10"\` or \`"FREESHIP"\`. ```ts string ``` * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * type Identifies this as a code-based discount, triggered by a discount code the buyer entered at checkout. ```ts 'code' ``` ### CartAutomaticDiscountAllocation * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The merchant-defined title of the automatic discount as displayed to the buyer, such as "Summer Sale 10% Off". ```ts string ``` * type Identifies this as an automatic discount, applied based on merchant-configured rules without a code. ```ts 'automatic' ``` ### CartCustomDiscountAllocation * discountedAmount The monetary value that was deducted from the line item or order total by this discount allocation. ```ts Money ``` * title The title of the custom discount, typically applied by a \[Shopify Function]\(/docs/api/functions/latest/discount). ```ts string ``` * type Identifies this as a custom discount applied by a \[Shopify Function]\(/docs/api/functions/latest/discount). ```ts 'custom' ``` ### CartBundleLineComponent An individual component within a bundled cart line. Each \`CartLine\` that represents a bundle has a \`lineComponents\` array containing these components. * attributes Custom key-value pairs attached to this bundle component, such as personalization options specific to this item within the bundle. ```ts Attribute[] ``` * cost The cost breakdown for this bundle component, including the total amount after any per-item discounts. ```ts CartLineCost ``` * id A unique identifier for this component within the bundle, in the format \`gid://shopify/CartLineComponent/\\`. This ID isn't stable and might change after any operation that updates the line items. ```ts string ``` * merchandise The product variant included in this bundle component. Use this to display product details for individual items within a bundle. ```ts Merchandise ``` * quantity The number of units of this component included in the bundle. ```ts number ``` * type Identifies this as a bundle line component. This is currently the only component type. ```ts 'bundle' ``` ### Merchandise * id A globally-unique identifier for the product variant in the format \`gid://shopify/ProductVariant/\\`. ```ts string ``` * image The image associated with the product variant. Falls back to the product image if the variant doesn't have its own. The value is \`undefined\` if neither the variant nor the product has an image. ```ts ImageDetails ``` * product The parent product that this variant belongs to. Use this to access the product's ID, vendor, and type. ```ts Product ``` * requiresShipping Whether this product variant requires physical shipping. When \`true\`, the buyer must provide a shipping address. Returns \`false\` for digital products, gift cards, and services. ```ts boolean ``` * selectedOptions The product options applied to this variant, such as size, color, or material. Each entry contains the option name and the selected value. ```ts SelectedOption[] ``` * sellingPlan The \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) associated with this variant, such as a subscription or pre-order plan. The value is \`undefined\` if the item isn't being purchased through a selling plan. ```ts SellingPlan ``` * sku The stock keeping unit (SKU) assigned to this variant by the merchant, used for inventory tracking. The value is \`undefined\` if no SKU has been set. ```ts string ``` * subtitle A secondary description for the variant that provides additional context, such as a color or size combination. The value is \`undefined\` if no subtitle is available. ```ts string ``` * title The display title of the product variant, such as "Small" or "Red / Large". This is the variant-specific label, not the parent product title. ```ts string ``` * type Identifies the merchandise as a product variant. This is currently the only merchandise type in checkout. ```ts 'variant' ``` ### ImageDetails * altText The alternative text for the image, used for accessibility. The value is \`undefined\` if the merchant hasn't provided alt text. ```ts string ``` * url The fully-qualified URL of the image. Use this to render the product or variant image in your extension. ```ts string ``` ### Product * id A globally-unique identifier for the product in the format \`gid://shopify/Product/\\`. ```ts string ``` * productType A merchant-defined categorization for the product, such as "Accessories" or "Clothing". Commonly used for filtering and organizing products in a storefront. ```ts string ``` * vendor The name of the product's vendor or manufacturer, as set by the merchant in Shopify admin. ```ts string ``` ### SelectedOption * name The name of the product option, such as "Color" or "Size". ```ts string ``` * value The selected value for the product option, such as "Red" or "Large". ```ts string ``` ### SellingPlan A \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) represents a recurring or deferred purchasing option for a product, such as a subscription, pre-order, or try-before-you-buy plan. The merchant configures selling plans to define how and when the buyer is charged. * id A globally-unique identifier for the selling plan in the format \`gid://shopify/SellingPlan/\\`. Use this to reference the specific selling plan associated with a line item. ```ts string ``` * recurringDeliveries Whether purchasing through this selling plan results in multiple deliveries. \`true\` for subscription plans with recurring fulfillment, \`false\` for one-time pre-orders or try-before-you-buy plans. ```ts boolean ``` ### CartLineParentRelationship * parent The parent cart line that a cart line is associated with. ```ts { id: string; } ``` ## use​Delivery​Groups() Returns the current delivery groups for the checkout, and automatically re-renders your component when delivery address or delivery option selection changes. ### Returns * **DeliveryGroup\[]** ## Shipping Option This API object is provided to extensions registered for the `purchase.checkout.shipping-option-item.render-after` and `purchase.checkout.shipping-option-item.details.render` extension targets. * **isTargetSelected** **SubscribableSignalLike\** **required** Whether the buyer has selected the target shipping option. When `true`, the target option is the buyer's active choice. When `false`, the buyer has chosen a different shipping option. * **renderMode** **ShippingOptionItemRenderMode** **required** The render mode of this shipping option, indicating how the extension is displayed in the checkout UI. * **target** **SubscribableSignalLike\** **required** The shipping option that this extension is attached to. Use this to read the option's cost, carrier, delivery estimate, and other details. ### ShippingOptionItemRenderMode The render mode of a shipping option. * overlay Whether the shipping option is rendered in an overlay. When \`true\`, the extension appears in a modal or sheet on top of the checkout page. When \`false\`, the extension renders inline within the shipping options list. ```ts boolean ``` ## use​Shipping​Option​Target() Returns the shipping option for the `purchase.checkout.shipping-option-item.render-after` and `purchase.checkout.shipping-option-item.details.render` attached extensions. ### Returns * **{ shippingOptionTarget: ShippingOption; isTargetSelected: boolean; renderMode: ShippingOptionItemRenderMode; }** ## ShippingOptionListApi This API object is provided to extensions registered for the `purchase.checkout.shipping-option-list.render-before` and `purchase.checkout.shipping-option-list.render-after` extension targets. * **deliverySelectionGroups** **SubscribableSignalLike< DeliverySelectionGroup\[] | undefined >** **required** The list of delivery selection groups available to the buyer, which let buyers choose between grouped delivery options. The value is `undefined` when no selection groups are available. * **target** **SubscribableSignalLike\** **required** The delivery group list that this extension is attached to. Use this to access all delivery groups and their options. The value is `undefined` when there aren't any delivery groups for the given type. ### DeliverySelectionGroup A named group of delivery options that the buyer can select as a unit. * associatedDeliveryOptions The delivery options that belong to this selection group. Each reference's \`handle\` matches a delivery option handle in the associated delivery group. ```ts DeliveryOptionReference[] ``` * cost The combined cost of all delivery options in this group before discounts. ```ts Money ``` * costAfterDiscounts The combined cost of all delivery options in this group after discounts have been applied. This is what the buyer actually pays. ```ts Money ``` * handle A unique identifier for this selection group. ```ts string ``` * selected Whether the buyer has selected this delivery selection group. When \`true\`, the associated delivery options are active. When \`false\`, the buyer has selected a different group. ```ts boolean ``` * title The localized display title of this selection group, suitable for rendering in the checkout UI. ```ts string ``` ### DeliveryGroupList A collection of delivery groups that share the same group type. * deliveryGroups The delivery groups in this list. Each group contains cart lines and available delivery options for those items. ```ts DeliveryGroup[] ``` * groupType The type of delivery groups in this list. This is the same \`DeliveryGroupType\` used on \`DeliveryGroup.groupType\`. - \`'oneTimePurchase'\`: Items bought as a single, non-recurring purchase. - \`'subscription'\`: Items bought through a \[selling plan]\(/docs/apps/build/purchase-options/subscriptions) that results in recurring deliveries. ```ts DeliveryGroupType ``` ## use​Delivery​Group​Target() Returns the delivery group for the `purchase.checkout.shipping-option-list.render-before` and `purchase.checkout.shipping-option-list.render-after` attached extensions. This is deprecated, use `useDeliveryGroupListTarget()` instead. ### Returns * **DeliveryGroup | undefined** ## use​Delivery​Group​List​Target() Returns the delivery group list for the `purchase.checkout.shipping-option-list.render-before` and `purchase.checkout.shipping-option-list.render-after` attached extensions. ### Returns * **DeliveryGroupList | undefined** ## use​Delivery​Selection​Groups() Returns the delivery selection groups for the `purchase.checkout.shipping-option-list.render-before` and `purchase.checkout.shipping-option-list.render-after` attached extensions. ### Returns * **| DeliverySelectionGroup\[] | undefined** ## PickupPointListApi This API object is provided to extensions registered for the `purchase.checkout.pickup-point-list.render-after` and `purchase.checkout.pickup-point-list.render-after` extension target. * **isLocationFormVisible** **SubscribableSignalLike\** **required** Whether the location search form is currently visible to the buyer. Use this to conditionally render UI that depends on the buyer actively searching for pickup points. ## PickupLocationListApi This API object is provided to extensions registered for the `purchase.checkout.pickup-location-list.render-after` and `purchase.checkout.pickup-location-list.render-after` extension target. * **isLocationFormVisible** **SubscribableSignalLike\** **required** Whether the location search form is currently visible to the buyer. Use this to conditionally render UI that depends on the buyer actively searching for pickup locations. ## PickupLocationItemApi The API object provided to the `purchase.checkout.pickup-location-option-item.render-after` extension target. * **isTargetSelected** **SubscribableSignalLike\** **required** Whether the buyer has selected the target pickup location. When `true`, the target location is the buyer's active choice. When `false`, the buyer has chosen a different pickup location. * **target** **SubscribableSignalLike\** **required** The pickup location that this extension is attached to. Use this to read the location's name, address, and other details. ## use​Pickup​Location​Option​Target() Returns the pickup location option for `purchase.checkout.pickup-location-option-item.render-after` attached extensions. ### Returns * **{ pickupLocationOptionTarget: PickupLocationOption; isTargetSelected: boolean; }** Examples ### Examples * #### Delivery group ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useDeliveryGroup} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { const firstDeliveryGroup = useDeliveryGroup( shopify.deliveryGroups.value[0], ); if (!firstDeliveryGroup) { return null; } const selectedDeliveryOption = firstDeliveryGroup?.selectedDeliveryOption; return ( Selected delivery option:{' '} {selectedDeliveryOption?.title} ); } ``` * #### Reading the selected shipping option ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {useShippingOptionTarget} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { const {shippingOptionTarget, isTargetSelected} = useShippingOptionTarget(); const title = shippingOptionTarget.title; return ( Shipping method: {title} is{' '} {isTargetSelected ? '' : 'not'} selected. ); } ``` * #### Reading the selected pickup location option ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; import {usePickupLocationOptionTarget} from '@shopify/ui-extensions/checkout/preact'; export default function extension() { render(, document.body); } function Extension() { const { isTargetSelected, pickupLocationOptionTarget, } = usePickupLocationOptionTarget(); const title = pickupLocationOptionTarget?.title; if (isTargetSelected) { return {title}; } return null; } ``` * #### Determine if the location input form is shown ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { if (shopify.isLocationFormVisible.value) { return ( The customer is being asked to provide their location. ); } else { return ( Pickup points are being shown. ); } } ``` * #### Delivery groups ##### Preact ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const deliveryGroups = shopify.deliveryGroups.value; return ( First delivery option:{' '} {deliveryGroups[0].deliveryOptions[0].title} ); } ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)