# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.dollarlabs.io/dollarlabs-b2b-custom-pricing/developer-tools/ui-sdk-for-storefront.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.