--- title: Delivery API description: >- Access delivery groups, shipping options, and pickup locations during checkout. Read the buyer's selected delivery method and display contextual information. 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 Delivery API provides access to delivery groups, shipping options, and pickup locations during checkout. Use this API to display the buyer's selected delivery method, show shipping or pickup details, and build extensions that render alongside specific delivery options. The Delivery API is read-only. There are no methods to change the buyer's selected shipping option or pickup location from an extension. **Tip:** Not all extension targets implement all APIs. Check the documentation for the extension target you are using to see which APIs are available. ### Use cases * **Display the selected delivery option**: Show the buyer which shipping or delivery method is currently selected. * **Build shipping option extensions**: Render additional information alongside a specific shipping option using the shipping option item target. * **Show pickup location details**: Display information about the buyer's selected pickup location. ### Support Targets (31) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides delivery data for the current checkout. Access the following properties on `shopify` to read delivery groups and their selected options. Available 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. Empty until the buyer enters enough address information for Shopify to calculate shipping rates. ### 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 ``` ### Shipping option item properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for 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. Available only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties. * **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. Available only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties. ### 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 ``` ### Shipping option list properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for 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 ``` ### Pickup point list properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for extensions registered for the `purchase.checkout.pickup-point-list.render-before` and `purchase.checkout.pickup-point-list.render-after` extension targets. * **isLocationFormVisible** **SubscribableSignalLike\** **required** Reflects which view was active when the extension loaded. When the buyer moves to the next view, the extension restarts with the current value rather than updating in place. ### Pickup location list properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for extensions registered for the `purchase.checkout.pickup-location-list.render-before` and `purchase.checkout.pickup-location-list.render-after` extension targets. * **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. ### Pickup location item properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the following additional properties on `shopify` for extensions registered for 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. Available only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties. * **target** **SubscribableSignalLike\** **required** The pickup location that this extension is attached to. Use this to read the location's name, address, and other details. Available only on the corresponding item target. Shipping option item targets expose shipping option properties; pickup location item targets expose pickup location properties. Examples ### Examples * #### ##### Description Show which delivery method the buyer chose from a delivery group. This example uses \`useDeliveryGroup\` to access the first group and renders the selected option's title. ##### jsx ```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} ); } ``` * #### ##### Description Render information alongside a specific shipping option. This example reads \`shopify.target\` for the option details and \`shopify.isTargetSelected\` for the buyer's selection state. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const shippingOption = shopify.target.value; const isTargetSelected = shopify.isTargetSelected.value; const title = shippingOption.title; return ( Shipping method: {title} is{' '} {isTargetSelected ? '' : 'not'} selected. ); } ``` * #### ##### Description Display the selected pickup location's title when the buyer chooses it. This example reads \`shopify.target\` for the location details and \`shopify.isTargetSelected\` to conditionally render. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const pickupLocation = shopify.target.value; const isTargetSelected = shopify.isTargetSelected.value; const title = pickupLocation?.title; if (isTargetSelected) { return {title}; } return null; } ``` * #### ##### Description Check whether the buyer is being asked to provide their location. This example reads \`shopify.isLocationFormVisible\` and displays a different message depending on the form state. ##### jsx ```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. ); } } ``` * #### ##### Description Retrieve all delivery groups and their available options. This example iterates over \`shopify.deliveryGroups\` and displays the title of the first available delivery option. ##### jsx ```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} ); } ``` *** ## Best practices * **Check API availability for your target**: Not all extension targets implement all delivery APIs. Verify which APIs are available for your specific target before accessing them. * **Handle empty delivery groups**: Delivery groups might be empty early in checkout before the buyer enters a shipping address. Always check that the array has items before accessing elements. ***