> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarlabs-b2b-custom-pricing/developer-tools/ui-sdk-for-storefront.md).

# UI SDK for Storefront

When **Collection Pricing** is enabled on your store, Dollarlabs exposes a set of helper functions on the global `window` object.<br>

These functions let developers **query pricing logic programmatically** and build fully custom pricing, upsell, and UI experiences.

All APIs are **read-only helpers** and reflect the exact pricing rules configured inside the app.

***

### Availability & Requirements

These functions are available **only when**:

* Collection Pricing is enabled
* The app embed is active on the theme
* The page has finished loading (safe to call after `DOMContentLoaded`)

***

### 1. `DollarlabsGetBestPrice(variantId, quantity)`

Returns the **best applicable price** for a given variant and quantity based on all active rules (customer tags, tiers, defaults, etc).

#### Signature

```js
DollarlabsGetBestPrice("45132559613996", 55)
```

#### Parameters

| Name        | Type   | Description              |
| ----------- | ------ | ------------------------ |
| `variantId` | string | Shopify Variant ID       |
| `quantity`  | number | Quantity being evaluated |

#### Use cases

* Custom product price displays
* Cart or PDP price recalculation
* Showing discounted prices outside native UI

#### Response

```json
{
  "hasDiscount": true,
  "formattedPrice": "$148.34",
  "priceInCents": 14834,
  "originalPrice": 18314,
  "savingsPercentage": 19
}
```

#### Field breakdown

| Field               | Meaning                              |
| ------------------- | ------------------------------------ |
| `hasDiscount`       | Whether a discount applies           |
| `formattedPrice`    | Price formatted using store currency |
| `priceInCents`      | Final unit price in cents            |
| `originalPrice`     | Original unit price in cents         |
| `savingsPercentage` | Discount percentage applied          |

***

### 2. `DollarlabsGetNextTierWarning(variantId, quantity)`

Returns information about the **next pricing tier**, if one exists.\
If no higher tier is configured, this function returns `null`.

This is especially useful for **cart upsells and quantity nudges**.

#### Signature

```js
DollarlabsGetNextTierWarning("45132559613996", 51)
```

#### Use cases

* “Add X more items to save more” messages
* Dynamic cart banners
* Quantity-based upsell prompts

#### Response

```json
{
  "itemsNeeded": 3,
  "nextTierQuantity": 6,
  "nextTierPrice": 146.83,
  "nextTierPriceFormatted": "$146.83",
  "currentQuantity": 3,
  "currentTierPrice": 147.59,
  "currentTierPriceFormatted": "$147.59",
  "savingsPerUnit": 0.7599999999999909,
  "savingsPercentage": 0.5,
  "tag": "Precio1",
  "discountMode": "specific_price"
}
```

#### Field breakdown

| Field              | Meaning                                        |
| ------------------ | ---------------------------------------------- |
| `itemsNeeded`      | Units required to reach the next tier          |
| `nextTierQuantity` | Quantity threshold for the next tier           |
| `nextTierPrice`    | Unit price at the next tier                    |
| `currentTierPrice` | Current unit price                             |
| `savingsPerUnit`   | Savings per item at the next tier              |
| `tag`              | Customer tag applied                           |
| `discountMode`     | Pricing mode used (`specific_price`, `%`, etc) |

***

### 3. `DollarlabsGetPricingString(variantId)`

Returns the **raw pricing configuration** (from the uploaded CSV) that applies to the variant.

This is useful when you want **full control over how pricing tiers are displayed** or need to plug the data into custom logic.

#### Signature

```js
DollarlabsGetPricingString("44893358588063")
```

#### Use cases

* Custom pricing tables
* Tooltips or expandable tier breakdowns
* Advanced B2B pricing UI

#### Response

```json
{
  "found": true,
  "pricings": [
    {
      "tagName": "Precio1",
      "pricingString": "1:148.34;3:147.59;6:146.83;12:146.07;24:145.32;c:1",
      "isCustomerTag": true,
      "isDefault": false
    }
  ],
  "customerTags": [
    "Precio1"
  ]
}
```

#### Notes

* `pricingString` is returned **as-is** from the CSV
* You are free to parse and render this however you want
* Multiple pricing rules may be returned if applicable

***

### Error Handling & Defaults

* If no pricing applies, functions return either:
  * `hasDiscount: false`, or
  * `null` (for next tier lookups)
* Functions never mutate cart or prices — they are **pure helpers**

***

### Best Practices

* Cache results where possible to avoid repeated calls
* Call these functions **after customer context is available**
* Use `DollarlabsGetNextTierWarning` for upsells instead of manually recalculating tiers

***

If you’re building advanced B2B pricing experiences, these APIs give you **full access to Dollarlabs’ pricing brain** — without needing to re-implement any logic yourself.