Item Price

An item’s price is determined by the variation selected, as well as any modifiers selected. A price has both regular and sale in order to show both on the UI if desired.

Usage

The getItemPrice function takes in the following object:

interface GetItemPriceRequest {
    item: Item;
    selectedOptions?: OptionSelection[];
    selectedModifiers?: AddItemModifier[];
    selectedVariationId?: string;
    skipStockCheck?: boolean;
    skipModifierCheck?: boolean;
    formattedLocale?: string;
}

• item is the item resource you’re validating.
• selectedOptions is an array of OptionSelections, which is covered in variation choices.
• selectedModifiers is an array of AddItemModifiers which is covered in modifier validation.
• selectedVariationId is used in lieu of selectedOptions if you have a flat variation. It’s simply the id on the choice in the item.variations array. Alternatively, it is also possible to use this for variations with multiple options had you chosen to display the raw variations available.
• skipStockCheck can be set to true if you still want to get a price for an item, even if it’s out of stock. Default is false.
• skipModifierCheck can be set to true if you don’t want to verify that the modifier selections are valid (e.g. still calculate the price prior to a required modifier being selected). Default is false.
• formattedLocale can be set to a BCP 47 language tag string. If provided, the returned ItemPrice will contain regularFormatted and saleFormatted properties (via Intl.NumberFormat()).

getItemPrice runs validateItem to ensure there’s a valid item we can calculate the price on, also taking into account skipStockCheck and skipModifierCheck. If validation fails, a null value will be returned. Otherwise, on succcess an ItemPrice object is returned.

interface ItemPrice {
    regular: Money;
    sale: Money;
}

• regular and sale will both be the same Money objects used in all the custom site resources. If there is no sale price, sale will be populated with the same price as regular.

    interface Money {
        amount: number;
        formatted: string;
        currency: string;
    }
  

  • amount is the the smallest subunit of the given currency. For example, in USD, $7.25 would be returned as 725, and $10.00 would be returned as 1000.
  • formatted is the formatted currency string. It is only populated if formattedLocale is provided on the GetItemPriceRequest, otherwise will be an empty string. The formatting is based off that locale as well as the currency of the price. An amount of 1000 with formattedLocale: en-US and currency: USD would show as $10.00. Note that if the formattedLocale is not a valid BCP 47 language tag, then it will fallback to en-US in order to still populate these properties.
  • currency is the currency code in ISO 4217 format. For example, US dollars is USD.

Usage example:

// In Twig, you can get the current locale of the site via the `square.site.current_locale`
// property and set it in your script.
//
// Note that it is NOT guaranteed to be in BCP 47 format as it takes into account the language input
// ('lang' query string, 'custom_site_lang' cookie, or browser locale). It is guaranteed to be a
// supported locale by the PHP ResourceBundle, and is the same locale used by any of the price filters.
const currentLocale = '{{ square.site.current_locale }}';

// If you don't care about the language input, you can simply use your site's language instead
const siteLanguage = '{{ square.site.language }}';

const itemPrice = sdk.helpers.item.getItemPrice({
    item: item,
    selectedOptions: [
        {
            "itemOptionId": "FPWZK5NMPZSUJ6V2SKYMYKS7",
            "choice": "Medium"
        },
        {
            "itemOptionId": "V4ZLC5E7ZIRJQHBKQVSXITGU",
            "choice": "Home"
        }
    ],
    selectedModifiers: [
        {
            "id": "CEO4PNPOCG6XL4NO27O3EJES",
            "type": "CHOICE",
            "choiceSelections": [
                "Q5AHPUFNSP2AA5GP2JY73Z4D"
            ]
        },
        {
            "id": "11ee26523c56faf08d928e0f9ddeceab",
            "type": "TEXT",
            "textEntry": "Text Modifier"
        }
    ],
    skipStockCheck: true,
    skipModifierCheck: true,
    formattedLocale: siteLanguage
});
// Ensure item passed validation
if (itemPrice) {
    // Display prices as you see fit
    console.log('Regular price is:', itemPrice.regular.formatted);
    console.log('Sale price is:', itemPrice.sale.formatted);
}

Using Twig price filters

As mentioned, getItemPrice will only provide formatted prices for a BCP 47 language tag.

If you want to use a locale outside of BCP 47 to convert the raw numeric currency values, you can use the template API that can accept the properties in the ItemPrice object. Then you can use the format_price filter to update the displayed price via template API on any price change.

// In Twig
{% set formattedRegularPrice = itemPrice.regular.amount|format_price({ currency: itemPrice.regular.currency }) %}
{% set formattedSalePrice = itemPrice.sale.amount|format_price({ currency: itemPrice.sale.currency }) %}

Alternative default price display

If you choose to not have any selected default variation on initial load of your item page, you may display the range of the item’s variation prices (without modifiers) via item.price.low.formatted and item.price.high.formatted. Alternatively you can use the other item price properties if you want to take into account modifiers or just regular prices when showing the range.