# API for bulk update pricing

## DollarLabs B2B Pricing API – Complete Implementation Guide

This guide explains how to use the DollarLabs B2B Pricing API to programmatically update variant pricing by customer tag. It covers authentication, request structure, pricing formats (including discount types `s`, `p`, and `f`), job processing, and practical implementation examples.

***

### 1. Overview

The DollarLabs B2B Pricing API allows you to push pricing updates directly from external systems such as:

* ERP
* PIM
* Inventory management systems
* Custom internal tools

All pricing updates are processed **asynchronously**.

When you submit a request:

1. The API validates the payload.
2. It returns `202 Accepted` immediately.
3. A background job processes updates sequentially per shop.
4. You can monitor progress using the Job Status endpoint.

This architecture ensures consistency and prevents race conditions.

***

### 2. Authentication

All requests require two headers:

| Header             | Description                          |
| ------------------ | ------------------------------------ |
| `X-API-Key`        | Your API key (prefix: `dlb_`)        |
| `X-Signing-Secret` | Your signing secret (prefix: `sec_`) |

Generate credentials inside the DollarLabs B2B app under:

**API Keys → Create New Key**

Credentials are shown only once at creation. Store them securely.

<figure><img src="/files/uAqXwchAqxatSHm5TUMg" alt=""><figcaption></figcaption></figure>

Copy and save the API tokena nd Signing Secret for using in the next step for Authentication.

<figure><img src="/files/zW2hCrKKlLYqKA4mSPWK" alt=""><figcaption></figcaption></figure>

***

### 3. Endpoint

```
POST https://pricelist-app.dollarlabs.io/api/update-pricing
```

***

### 4. Request Structure

#### Required Headers

```
Content-Type: application/json
X-API-Key: dlb_your_api_key
X-Signing-Secret: sec_your_signing_secret
```

#### Request Body

```json
{
  "action": "update_pricing",
  "updates": [
    {
      "variantId": "123456789",
      "tag": "wholesale",
      "pricing": "1:10.00;c:6;d:s;l:0.00"
    }
  ]
}
```

#### Field Definitions

| Field                 | Type   | Required | Description                      |
| --------------------- | ------ | -------- | -------------------------------- |
| `action`              | string | Yes      | Must be `"update_pricing"`       |
| `updates`             | array  | Yes      | Array of variant pricing updates |
| `updates[].variantId` | string | Yes      | Shopify variant ID               |
| `updates[].tag`       | string | Yes      | Customer tag                     |
| `updates[].pricing`   | string | Yes      | Pricing definition               |

***

### 5. Flat Price Updates (Simple Use Case)

If you want to set a **specific flat price per variant for a given customer tag**, you can pass only a numeric value as the pricing string.

#### Example: Set Flat Prices for Tag `dollartest3`

```json
{
  "action": "update_pricing",
  "updates": [
    { "variantId": "52384592658707", "tag": "dollartest3", "pricing": "948.95" },
    { "variantId": "52384592691475", "tag": "dollartest3", "pricing": "9" },
    { "variantId": "52384592724243", "tag": "dollartest3", "pricing": "24" },
    { "variantId": "52384592757011", "tag": "dollartest3", "pricing": "49" }
  ]
}
```

Behavior:

* Sets an absolute price.
* No volume tiers.
* No case logic.
* No loose pricing logic.
* Overwrites existing pricing for that tag and variant.

Use this format when syncing direct ERP price lists.

***

### 6. Advanced Pricing Format

For volume pricing, case multiples, and discount logic, use the structured pricing format:

```
<qty>:<price>;c:<case_multiple>;d:<discount_type>;l:<loose_price>
```

#### Components

| Component       | Description            |
| --------------- | ---------------------- |
| `<qty>:<price>` | Volume tier definition |
| `c:<number>`    | Case multiple          |
| `d:<type>`      | Discount type          |
| `l:<price>`     | Loose item price       |

***

### 7. Discount Type (`d:`) Explained

The `d:` parameter controls how prices are interpreted.

```
d:s
d:p
d:f
```

| Code | Meaning        | Description                                  |
| ---- | -------------- | -------------------------------------------- |
| `s`  | Specific price | The price you define is the final price      |
| `p`  | Percentage     | The value represents a percentage discount   |
| `f`  | Fixed amount   | The value represents a fixed amount discount |

#### 7.1 d:s (Specific Price)

The number provided is the final selling price.

Example:

```
1:10.00;c:1;d:s;l:0.00
```

Interpretation:

* 1+ units at $10.00
* Case multiple 1
* Direct price, not a discount calculation

Use when defining exact B2B price lists.

***

#### 7.2 d:p (Percentage Discount)

The number represents percentage off the product’s base price.

Example:

```
1:20;c:1;d:p;l:0
```

Interpretation:

* 20% discount applied
* System calculates final price dynamically

Use when wholesale discounts are defined as percentages rather than fixed prices.

***

#### 7.3 d:f (Fixed Amount Discount)

The number represents a fixed amount deducted from the base price.

Example:

```
1:5;c:1;d:f;l:0
```

Interpretation:

* $5 discount per unit
* Final price = base price − 5

Use when offering fixed dollar discounts across variants.

***

### 8. Volume Pricing

Multiple tiers can be defined:

```
1:12.00;6:10.00;12:8.00;c:6;d:s;l:2.50
```

Interpretation:

* 1+ units → $12.00
* 6+ units → $10.00
* 12+ units → $8.00
* Must order in multiples of 6
* Loose item price → $2.50

***

### 9. Loose Volume Tiers

You may define separate loose quantity tiers:

```
10:40.00;20:30.00;30:20.00;c:10;d:s;l:10:45.00;l:20:40.00;l:30:35.00
```

Interpretation:

* Case pricing tiers at 10, 20, 30 units
* Case multiple = 10
* Separate loose pricing tiers

This allows hybrid B2B structures.

***

### 10. Auto-Creation Rules

The system automatically handles:

* New tags → creates new pricing column
* Missing price list → creates price list
* New variant ID → adds new row

No manual preparation required.

***

### 11. Response Handling

All valid requests return:

```
202 Accepted
```

Example:

```json
{
  "message": "Pricing update accepted for background processing.",
  "jobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "totalItems": 3
}
```

This does not mean updates are complete. It means the job has entered the processing queue.

***

### 12. Tracking Job Status

Endpoint:

```
GET https://pricelist-app.dollarlabs.io/api/jobs/:jobId
```

Possible statuses:

| Status       | Meaning                    |
| ------------ | -------------------------- |
| `pending`    | Waiting in queue           |
| `processing` | Currently executing        |
| `completed`  | All updates successful     |
| `failed`     | One or more updates failed |

Example (Completed):

```json
{
  "jobId": "a1b2c3d4",
  "status": "completed",
  "progress": {
    "total": 3,
    "processed": 3,
    "failed": 0,
    "percent": 100
  }
}
```

Example (Failed):

```json
{
  "status": "failed",
  "errors": [
    { "variantId": "999", "error": "Variant not found in store or is invalid/archived" }
  ]
}
```

***

### 13. Rate Limits and Best Practices

* 100 requests per minute per API key
* Recommended: maximum 25 updates per request
* Batch updates efficiently
* Queue large updates sequentially

If syncing thousands of variants, chunk them into 25-item batches.

***

### 14. Choosing the Right Pricing Strategy

| Scenario                      | Recommended Format        |
| ----------------------------- | ------------------------- |
| ERP sync with exact prices    | Flat numeric pricing      |
| Tiered wholesale pricing      | Structured volume pricing |
| Percentage wholesale program  | `d:p`                     |
| Fixed amount rebate           | `d:f`                     |
| Case-based distribution model | Use `c:`                  |
| Mixed case + loose pricing    | Use loose tiers           |

***

### 15. Implementation Pattern

Typical integration flow:

1. Collect variant pricing changes in your ERP.
2. Batch into 25-item groups.
3. POST to `/api/update-pricing`.
4. Store returned `jobId`.
5. Poll `/api/jobs/:jobId` until complete.
6. Log errors if any.

For production systems:

* Implement retry logic for `429` rate limits.
* Handle `failed` jobs by logging and retrying specific variants.

***

### 16. Error Codes Summary

| Status | Meaning                        |
| ------ | ------------------------------ |
| 202    | Accepted for processing        |
| 400    | Invalid request body           |
| 401    | Missing/invalid authentication |
| 403    | IP restricted                  |
| 429    | Rate limit exceeded            |
| 500    | Internal job creation failure  |

***

### 17. Finding Shopify Variant IDs

1. Go to Shopify Admin → Products
2. Open a product
3. Click a variant
4. URL format:

   ```
   /products/{product_id}/variants/{variant_id}
   ```
5. Use the `{variant_id}` value in API calls.

***

### 18. Support

For implementation assistance:

<support@dollarlabs.io>


---

# 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/api-for-bulk-update-pricing.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.