Release Notes

24min
v2.10.0
This release adds an option to return expanded orders objects (OrderBig instead of OrderSmall) from the useOrders hook. To use, pass this configuration object to either the useOrders hook or the loadOrders method: useOrders({ includeDetails: true }). See additional documentation here.
v2.9.0
This release adds support for recurring prepaid subscriptions and an emptyCart method to the useCart hook.
v2.8.4
This release refactors the functionality added in v2.8.2 around the <ChordProvider/ > re-initializing. It fixes issues where page navigation changes could inadvertently recreate the application state and cause it to act unpredictibly. With this update, the state is created exactly once, when the app initializes, and any subsequent updates to it will not cause it to be created again.
v2.8.3
This release adds support for Chord's update prepaid subscription redemption methods. You can now setup your storefront to have prepaid subscription redeemable via redemption code, right in time for the holiday season!
v2.8.2
This PR fixes a case where any re-render of the <ChordProvider> component caused a re-initialization of the application state. Now, the application state is only re-initialized when one of the <ChordProvider> props changes. The config param object doesn't need to be memoized before passing to <ChordProvider>, because we're doing a deep equal check, but any functions that are part of the config param should be.
v2.8.1
This PR updates useCart hook methods to return the current cart object. This makes complex interactions with this hook much easier to orchestrate in user space code. For example:
JS
import { useEffect } from 'react'
import { useCart, useAnalytics } from '@chordcommerce/react-autonomy'

const ImpliedCheckoutPage = ({ sku }) => {
  const { addToCart } = useCart()
  const { trackCartViewed } = useAnalytics()

  useEffect(() => {
    addToCart({ sku, quantity: 1 }).then((cart) => trackCartViewed({
      products: cart.lineItems,
    }))
  }, [sku])
}
import { useEffect } from 'react'
import { useCart, useAnalytics } from '@chordcommerce/react-autonomy'

const ImpliedCheckoutPage = ({ sku }) => {
  const { addToCart } = useCart()
  const { trackCartViewed } = useAnalytics()

  useEffect(() => {
    addToCart({ sku, quantity: 1 }).then((cart) => trackCartViewed({
      products: cart.lineItems,
    }))
  }, [sku])
}
﻿
Without this, we would need multiple useEffects listening to the changes in cart, which may not coincide with the item being added to the cart (i.e. a promo code being added in this above component could cause the event to fire twice).
v2.8.0
Adds checkRedemptionCodeValidity, redeemGiftCard, and redeemPrepaidSubscription methods to the useCart hook.
v2.7.0
Adds a getPrice method to the useProduct hook.
v2.5.0
This release adds support for changing the product SKU and quantity of a subscription using the updateSubscription method.
v2.4.1
This release adds exports for the useOrder and useOrders hooks. Previously, these hooks existed but had to be imported from @chordcommerce/react-autonomy/dist. Now, these hooks can be imported like:
import { useOrder, useOrders } from '@chordcommerce/react-autonomy'
v2.4.0
This release had internal changes only.
v2.3.1
This release has fixes to the Segment events “Product Added”, “Subscription Cancelled”, “SubscriptionPaused”, “SubscriptionResumed”, and “SubscriptionSkipped”.
“Product Added” fixes
The “Product Added” event for subscriptions previously had an empty string for the url property. The url property is now consistent with other Segment events.
The “Product Added” event for subscriptions previously had the numeric product id for the product_id property. The product_id property is now the product slug, which is the value Chord uses for the product_id property in all other events.
The “Product Added” event for subscriptions previously used the product’s image miniUrl for the image_url property. The image_url property now defaults to first the largeUrl, then the smallUrl, and then the miniUrl, choosing the first one that’s available. This is the logic Chord uses for the image_url property in all other events.
The “Product Added” event for subscriptions previously could have an incorrect quantity property when, prior to the event, another subscription for the same SKU had been added to the cart. This has been fixed.
“Subscription Cancelled”, “SubscriptionPaused”, “SubscriptionResumed”, and “SubscriptionSkipped” fixes
Previously, if the optional products argument was not provided to the corresponding SDK methods, the products array in the Segment event would be empty. This fix uses the subscription line item details to populate the products array in the Segment event, so that if the optional products argument isn’t provided, some product data is still available in the Segment events.
v2.2.4
This release fixes a bug where SDK methods returned by the useAuth hook could cause a React component to re-render when the methods were listed in the dependency array of a useEffect hook.
v2.2.3
This release populates the coupon property of Segment events with the correct coupon. Prior to this release, if the coupon property referred to a specific line item or product (as in "Product Added", or the products array of "Order Completed"), the coupon property was always an empty string.
v2.2.2
This release fixes a bug where orders created after a user logged in (usually by placing an order, and then placing a second order immediately afterwards) were not always correctly associated with the user account prior to checking out and therefore didn't see applicable store credit. This was a race condition between establishing the user authentication session on the order confirmation page and creating a new order.
v2.2.1
This release adds two properties to the "Coupon Denied" Segment event, coupon_id and reason. "Coupon Denied" is sent when the addPromoCode method results in an error because the promo code is invalid. Chord's tracking plan indicates that the coupon_id property is required and the reason property is optional.
v2.2.0
This release adds an optional productUrlFormatter property to the <ChordProvider> config options. productUrlFormatter can be used to globally customize product URLs in Segment event payloads.
Example of using this option:
JS
import { ChordProvider } from '@chordcommerce/react-autonomy'

<ChordProvider
  config={{
    productUrlFormatter: product => {
      return product.url || `/products/${product.variant?.slug}`
    },
    ...
  }}
>
import { ChordProvider } from '@chordcommerce/react-autonomy'

<ChordProvider
  config={{
    productUrlFormatter: product => {
      return product.url || `/products/${product.variant?.slug}`
    },
    ...
  }}
>
﻿
Default behavior:
If productUrlFormatter is not provided by the user, the default productUrlFormatter (which behaves in a backwards-compatible way) is used:
TypeScript
(product: Product): string => {
  return product.url || ''
}
(product: Product): string => {
  return product.url || ''
}
﻿
v2.1.0
This release adds the getStockAvailability method to the useProduct hook. It can be used to check whether or not a given SKU is in stock and can be used like so:
TypeScript
import { useState, useEffect } from 'react'
import { useProduct } from '@chordcommerce/react-autonomy'

const BuyNowButton = ({ sku, onClick }) => {
  const { getStockAvailability } = useProduct()
  const [disabled, setDisabled] = useState(false)
  
  useEffect(() => {
    getStockAvailability({ sku }).then(a => setDisabled(!a.inStock))
  }, [sku])
  
  return (
    <button disabled={disabled} onClick={onClick}>
      {disabled ? 'Out of stock' : 'Buy Now'}
    </button>
  )
}
import { useState, useEffect } from 'react'
import { useProduct } from '@chordcommerce/react-autonomy'

const BuyNowButton = ({ sku, onClick }) => {
  const { getStockAvailability } = useProduct()
  const [disabled, setDisabled] = useState(false)
  
  useEffect(() => {
    getStockAvailability({ sku }).then(a => setDisabled(!a.inStock))
  }, [sku])
  
  return (
    <button disabled={disabled} onClick={onClick}>
      {disabled ? 'Out of stock' : 'Buy Now'}
    </button>
  )
}
﻿
v2.0.4
This release adds two properties to the "Order Completed" Segment event: has_subscription and is_recurring. These properties already exist on the "Order Completed" event Segment event sent by the Chord OMS.
has_subscription is a boolean that indicates whether the order contains a subscription.
is_recurring is a boolean that indicates whether the order is a subscription installment order and will always be false, since subscription installment orders are not placed via the SDK.
v2.0.3
This release adds a url property to the Product type that is an optional or required argument you can pass to the following methods:
useAnalytics().trackCartViewed()
useAnalytics().trackProductClicked()
useAnalytics().trackProductViewed()
useAnalytics().trackVariantClicked()
useCart().addToCart()
useCart().removeFromCart()
useCheckout().finalizeCheckout()
useCheckout().prepareCheckout()
useProduct().createStockRequest()
useSubscription().cancelSubscription()
useSubscription().pauseSubscription()
useSubscription().resumeSubscription()
useSubscription().skipSubscription()
When the url property is given a value, the value will be sent as the url property in the resulting Segment event.
v2.0.2
This release corrects how we send the ACS-Store header to the OMS. This is necessary for storefronts with multiple stores (i.e. D2C and B2B Chord setups). In order to use this functionality, you must supply a storeSlug prop like so:
JS
import ChordProvider from '@chordcommerce/react-autonomy'
import { StytchClient } from '@chordcommerce/chord-stytch'
import { StytchProvider } from '@stytch/nextjs'

const App = ({ Component, pageProps }) => {
  const authClient = new StytchClient({
    apiKey: process.env.STYTCH_API_KEY,
  })

  return (
    <ChordProvider
      config={{
        domain: process.env.CHORD_OMS_DOMAIN,
        brandName: process.env.CHORD_OMS_BRAND_NAME,
        storeId: process.env.CHORD_OMS_STORE_ID,
        omsId: process.env.CHORD_OMS_ID,
        tenantId: process.env.CHORD_OMS_TENANT_ID,
        // Add this prop to the config for multiple storefront operations
        storeSlug: process.env.CHORD_OMS_STORE_SLUG,
      }}
      authClient={authClient}
    >
      <StytchProvider stytch={authClient.getServiceClient()}>
        <Component {...pageProps} />
      </StytchProvider>
    </ChordProvider>
  )
}
import ChordProvider from '@chordcommerce/react-autonomy'
import { StytchClient } from '@chordcommerce/chord-stytch'
import { StytchProvider } from '@stytch/nextjs'

const App = ({ Component, pageProps }) => {
  const authClient = new StytchClient({
    apiKey: process.env.STYTCH_API_KEY,
  })

  return (
    <ChordProvider
      config={{
        domain: process.env.CHORD_OMS_DOMAIN,
        brandName: process.env.CHORD_OMS_BRAND_NAME,
        storeId: process.env.CHORD_OMS_STORE_ID,
        omsId: process.env.CHORD_OMS_ID,
        tenantId: process.env.CHORD_OMS_TENANT_ID,
        // Add this prop to the config for multiple storefront operations
        storeSlug: process.env.CHORD_OMS_STORE_SLUG,
      }}
      authClient={authClient}
    >
      <StytchProvider stytch={authClient.getServiceClient()}>
        <Component {...pageProps} />
      </StytchProvider>
    </ChordProvider>
  )
}
﻿
Omitting this value will cause all requests to go against the default storefront in the OMS. You can find the storefront's slug in the OMS on the following screen:
How to find your store's slug
﻿
v2.0.0
This release adds an “Order Completed” Segment event to the finalizeCheckout() method. Previously, finalizeCheckout() sent a “Checkout Completed” Segment event. Now, finalizeCheckout() sends both “Order Completed” and “Checkout Completed”.
No changes to your website code are required to upgrade to this release. However, we’re releasing this change as a new major version because the “Order Completed” event is a standard event that many Segment destinations process automatically, and adding it may impact the way your Segment destinations track conversions and revenue.
“Order Completed” is part of the Segment ecommerce event spec. It is usually mapped by default to standard conversion/purchase events in Segment destinations like the Facebook Pixel and TikTok Conversions destinations. You can override this mapping in the Segment destination settings. You may have changed the event mapping in your Segment destination settings to map “Checkout Completed” to the conversion/purchase event for the destination. This will continue to work.
The Chord OMS back-end Segment source has always sent an “Order Completed” event, and you may have connected Segment destinations to this source that are using this event to track conversions and revenue. We recommend continuing to rely on this “Order Completed” event, if possible, because events from back-end sources tend to be more reliable and accurate. (You can read more about this from Segment.)
If you currently have any Segment destinations connected to both the Chord OMS back-end Segment source (typically named "My Company Back-End (Production)”) and your website front-end Segment source (typically named "My Company Front-End (Production)”), you may want to add a destination filter to stop your destination from receiving “Order Completed” events from one of the two Chord Segment sources. If a destination receives an “Order Completed” event from both sources, that could result in revenue or conversions being double counted.
Note regarding the Google Universal Analytics Segment destination: This destination accepts total or revenue as a property on "Order Completed", but not both. The "Order Completed" event does include both of these properties, to match the Segment ecommerce spec and to be compatible with other Segment destinations. You may need to add a destination-specific transformation to remove one of the two properties.
v1.7.0
This release adds eventing for when a subscription is added or removed from the cart. Adding a subscription to the cart will trigger a Product Added event with the interval and actionable date attached to it. Removing a subscription from the cart will trigger a Product Removed event with the same attributes.
Reach out to Chord support for instructions on how to add these properties to your tracking plan.
v1.5.0 / v1.6.0
These releases introduce the ability to purchase prepaid / gift subscriptions in your storefront through the purchasePrepaidSubscription method in useCart. The purchasing flow for prepaid subscriptions roughly follows:
Customer clicks purchase on the prepaid subscription.
Storefront collects the email, name and shipping information for the recipient of prepaid subscription.
That information is passed to the SDK method which will return a checkout session token.
The caller should direct the customer directly to checkout, where the only item in the cart will be the prepaid subscription and the shipping information will already be filled in.
Upon successful purchase, the subscription is immediately activated and will begin shipping to the recipient.
In future releases, the shipping date, notifications and redemption methods will be controllable through this new method.
If the customer backs out of the purchase, the order is lost.
More detailed documentation is below.
﻿SDK documentation for the new method﻿
﻿API documentation for the endpoint the SDK method calls﻿
(Optional) Instructions for how one might setup a prepaid subscription type in the CMS﻿
v1.2.0 / 1.3.0
These releases have several fixes related to associating an existing guest cart with a user that has logged in passwordless, magic link contexts. The major change to be aware of here is that, eventually, your application is going to need to have a route that explictly handles the code exchange in these contexts. This should already be the case for users using chord-stytch, but will be a new requirement if you are using chord-magic with this library.
﻿Here is an example of what that page might look like, should you need inspiration.﻿
v1.0.0
This release has authentication, cart, and user-related fixes that may be breaking in some contexts. 
Previous to this, we were loading authentication tokens, carts, and users outside of our core Redux initialization logic and offloading that to application-level useEffects or in useEffects in useAuth, useCart, and useUser. With this release, we have moved those requests to the store initialization logic such that they are only requested once when the site loads for the first time. This change means that your application will make less requests and will sidestep a potential race condition around Chord's login logic.
What this means for you: If you have any calls in your components that use useAuth's getToken function, useCart's loadCart function, and/or useUser's loadUser function, you should probably remove those and respond to the state provided by these hooks.
v0.1.0
This is the initial release. 
Similar React hooks and methods were previously available in the Next.js starter and Gatsby theme. These have been moved into react-autonomy,  and improved with these changes:
Typescript support
react-autonomy has complete Typescript support with type definitions.
Removed dependency on CMS product catalog
Previously, all products in the CMS had to belong to a single catalog. A bootstrapReduxStore query fetched the catalog from the CMS on every page, and Redux stored the catalog and used it to add product metadata, like descriptions and images, to product-related Segment tracking events. react-autonomy removes this dependency on a product catalog and instead adds an optional product argument to some SDK methods, allowing you to provide the product from the CMS and control the CMS query.
JSDoc documentation
react-autonomy includes function documentation following the JSDoc specification.
Improved hooks and methods
Names, parameters, and behavior has been standardized across the SDK.
Updated 06 Nov 2023
Did this page help you?
Quick Start
Next.js