Delivery

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.

Delivery group

import {
  reactExtension,
  Banner,
  useDeliveryGroups,
  useDeliveryGroup,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const deliveryGroups = useDeliveryGroups();
  const {
    selectedDeliveryOption,
    targetedCartLines,
  } = useDeliveryGroup(deliveryGroups[0]);

  return (
    <Banner>
      Selected delivery option:{' '}
      {selectedDeliveryOption?.title}
    </Banner>
  );
}

StandardApi

The base API object provided to `purchase`, and `customer-account.order-status` extension targets.

Docs_Standard_DeliveryApi

deliveryGroups

A list of delivery groups containing information about the delivery of the items the customer intends to purchase.

DeliveryGroup

Represents the delivery information and options available for one or more cart lines.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

targetedCartLines

The cart line references associated to the delivery group.

deliveryOptions

The delivery options available for the delivery group.

selectedDeliveryOption

The selected delivery option for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLineReference

Represents a reference to a cart line.

id

The unique identifier of the referenced cart line.

DeliveryOption

ShippingOption | PickupPointOption | PickupLocationOption

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

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

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

PickupPointOption

type

The type of this delivery option.

carrier

Information about the carrier that ships to the pickup point.

cost

The cost to ship to this pickup point.

costAfterDiscounts

The cost to ship to this pickup point including discounts.

location

The location details of the pickup point.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupPointCarrier

code

The code identifying the carrier.

name

The name of the carrier.

PickupPointLocation

name

The name of the pickup point.

handle

The unique identifier of the pickup point.

address

The address of the pickup point.

MailingAddress

name

The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

firstName

The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

lastName

The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company

The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address1

The first line of the buyer's address, including street name and number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address2

The second line of the buyer's address, like apartment number, suite, etc. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

city

The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

zip

The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

countryCode

The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

provinceCode

The buyer's province code, such as state, province, prefecture, or region. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

phone

The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

CountryCode

'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

type

The type of this delivery option.

location

The location details of the pickup location.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupLocation

name

The name of the pickup location.

address

The address of the pickup location.

DeliveryOptionReference

Represents a reference to a delivery option.

handle

The unique identifier of the referenced delivery option.

DeliveryGroupType

The possible types of a delivery group.

'oneTimePurchase' | 'subscription'

useDeliveryGroup

Returns the full expanded details of a delivery group and automatically re-renders your component when that delivery group changes.

UseDeliveryGroupGeneratedType

Returns the full expanded details of a delivery group and automatically re-renders your component when that delivery group changes.

Returns: DeliveryGroupDetails

Params:

deliveryGroup: DeliveryGroup

export function useDeliveryGroup< ID extends RenderExtensionTarget = RenderExtensionTarget, >(deliveryGroup: DeliveryGroup): DeliveryGroupDetails { const {lines} = useApi<ID>(); const cartLines = useSubscription(lines); return useMemo(() => { if (!deliveryGroup) { throw new DeliveryGroupHookError( 'useDeliveryGroup must be called with a delivery group from the useDeliveryGroups hook', ); } const deliveryGroupDetails = { ...deliveryGroup, selectedDeliveryOption: getSelectedDeliveryOption(deliveryGroup), targetedCartLines: getTargetedCartLines(deliveryGroup, cartLines), }; return deliveryGroupDetails; }, [deliveryGroup, cartLines]); }

DeliveryGroup

Represents the delivery information and options available for one or more cart lines.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

targetedCartLines

The cart line references associated to the delivery group.

deliveryOptions

The delivery options available for the delivery group.

selectedDeliveryOption

The selected delivery option for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLineReference

Represents a reference to a cart line.

id

The unique identifier of the referenced cart line.

DeliveryOption

ShippingOption | PickupPointOption | PickupLocationOption

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

PickupPointOption

type

The type of this delivery option.

carrier

Information about the carrier that ships to the pickup point.

cost

The cost to ship to this pickup point.

costAfterDiscounts

The cost to ship to this pickup point including discounts.

location

The location details of the pickup point.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupPointCarrier

code

The code identifying the carrier.

name

The name of the carrier.

PickupPointLocation

name

The name of the pickup point.

handle

The unique identifier of the pickup point.

address

The address of the pickup point.

MailingAddress

name

The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

firstName

The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

lastName

The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company

The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address1

address2

city

The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

zip

The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

countryCode

provinceCode

phone

The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

CountryCode

PickupLocationOption

type

The type of this delivery option.

location

The location details of the pickup location.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupLocation

name

The name of the pickup location.

address

The address of the pickup location.

DeliveryOptionReference

Represents a reference to a delivery option.

handle

The unique identifier of the referenced delivery option.

DeliveryGroupType

The possible types of a delivery group.

'oneTimePurchase' | 'subscription'

DeliveryGroupDetails

Represents a DeliveryGroup with expanded reference fields and full details.

selectedDeliveryOption

The selected delivery option for the delivery group.

targetedCartLines

The cart lines associated to the delivery group.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

deliveryOptions

The delivery options available for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLine

id

These line item IDs are not stable at the moment, they might change after any operations on the line items. You should always look up for an updated ID before any call to `applyCartLinesChange` because you'll need the ID to create a `CartLineChange` object.

merchandise

The merchandise being purchased.

quantity

The quantity of the merchandise being purchased.

cost

The details about the cost components attributed to the cart line.

attributes

The line item additional custom attributes.

discountAllocations

Discounts applied to the cart line.

lineComponents

Sub lines of the merchandise line. If no sub lines are present, this will be an empty array.

Merchandise

type

id

A globally-unique identifier.

title

The product variant’s title.

subtitle

The product variant's subtitle.

image

Image associated with the product variant. This field falls back to the product image if no image is available.

selectedOptions

List of product options applied to the variant.

product

The product object that the product variant belongs to.

requiresShipping

Whether or not the product requires shipping.

sellingPlan

The selling plan associated with the merchandise.

ImageDetails

url

The image URL.

altText

The alternative text for the image.

SelectedOption

name

The name of the merchandise option.

value

The value of the merchandise option.

Product

id

A globally-unique identifier.

vendor

The product’s vendor name.

productType

A categorization that a product can be tagged with, commonly used for filtering and searching.

SellingPlan

id

A globally-unique identifier.

CartLineCost

totalAmount

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

Attribute

key

The key for the attribute.

value

The value for the attribute.

CartDiscountAllocation

CartCodeDiscountAllocation | CartAutomaticDiscountAllocation | CartCustomDiscountAllocation

CartCodeDiscountAllocation

code

The code for the discount

type

The type of the code discount

discountedAmount

The money amount that has been discounted from the order

CartAutomaticDiscountAllocation

title

The title of the automatic discount

type

The type of the automatic discount

discountedAmount

The money amount that has been discounted from the order

CartCustomDiscountAllocation

title

The title of the custom discount

type

The type of the custom discount

discountedAmount

The money amount that has been discounted from the order

CartBundleLineComponent

type

id

A unique identifier for the bundle line component. This ID is not stable. If an operation updates the line items in any way, all IDs could change.

merchandise

The merchandise of this bundle line component.

quantity

The quantity of merchandise being purchased.

cost

The cost attributed to this bundle line component.

attributes

Additional custom attributes for the bundle line component.

useDeliveryGroups

Returns the current delivery groups for the checkout, and automatically re-renders your component when delivery address or delivery option selection changes.

UseDeliveryGroupsGeneratedType

Returns the current delivery groups for the checkout, and automatically re-renders your component when delivery address or delivery option selection changes.

Returns: DeliveryGroup[]

export function useDeliveryGroups< Target extends RenderExtensionTarget = RenderExtensionTarget, >(): DeliveryGroup[] { const api = useApi<Target>(); if (!('deliveryGroups' in api)) { throw new ExtensionHasNoMethodError('deliveryGroups', api.extension.target); } return useSubscription(api.deliveryGroups); }

DeliveryGroup

Represents the delivery information and options available for one or more cart lines.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

targetedCartLines

The cart line references associated to the delivery group.

deliveryOptions

The delivery options available for the delivery group.

selectedDeliveryOption

The selected delivery option for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLineReference

Represents a reference to a cart line.

id

The unique identifier of the referenced cart line.

DeliveryOption

ShippingOption | PickupPointOption | PickupLocationOption

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

PickupPointOption

type

The type of this delivery option.

carrier

Information about the carrier that ships to the pickup point.

cost

The cost to ship to this pickup point.

costAfterDiscounts

The cost to ship to this pickup point including discounts.

location

The location details of the pickup point.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupPointCarrier

code

The code identifying the carrier.

name

The name of the carrier.

PickupPointLocation

name

The name of the pickup point.

handle

The unique identifier of the pickup point.

address

The address of the pickup point.

MailingAddress

name

The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

firstName

The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

lastName

The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company

The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address1

address2

city

The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

zip

The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

countryCode

provinceCode

phone

The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

CountryCode

PickupLocationOption

type

The type of this delivery option.

location

The location details of the pickup location.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupLocation

name

The name of the pickup location.

address

The address of the pickup location.

DeliveryOptionReference

Represents a reference to a delivery option.

handle

The unique identifier of the referenced delivery option.

DeliveryGroupType

The possible types of a delivery group.

'oneTimePurchase' | 'subscription'

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.

ShippingOptionItemApi

target

The shipping option the extension is attached to.

isTargetSelected

Whether the shipping option the extension is attached to is currently selected in the UI.

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

useShippingOptionTarget

Returns the shipping option for the `purchase.checkout.shipping-option-item.render-after` and `purchase.checkout.shipping-option-item.details.render` attached extensions

UseShippingOptionTargetGeneratedType

Returns the shipping option the extension is attached to. This hook can only be used by extensions in the following extension targets: - `purchase.checkout.shipping-option-item.render-after` - `purchase.checkout.shipping-option-item.details.render`

Returns: { shippingOptionTarget: ShippingOption; isTargetSelected: boolean; }

export function useShippingOptionTarget(): { shippingOptionTarget: ShippingOption; isTargetSelected: boolean; } { const api = useApi< | 'purchase.checkout.shipping-option-item.render-after' | 'purchase.checkout.shipping-option-item.details.render' >(); if (!api.target || api.isTargetSelected === undefined) { throw new ExtensionHasNoTargetError( 'useShippingOptionTarget', api.extension.target, ); } const shippingOptionTarget = useSubscription(api.target); const isTargetSelected = useSubscription(api.isTargetSelected); const shippingOption = useMemo(() => { return { shippingOptionTarget, isTargetSelected, }; }, [shippingOptionTarget, isTargetSelected]); return shippingOption; }

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

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.

ShippingOptionListApi

target

The delivery group the extension is attached to. The target will be undefined if the group is not available.

DeliveryGroup

Represents the delivery information and options available for one or more cart lines.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

targetedCartLines

The cart line references associated to the delivery group.

deliveryOptions

The delivery options available for the delivery group.

selectedDeliveryOption

The selected delivery option for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLineReference

Represents a reference to a cart line.

id

The unique identifier of the referenced cart line.

DeliveryOption

ShippingOption | PickupPointOption | PickupLocationOption

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

PickupPointOption

type

The type of this delivery option.

carrier

Information about the carrier that ships to the pickup point.

cost

The cost to ship to this pickup point.

costAfterDiscounts

The cost to ship to this pickup point including discounts.

location

The location details of the pickup point.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupPointCarrier

code

The code identifying the carrier.

name

The name of the carrier.

PickupPointLocation

name

The name of the pickup point.

handle

The unique identifier of the pickup point.

address

The address of the pickup point.

MailingAddress

name

The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

firstName

The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

lastName

The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company

The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address1

address2

city

The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

zip

The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

countryCode

provinceCode

phone

The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

CountryCode

PickupLocationOption

type

The type of this delivery option.

location

The location details of the pickup location.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupLocation

name

The name of the pickup location.

address

The address of the pickup location.

DeliveryOptionReference

Represents a reference to a delivery option.

handle

The unique identifier of the referenced delivery option.

DeliveryGroupType

The possible types of a delivery group.

'oneTimePurchase' | 'subscription'

useDeliveryGroupTarget

Returns the delivery group for the `purchase.checkout.shipping-option-list.render-before` and `purchase.checkout.shipping-option-list.render-after` attached extensions.

UseDeliveryGroupTargetGeneratedType

Returns the delivery group the extension is attached to. This hook can only be used by extensions in the following extension targets: - purchase.checkout.shipping-option-list.render-before - purchase.checkout.shipping-option-list.render-after

Returns: DeliveryGroup | undefined

export function useDeliveryGroupTarget(): DeliveryGroup | undefined { const api = useApi< | 'purchase.checkout.shipping-option-list.render-before' | 'purchase.checkout.shipping-option-list.render-after' >(); return useSubscription(api.target); }

DeliveryGroup

Represents the delivery information and options available for one or more cart lines.

id

The unique identifier of the delivery group. On the Thank You page this value is undefined.

targetedCartLines

The cart line references associated to the delivery group.

deliveryOptions

The delivery options available for the delivery group.

selectedDeliveryOption

The selected delivery option for the delivery group.

groupType

The type of the delivery group.

isDeliveryRequired

Whether delivery is required for the delivery group.

CartLineReference

Represents a reference to a cart line.

id

The unique identifier of the referenced cart line.

DeliveryOption

ShippingOption | PickupPointOption | PickupLocationOption

ShippingOption

Represents a delivery option that is a shipping option.

type

The type of this delivery option.

carrier

Information about the carrier.

cost

The cost of the delivery.

costAfterDiscounts

The cost of the delivery including discounts.

deliveryEstimate

Information about the estimated delivery time.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

ShippingOptionCarrier

name

The name of the carrier.

Money

amount

The price amount.

currencyCode

The ISO 4217 format for the currency.

CurrencyCode

DeliveryEstimate

timeInTransit

The estimated time in transit for the delivery in seconds.

NumberRange

lower

The lower bound of the number range.

upper

The upper bound of the number range.

PickupPointOption

type

The type of this delivery option.

carrier

Information about the carrier that ships to the pickup point.

cost

The cost to ship to this pickup point.

costAfterDiscounts

The cost to ship to this pickup point including discounts.

location

The location details of the pickup point.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupPointCarrier

code

The code identifying the carrier.

name

The name of the carrier.

PickupPointLocation

name

The name of the pickup point.

handle

The unique identifier of the pickup point.

address

The address of the pickup point.

MailingAddress

name

The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

firstName

The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

lastName

The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company

The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

address1

address2

city

The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

zip

The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

countryCode

provinceCode

phone

The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

CountryCode

PickupLocationOption

type

The type of this delivery option.

location

The location details of the pickup location.

handle

The unique identifier of the delivery option.

title

The title of the delivery option.

description

The description of the delivery option.

code

The code of the delivery option.

PickupLocation

name

The name of the pickup location.

address

The address of the pickup location.

DeliveryOptionReference

Represents a reference to a delivery option.

handle

The unique identifier of the referenced delivery option.

DeliveryGroupType

The possible types of a delivery group.

'oneTimePurchase' | 'subscription'

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.

PickupPointListApi

isLocationFormVisible

Whether the customer location input form is shown to the buyer.

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.

PickupLocationListApi

isLocationFormVisible

Whether the customer location input form is shown to the buyer.

Examples

Reading the selected shipping option

import {
  reactExtension,
  Text,
  useSubscription,
  useShippingOptionTarget,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-item.render-after',
  () => <Extension />,
);

function Extension() {
  const {shippingOptionTarget, isTargetSelected} =
    useShippingOptionTarget();
  const title = shippingOptionTarget.title;

  return (
    <Text>
      Shipping method: {title} is{' '}
      {isTargetSelected ? '' : 'not'} selected.
    </Text>
  );
}

import {extension} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-item.render-after',
  (root, {target, isTargetSelected}) => {
    const titleText = root.createText(
      `Shipping method title: ${target.current.title}`,
    );
    root.appendChild(titleText);

    target.subscribe((updatedTarget) => {
      titleText.updateText(
        `Shipping method title: ${updatedTarget.title}`,
      );
    });

    const selectedText = root.createText(
      getSelectedText(isTargetSelected),
    );
    root.appendChild(selectedText);

    isTargetSelected.subscribe(
      (updatedSelected) => {
        selectedText.updateText(
          getSelectedText(updatedSelected),
        );
      },
    );

    function getSelectedText(selected) {
      return selected
        ? 'Selected'
        : 'Not selected';
    }
  },
);

Reading the selected shipping option

import {
  reactExtension,
  Text,
  useSubscription,
  useShippingOptionTarget,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.shipping-option-item.render-after',
  () => <Extension />,
);

function Extension() {
  const {shippingOptionTarget, isTargetSelected} =
    useShippingOptionTarget();
  const title = shippingOptionTarget.title;

  return (
    <Text>
      Shipping method: {title} is{' '}
      {isTargetSelected ? '' : 'not'} selected.
    </Text>
  );
}

import {extension} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.shipping-option-item.render-after',
  (root, {target, isTargetSelected}) => {
    const titleText = root.createText(
      `Shipping method title: ${target.current.title}`,
    );
    root.appendChild(titleText);

    target.subscribe((updatedTarget) => {
      titleText.updateText(
        `Shipping method title: ${updatedTarget.title}`,
      );
    });

    const selectedText = root.createText(
      getSelectedText(isTargetSelected),
    );
    root.appendChild(selectedText);

    isTargetSelected.subscribe(
      (updatedSelected) => {
        selectedText.updateText(
          getSelectedText(updatedSelected),
        );
      },
    );

    function getSelectedText(selected) {
      return selected
        ? 'Selected'
        : 'Not selected';
    }
  },
);

Determine if the location input form is shown

import {
  reactExtension,
  useApi,
  useSubscription,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.pickup-point-list.render-before',
  () => <Extension />,
);

function Extension() {
  const {isLocationFormVisible} =
    useApi<'purchase.checkout.pickup-point-list.render-before'>();

  const locationFormShown = useSubscription(
    isLocationFormVisible,
  );

  if (locationFormShown) {
    return (
      <Text>
        The customer is being asked to provide
        their location.
      </Text>
    );
  } else {
    return (
      <Text>Pickup points are being shown.</Text>
    );
  }
}

import {extension} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.pickup-point-list.render-before',
  (root, {isLocationFormVisible}) => {
    const content = root.createText(
      getTextContent(
        isLocationFormVisible.current,
      ),
    );
    root.appendChild(content);

    isLocationFormVisible.subscribe(
      (updatedLocationFormVisible) => {
        content.updateText(
          getTextContent(
            updatedLocationFormVisible,
          ),
        );
      },
    );

    function getTextContent(
      isLocationFormVisible,
    ) {
      if (isLocationFormVisible) {
        return 'The customer is being asked to provide their location.';
      } else {
        return 'Pickup points are being shown.';
      }
    }
  },
);

Determine if the location input form is shown

import {
  reactExtension,
  useApi,
  useSubscription,
  Text,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.pickup-point-list.render-before',
  () => <Extension />,
);

function Extension() {
  const {isLocationFormVisible} =
    useApi<'purchase.checkout.pickup-point-list.render-before'>();

  const locationFormShown = useSubscription(
    isLocationFormVisible,
  );

  if (locationFormShown) {
    return (
      <Text>
        The customer is being asked to provide
        their location.
      </Text>
    );
  } else {
    return (
      <Text>Pickup points are being shown.</Text>
    );
  }
}

import {extension} from '@shopify/ui-extensions/checkout';

export default extension(
  'purchase.checkout.pickup-point-list.render-before',
  (root, {isLocationFormVisible}) => {
    const content = root.createText(
      getTextContent(
        isLocationFormVisible.current,
      ),
    );
    root.appendChild(content);

    isLocationFormVisible.subscribe(
      (updatedLocationFormVisible) => {
        content.updateText(
          getTextContent(
            updatedLocationFormVisible,
          ),
        );
      },
    );

    function getTextContent(
      isLocationFormVisible,
    ) {
      if (isLocationFormVisible) {
        return 'The customer is being asked to provide their location.';
      } else {
        return 'Pickup points are being shown.';
      }
    }
  },
);

Delivery groups

import {
  reactExtension,
  Banner,
  useDeliveryGroups,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const deliveryGroups = useDeliveryGroups();
  const deliveryOptions =
    deliveryGroups[0].deliveryOptions;

  return (
    <Banner>
      First delivery option:{' '}
      {deliveryOptions[0].title}
    </Banner>
  );
}

Delivery groups

import {
  reactExtension,
  Banner,
  useDeliveryGroups,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  const deliveryGroups = useDeliveryGroups();
  const deliveryOptions =
    deliveryGroups[0].deliveryOptions;

  return (
    <Banner>
      First delivery option:{' '}
      {deliveryOptions[0].title}
    </Banner>
  );
}