@shopify/ui-extensions 2023.4.2 → 2023.7.0

package/src/surfaces/checkout/api/standard/standard.ts

@@ -9,14 +9,15 @@ import type {
   ValidationError,
   SellingPlan,
   Attribute,
+  MailingAddress,
 } from '../shared';
-import type {ExtensionPoint} from '../../extension-points';
+import type {ExtensionTarget} from '../../targets';
 
 /**
- * A key-value storage object for extension points.
+ * A key-value storage object for extension targets.
  *
  * Stored data is only available to this specific app
- * at this specific extension point.
+ * at this specific extension target.
  *
  * The storage backend is implemented with `localStorage` and
  * should persist across the buyer's checkout session.
@@ -58,40 +59,34 @@ export interface Storage {
 export type Capability = 'api_access' | 'network_access' | 'block_progress';
 
 /**
- * Meta information about an extension point.
+ * Meta information about an extension target.
  */
-export interface Extension<Target extends ExtensionPoint = ExtensionPoint> {
+export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
   /**
-   * The identifier that specifies where in Shopify’s UI your code is being
-   * injected. This will be one of the targets you have included in your
-   * extension’s configuration file.
+   * The API version that was set in the extension config file.
    *
-   * @example 'Checkout::Dynamic::Render'
-   * @see https://shopify.dev/docs/api/checkout-ui-extensions/unstable/extension-targets-overview
-   * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
+   * @example '2023-04', '2023-07'
    */
-  target: Target;
+  apiVersion: ApiVersion;
 
   /**
-   * The published version of the running extension point.
+   * The allowed capabilities of the extension, defined
+   * in your [shopify.extension.toml](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
    *
-   * For unpublished extensions, the value is `undefined`.
+   * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API.
    *
-   * @example 3.0.10
-   */
-  version?: string;
-
-  /**
-   * The API version that was set in the extension config file.
+   * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
    *
-   * @example '2023-04'
+   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
    */
-  apiVersion: ApiVersion;
+  capabilities: StatefulRemoteSubscribable<Capability[]>;
 
   /**
-   * The URL to the script that started the extension point.
+   * Information about the editor where the extension is being rendered.
+   *
+   * The value is undefined if the extension is not rendering in an editor.
    */
-  scriptUrl: string;
+  editor?: Editor;
 
   /**
    * Whether your extension is currently rendered to the screen.
@@ -107,23 +102,29 @@ export interface Extension<Target extends ExtensionPoint = ExtensionPoint> {
   rendered: StatefulRemoteSubscribable<boolean>;
 
   /**
-   * The allowed capabilities of the extension, defined
-   * in your [shopify.ui.extension.toml](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
-   *
-   * * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API.
-   *
-   * * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls.
+   * The URL to the script that started the extension target.
+   */
+  scriptUrl: string;
+
+  /**
+   * The identifier that specifies where in Shopify’s UI your code is being
+   * injected. This will be one of the targets you have included in your
+   * extension’s configuration file.
    *
-   * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
+   * @example 'purchase.checkout.block.render'
+   * @see https://shopify.dev/docs/api/checkout-ui-extensions/unstable/extension-targets-overview
+   * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
    */
-  capabilities: StatefulRemoteSubscribable<Capability[]>;
+  target: Target;
 
   /**
-   * Information about the editor where the extension is being rendered.
+   * The published version of the running extension target.
    *
-   * The value is undefined if the extension is not rendering in an editor.
+   * For unpublished extensions, the value is `undefined`.
+   *
+   * @example 3.0.10
    */
-  editor?: Editor;
+  version?: string;
 }
 
 export interface Editor {
@@ -179,6 +180,23 @@ export interface AppMetafield {
   type: string;
 }
 
+/**
+ * Represents a custom metadata attached to a resource.
+ */
+export interface CartMetafield {
+  /** The key name of a metafield. */
+  key: string;
+
+  /** The namespace for a metafield. */
+  namespace: string;
+
+  /** The value of a metafield. */
+  value: string;
+
+  /** The metafield's type name. */
+  type: string;
+}
+
 /**
  * The metafield owner.
  */
@@ -186,7 +204,7 @@ export interface AppMetafieldEntryTarget {
   /**
    * The type of the metafield owner.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`.
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
    */
   type:
     | 'customer'
@@ -208,7 +226,7 @@ export interface AppMetafieldEntry {
   /**
    * The target that is associated to the metadata.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`.
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`.
    */
   target: AppMetafieldEntryTarget;
 
@@ -216,7 +234,7 @@ export interface AppMetafieldEntry {
   metafield: AppMetafield;
 }
 
-export type ApiVersion = '2023-04' | 'unstable';
+export type ApiVersion = '2023-04' | '2023-07' | 'unstable';
 
 export type Version = string;
 
@@ -399,7 +417,7 @@ export interface BuyerJourney {
   completed: StatefulRemoteSubscribable<boolean>;
 }
 
-export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
+export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
    */
@@ -412,7 +430,7 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
 
   /**
    * The metafields requested in the
-   * [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
+   * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)
    * file. These metafields are updated when there's a change in the merchandise items
    * being purchased by the customer.
    *
@@ -445,6 +463,11 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
    */
   buyerJourney: BuyerJourney;
 
+  /**
+   * Settings applied to the buyer's checkout.
+   */
+  checkoutSettings: StatefulRemoteSubscribable<CheckoutSettings>;
+
   /**
    * Details on the costs the buyer will pay for this checkout.
    */
@@ -475,11 +498,13 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
    * injected. This will be one of the targets you have included in your
    * extension’s configuration file.
    *
-   * @example 'Checkout::Dynamic::Render'
+   * @example 'purchase.checkout.block.render'
    * @see https://shopify.dev/docs/api/checkout-ui-extensions/unstable/extension-targets-overview
    * @see https://shopify.dev/docs/apps/app-extensions/configuration#targets
+   *
+   * @deprecated Deprecated as of version `2023-07`, use `extension.target` instead.
    */
-  extensionPoint: ExtensionPoint;
+  extensionPoint: Target;
 
   /**
    * Utilities for translating content and formatting values according to the current
@@ -529,11 +554,6 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
    */
   note: StatefulRemoteSubscribable<string | undefined>;
 
-  /**
-   * A list of the line items displayed in the checkout. These may be the same as lines, or may be a subset.
-   */
-  presentmentLines: StatefulRemoteSubscribable<PresentmentCartLine[]>;
-
   /**
    * Used to query the Storefront GraphQL API with a prefetched token.
    *
@@ -558,7 +578,7 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
 
   /**
    * The settings matching the settings definition written in the
-   * [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
+   * [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file.
    *
    *  See [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#example-settings) for more information.
    *
@@ -581,7 +601,7 @@ export interface StandardApi<Target extends ExtensionPoint = ExtensionPoint> {
   shop: Shop;
 
   /**
-   * Key-value storage for the extension point.
+   * Key-value storage for the extension target.
    */
   storage: Storage;
 
@@ -638,144 +658,112 @@ export interface BuyerIdentity {
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   phone: StatefulRemoteSubscribable<string | undefined>;
-}
 
-export interface AppliedGiftCard {
   /**
-   * The last four characters of the applied gift card's code.
+   * Provides details of the company and the company location that the business customer is purchasing on behalf of.
+   * This includes information that can be used to identify the company and the company location that the business
+   * customer belongs to.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  lastCharacters: string;
+  purchasingCompany: StatefulRemoteSubscribable<PurchasingCompany | undefined>;
+}
 
+/**
+ * Information about a company that the business customer is purchasing on behalf of.
+ */
+export interface PurchasingCompany {
   /**
-   * The amount of the applied gift card that will be used when the checkout is completed.
+   * Includes information of the company that the business customer is purchasing on behalf of.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  amountUsed: Money;
-
+  company: Company;
   /**
-   * The current balance of the applied gift card prior to checkout completion.
+   * Includes information of the company location that the business customer is purchasing on behalf of.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  balance: Money;
+  location: CompanyLocation;
 }
 
-export interface Shop {
+export interface Company {
   /**
-   * The shop ID.
-   * @example 'gid://shopify/Shop/123'
+   * The company ID.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   id: string;
   /**
-   * The name of the shop.
+   * The name of the company.
+   *
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
   name: string;
   /**
-   * The primary storefront URL.
-   */
-  storefrontUrl?: string;
-  /**
-   * The shop's myshopify.com domain.
-   */
-  myshopifyDomain: string;
-}
-
-export interface MailingAddress {
-  /**
-   * 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).
+   * The external ID of the company that can be set by the merchant.
    *
-   * @example 'John Doe'
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  name?: string;
+  externalId?: string;
+}
 
+export interface CompanyLocation {
   /**
-   * The buyer's first name.
+   * The company location ID.
    *
-   * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
-   *
-   * @example 'John'
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  firstName?: string;
-
+  id: string;
   /**
-   * 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).
+   * The name of the company location.
    *
-   * @example 'Doe'
+   * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  lastName?: string;
-
+  name: string;
   /**
-   * The buyer's company name.
+   * The external ID of the company location that can be set by the merchant.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
-   *
-   * @example 'Shopify'
    */
-  company?: string;
+  externalId?: string;
+}
 
+export interface AppliedGiftCard {
   /**
-   * 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).
-   *
-   * @example '151 O'Connor Street'
+   * The last four characters of the applied gift card's code.
    */
-  address1?: string;
+  lastCharacters: string;
 
   /**
-   * 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).
-   *
-   * @example 'Ground floor'
+   * The amount of the applied gift card that will be used when the checkout is completed.
    */
-  address2?: string;
+  amountUsed: Money;
 
   /**
-   * 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).
-   *
-   * @example 'Ottawa'
+   * The current balance of the applied gift card prior to checkout completion.
    */
-  city?: string;
+  balance: Money;
+}
 
+export interface Shop {
   /**
-   * 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).
-   *
-   * @example 'K2P 2L8'
+   * The shop ID.
+   * @example 'gid://shopify/Shop/123'
    */
-  zip?: string;
-
+  id: string;
   /**
-   * 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).
-   *
-   * @example 'CA' for Canada.
+   * The name of the shop.
    */
-  countryCode?: CountryCode;
-
+  name: string;
   /**
-   * The buyer's zone 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).
-   *
-   * @example 'ON' for Ontario.
+   * The primary storefront URL.
    */
-  provinceCode?: string;
-
+  storefrontUrl?: string;
   /**
-   * 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).
-   *
-   * @example '+1 613 111 2222'.
+   * The shop's myshopify.com domain.
    */
-  phone?: string;
+  myshopifyDomain: string;
 }
 
 export interface CartCost {
@@ -981,52 +969,6 @@ export interface SelectedOption {
   value: string;
 }
 
-export interface PresentmentCartLine {
-  /**
-   * The ID of the present cart line. This ID isn't stable and might change after
-   * any operations on the line items.
-   * @example 'gid://shopify/PresentmentCartLine/123'
-   */
-  id: string;
-
-  /**
-   * The quantity of the merchandise being purchased.
-   */
-  quantity: number;
-
-  /**
-   * The details about the cost components attributed to the presentment cart line.
-   */
-  cost: PresentmentCartLineCost;
-
-  /**
-   * The title of the line item.
-   */
-  title: string;
-
-  /**
-   * The subtitle of the line item.
-   */
-  subtitle?: string;
-
-  /**
-   * The image associated with the line item.
-   */
-  image?: ImageDetails;
-
-  /**
-   * The merchandise lines being purchased.
-   */
-  lines: CartLine[];
-}
-
-export interface PresentmentCartLineCost {
-  /**
-   * The total cost of the merchandise line.
-   */
-  totalAmount: Money;
-}
-
 /**
  * A payment option presented to the buyer.
  */
@@ -1076,7 +1018,7 @@ export interface SelectedPaymentOption {
   /**
    * The unique handle referencing `PaymentOption.handle`.
    *
-   * See [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/apis/standardapi#properties-propertydetail-availablepaymentoptions).
+   * See [availablePaymentOptions](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-availablepaymentoptions).
    */
   handle: string;
 }
@@ -1286,6 +1228,57 @@ export interface Customer {
   storeCreditAccounts: StoreCreditAccount[];
 }
 
+/**
+ * Settings describing the behavior of the buyer's checkout.
+ */
+export interface CheckoutSettings {
+  /**
+   * The type of order that will be created once the buyer completes checkout.
+   */
+  orderSubmission: 'DRAFT_ORDER' | 'ORDER';
+  /**
+   * Represents the merchant configured payment terms.
+   */
+  paymentTermsTemplate?: PaymentTermsTemplate;
+  /**
+   * Settings describing the behavior of the shipping address.
+   */
+  shippingAddress: ShippingAddressSettings;
+}
+
+/**
+ * Settings describing the behavior of the shipping address.
+ */
+export interface ShippingAddressSettings {
+  /**
+   * Describes whether the buyer can ship to any address during checkout.
+   */
+  isEditable: boolean;
+}
+
+/**
+ * Represents the payment terms template object.
+ */
+export interface PaymentTermsTemplate {
+  /**
+   * A globally-unique ID.
+   * @example 'gid://shopify/PaymentTermsTemplate/1'
+   */
+  id: string;
+  /**
+   * The name of the payment terms translated to the buyer's current language. See [localization.language](https://shopify.dev/docs/api/checkout-ui-extensions/apis/standardapi#properties-propertydetail-localization).
+   */
+  name: string;
+  /**
+   * The due date for net payment terms as a ISO 8601 formatted string `YYYY-MM-DDTHH:mm:ss.sssZ`.
+   */
+  dueDate?: string;
+  /**
+   * The number of days between the issued date and due date if using net payment terms.
+   */
+  dueInDays?: number;
+}
+
 /**
  * Information about a Store Credit Account.
  */
@@ -1343,7 +1336,7 @@ export interface DeliveryGroup {
   /**
    * Whether delivery is required for the delivery group.
    */
-  deliveryRequired: boolean;
+  isDeliveryRequired: boolean;
 }
 
 /**

package/src/surfaces/checkout/api.ts

@@ -5,6 +5,7 @@ export type {
   Capability,
   CartCost,
   CartLineCost,
+  CheckoutSettings,
   Customer,
   Editor,
   Extension,
@@ -15,6 +16,7 @@ export type {
   ImageDetails,
   Product,
   ProductVariant,
+  PurchasingCompany,
   SelectedOption,
   SessionToken,
   Money,
@@ -22,13 +24,11 @@ export type {
   Storage,
   Shop,
   Version,
-  MailingAddress,
   Metafield,
   AppMetafield,
   AppMetafieldEntryTarget,
   AppMetafieldEntry,
   CartLine,
-  PresentmentCartLine,
   PaymentOption,
   SelectedPaymentOption,
   CartDiscountCode,
@@ -63,16 +63,19 @@ export type {
   SellingPlan,
   StorefrontApiVersion,
   ValidationError,
+  MailingAddress,
 } from './api/shared';
 
 export type {
   RedeemableAttribute,
   RedeemableChange,
+  RedeemableAddChange,
   RedeemableChangeResult,
   RedeemableChangeResultError,
   RedeemableChangeResultSuccess,
-  RedeemableRenderApi,
-} from './api/redeemable/render';
+  RedeemableApi,
+} from './api/redeemable/redeemable';
+
 export type {
   AttributeChange,
   AttributeChangeResult,
@@ -107,14 +110,19 @@ export type {
   NoteChangeResult,
   NoteChangeResultSuccess,
   NoteChangeResultError,
+  ShippingAddressChange,
+  ShippingAddressChangeFieldError,
+  ShippingAddressChangeResult,
+  ShippingAddressChangeResultError,
+  ShippingAddressChangeResultSuccess,
   CheckoutApi,
 } from './api/checkout/checkout';
 export type {Order, OrderStatusApi} from './api/order-status/order-status';
 
-export type {CartLineDetailsApi} from './api/cart-line/cart-line-details';
-export type {PickupLocationsApi} from './api/pickup/pickup-locations';
-export type {PickupPointsApi} from './api/pickup/pickup-points';
-export type {ShippingMethodDetailsApi} from './api/shipping/shipping-method-details';
+export type {CartLineItemApi} from './api/cart-line/cart-line-item';
+export type {PickupLocationListApi} from './api/pickup/pickup-location-list';
+export type {PickupPointListApi} from './api/pickup/pickup-point-list';
+export type {ShippingOptionItemApi} from './api/shipping/shipping-option-item';
 
 export type {
   PaymentMethodAttributesResult,
@@ -123,5 +131,5 @@ export type {
   PaymentMethodAttribute,
   PaymentMethodAttributesChange,
   PaymentMethodAttributesUpdateChange,
-  PaymentMethodRenderApi,
-} from './api/payment-method/render';
+  PaymentOptionItemApi,
+} from './api/payment/payment-option-item';

package/src/surfaces/checkout/components/Banner/examples/basic-banner.example.ts

@@ -1,6 +1,6 @@
 import {extension, Banner} from '@shopify/ui-extensions/checkout';
 
-extension('Checkout::Dynamic::Render', (root) => {
+export default extension('purchase.checkout.block.render', (root) => {
   const banner = root.createComponent(Banner, {
     status: 'critical',
     title:

package/src/surfaces/checkout/components/BlockLayout/examples/basic-blockLayout.example.ts

@@ -1,6 +1,6 @@
 import {extension, BlockLayout, View} from '@shopify/ui-extensions/checkout';
 
-extension('Checkout::Dynamic::Render', (root) => {
+export default extension('purchase.checkout.block.render', (root) => {
   const blockLayout = root.createComponent(
     BlockLayout,
     {

package/src/surfaces/checkout/components/BlockLayout/examples/basic-blocklayout.example.ts

@@ -1,6 +1,6 @@
 import {extension, BlockLayout, View} from '@shopify/ui-extensions/checkout';
 
-extension('Checkout::Dynamic::Render', (root) => {
+export default extension('purchase.checkout.block.render', (root) => {
   const blockLayout = root.createComponent(
     BlockLayout,
     {