> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing, quality, history and project settings

> Manage volume discount tiers, read stored quality scores and change history for products, and update the project's name, locales and currency.

This guide covers four smaller areas of the API that integrations often need next to product sync:

* **Volume discounts**: quantity-based pricing rules, for example "10 or more units cost 8.50 each".
* **Product quality**: the quality and completeness scores WISEPIM already calculated, with the findings behind them.
* **Product history**: who changed a product, when, and what the values were before and after.
* **Project settings**: the project's name, description, languages and currency.

Every request goes to `https://wisepim.com/api/public/v1` with a [project API key](https://docs.wisepim.com/en/api-reference/authentication.md). Lists use the shared keyset paging described in the [introduction](https://docs.wisepim.com/en/api-reference/introduction.md): pass `next_cursor` back as `cursor` until `has_more` is `false`.

## Scopes at a glance

| Endpoint | Required scope |
| - | - |
| [`GET /volume-discounts`](https://docs.wisepim.com/en/api-reference/volume-discounts/list), [`GET /volume-discounts/{discount_id}`](https://docs.wisepim.com/en/api-reference/volume-discounts/get) | `volume-discounts:read` |
| [`POST /volume-discounts`](https://docs.wisepim.com/en/api-reference/volume-discounts/create), [`PATCH /volume-discounts/{discount_id}`](https://docs.wisepim.com/en/api-reference/volume-discounts/update) | `volume-discounts:write` |
| [`DELETE /volume-discounts/{discount_id}`](https://docs.wisepim.com/en/api-reference/volume-discounts/delete) | `volume-discounts:delete` |
| [`GET /products/{product_id}/quality`](https://docs.wisepim.com/en/api-reference/quality-history/product-quality), [`GET /product-quality`](https://docs.wisepim.com/en/api-reference/quality-history/list-quality) | `products:read` |
| [`GET /products/{product_id}/history`](https://docs.wisepim.com/en/api-reference/quality-history/product-history) | `product-history:read` |
| [`GET /project`](https://docs.wisepim.com/en/api-reference/key/project) | `project:read` |
| [`PATCH /project`](https://docs.wisepim.com/en/api-reference/key/update-project) | `project:write` |

Write and delete scopes also need the member who created the key to still have edit access to the project. If they lost it, writes return `403 issuer_cannot_write`. `project:write` has an extra requirement, described in [Project settings](#project-settings).

Existing keys do not gain these scopes automatically. Create a replacement key with the scopes you need. See [Authentication and scopes](https://docs.wisepim.com/en/api-reference/authentication.md#scopes).

## Volume discounts

A volume discount is a pricing rule with one or more **tiers**. Each tier covers a quantity range and says how the price changes in that range. The rule's **scope** decides which products it covers.

| `scope` | Covers | Set with |
| - | - | - |
| `products` (default on create) | The products you link | `product_ids` |
| `category` | Products in one category | `category_id`, plus `include_subcategories` |
| `global` | The whole catalog | Nothing else |

Sending `product_ids` with a scope other than `products`, or `category_id` with a scope other than `category`, returns `422 invalid_discount_scope`. Products, the category and customer groups must all belong to the key's project. If any one of them does not, the whole write is refused with `422 invalid_reference`.

### Create a discount

This example gives two jackets a three-step price ladder. Prices are sent as fixed unit prices with `discount_method: "fixed_price"`.

```bash theme={null}
curl -X POST https://wisepim.com/api/public/v1/volume-discounts \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: discount-softshell-ladder-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Softshell jacket trade ladder",
    "scope": "products",
    "discount_type": "tier_price",
    "apply_to": "all_customers",
    "calculation_method": "replace_price",
    "product_ids": [48211, 48212],
    "start_date": "2026-12-01T00:00:00+01:00",
    "priority": 10,
    "is_active": true,
    "tiers": [
      {"min_quantity": 1, "max_quantity": 9, "discount_method": "fixed_price", "discount_value": "89.95"},
      {"min_quantity": 10, "max_quantity": 49, "discount_method": "fixed_price", "discount_value": "82.50"},
      {"min_quantity": 50, "max_quantity": null, "discount_method": "fixed_price", "discount_value": "76.00", "description": "Pallet price"}
    ]
  }'
```

The response is `201` with the full discount, including tier IDs, `is_currently_active` (whether the rule applies right now, given `is_active` and the date window), `created_at` and `updated_at`.

The accepted values are:

| Field | Values |
| - | - |
| `discount_type` | `flat_discount`, `buy_x_get_y`, `bulk_discount`, `tier_price`, `progressive`, `quantity_break` |
| `apply_to` | `all_customers`, `specific_groups`, `logged_in` |
| `calculation_method` | `replace_price`, `discount_price`, `compound` |
| Tier `discount_method` | `fixed_price`, `percentage_off`, `fixed_discount`, `price_per_unit` |

Tier `discount_value` is a price, a percentage or an amount, depending on `discount_method`. It has at most two decimal places. A `percentage_off` value cannot exceed 100.

### Tier rules

The API checks the tiers as a set before anything is written:

* `min_quantity` is at least 1. `max_quantity` must be greater than `min_quantity`, or `null` for "and above".
* The first tier does not have to start at 1, and gaps between tiers are allowed. Only overlapping ranges are refused.
* Quantity ranges must not overlap. A tier with `max_quantity: null` must be the last one.
* A discount holds at most 100 tiers.

A tier set that breaks these rules returns `422` with a per-field `detail`, and nothing changes.

### Update with replace-all lists

`PATCH /volume-discounts/{discount_id}` changes only the fields you send. Three fields are lists that **replace the whole set**:

* `product_ids`: the linked products. To add one product, read the discount, append the ID, and send the full list.
* `customer_group_ids`: the customer groups the rule targets, at most 200 per write.
* `tiers`: every tier. Send the complete ladder, including tiers you are not changing.

```bash theme={null}
curl -X PATCH https://wisepim.com/api/public/v1/volume-discounts/312 \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: discount-312-add-48213" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": [48211, 48212, 48213]}'
```

Changing `scope` away from `products` unlinks the discount's products. Changing it away from `category` clears the category.

> [!WARNING]
>
> One write can carry at most **500** `product_ids`. For a rule that should cover more products, put them in a category and use `scope: "category"`, or use `scope: "global"`.

### Filter the list

[`GET /volume-discounts`](https://docs.wisepim.com/en/api-reference/volume-discounts/list) accepts these filters, which combine with AND:

| Parameter | Example | Matches |
| - | - | - |
| `ids` | `ids=312,318` | Up to 200 discount IDs |
| `scope` | `scope=category` | `products`, `category` or `global` |
| `is_active` | `is_active=true` | The stored on/off switch |
| `product_id` | `product_id=48211` | Discounts that link this product |
| `category_id` | `category_id=77` | Discounts aimed at this category |

`product_id` only finds discounts that link the product directly. It does not return category or global discounts that also cover it.

### Gotchas

* **Discounts for specific customers are read-only.** A discount with `apply_to: "specific_customers"` is aimed at individual user accounts, which the API does not expose. You can read it, but `PATCH` and `DELETE` return `409 discount_managed_in_app`. Edit it in the WISEPIM app. You also cannot set `apply_to` to `specific_customers` through the API.
* **Customer group IDs come from the app.** The API has no customer group endpoint. Copy the IDs from the app, or read them from an existing discount.
* **Linking does not bump the product.** Adding a product to a discount does not change that product's `version` or `updated_at`. A sync that polls [`GET /products`](https://docs.wisepim.com/en/api-reference/products/list) with `updated_since` will not see the new link. Read the discounts themselves.
* **Send a time zone offset.** A `start_date` or `end_date` without an offset is read in the server's time zone. `end_date` must be after `start_date` (`422 invalid_discount_window`).
* **Coupons need a code.** `requires_coupon: true` without a `coupon_code` returns `422 coupon_required`.
* **Null is refused for most fields.** Only `category_id`, `start_date`, `end_date` and `coupon_code` accept `null`. Any other field sent as `null` returns `422 invalid_discount`.
* **Deleting keeps the products.** `DELETE` removes the discount and its tiers. The products stay as they are.

## Product quality

WISEPIM scores each product for quality and completeness on a 0 to 100 scale, and records findings such as missing content or failed checks. The quality endpoints return **the stored result of the last scoring run**. Reading a score never starts a new one, so these calls are cheap and safe to poll.

To refresh scores after a large change, run the `recalculate-quality` bulk action described in [Actions and jobs](https://docs.wisepim.com/en/api-reference/actions-and-jobs.md#apply-bulk-changes), wait for the job to finish, then read the scores again. Starting the action needs the `bulk-actions:execute` scope, and the member who created the key must have the bulk edit permission. A key with only `products:read` can read scores but gets `403` on the recalculation.

### What a quality row contains

```json theme={null}
{
  "product_id": 48211,
  "sku": "JKT-SOFT-NVY-M",
  "scored": true,
  "quality_score": 64.0,
  "completeness_score": 78.0,
  "domains": [
    {"domain": "completeness", "score": 78.0},
    {"domain": "channel_readiness", "score": 61.0},
    {"domain": "seo_discoverability", "score": 52.0},
    {"domain": "conversion_potential", "score": 66.0}
  ],
  "issues": [
    {
      "domain": "seo_discoverability",
      "severity": "high",
      "field": "meta_description",
      "message": "Add a meta description",
      "code": null,
      "impact": 8.0,
      "effort": "low"
    }
  ]
}
```

| Field | Meaning |
| - | - |
| `scored` | `false` when the product has never been scored. `quality_score` and `completeness_score` are then `null` and the lists are empty. |
| `quality_score`, `completeness_score` | The stored scores, 0 to 100. |
| `domains` | One score per area the scorer checked. |
| `issues` | Open findings: `domain`, `severity`, `field`, `message`, `code`, `impact` and `effort`. Every field except `domain` and `message` can be `null`. |

The scorer stores **at most five findings per domain**. Treat `issues` as the most important work per area, not a complete list of every problem. A row returns at most 100 findings in total. Typical domains are `completeness`, `channel_readiness`, `seo_discoverability` and `conversion_potential`, and `severity` is usually `high`, `medium` or `low`. Both come from the scorer and can grow, so handle values you have not seen before.

> [!NOTE]
>
> `scored: false` is different from a score of 0. A product with a measured score of 0 has `scored: true` and keeps its findings. Do not rank unscored products as the worst in your catalog. Leave them out or score them first.

### Read one product or many

[`GET /products/{product_id}/quality`](https://docs.wisepim.com/en/api-reference/quality-history/product-quality) returns one row. [`GET /product-quality`](https://docs.wisepim.com/en/api-reference/quality-history/list-quality) returns pages of rows ordered by product ID. Narrow it with `ids` or `skus`: comma-separated, up to 200 values each.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/product-quality?skus=JKT-SOFT-NVY-M,JKT-SOFT-NVY-L,JKT-SOFT-BLK-M&limit=200" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

SKUs that do not exist in the project are left out of the result. They do not cause an error. Without a filter, the list walks every product in the project.

### Example: find the weakest products in a SKU list

This script takes a list of SKUs, fetches their stored scores 200 at a time, and prints the ten lowest-scoring products with their most impactful finding.

```python Python theme={null}
import os
import requests

BASE = "https://wisepim.com/api/public/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['WISEPIM_API_KEY']}"}

def quality_for_skus(skus):
    rows = []
    for start in range(0, len(skus), 200):
        params = {"skus": ",".join(skus[start:start + 200]), "limit": 200}
        while True:
            response = requests.get(f"{BASE}/product-quality", headers=HEADERS, params=params, timeout=30)
            response.raise_for_status()
            page = response.json()
            rows.extend(page["data"])
            if not page["has_more"]:
                break
            params["cursor"] = page["next_cursor"]
    return rows

skus = ["JKT-SOFT-NVY-M", "JKT-SOFT-NVY-L", "JKT-SOFT-BLK-M", "TEE-ORG-WHT-S"]
rows = quality_for_skus(skus)

scored = [row for row in rows if row["scored"]]
unscored = [row["sku"] for row in rows if not row["scored"]]

for row in sorted(scored, key=lambda row: row["quality_score"])[:10]:
    top = max(row["issues"], key=lambda issue: issue["impact"] or 0, default=None)
    hint = f'{top["field"] or top["domain"]}: {top["message"]}' if top else "no open findings"
    print(f'{row["sku"]:<20} {row["quality_score"]:>5.1f}  {hint}')

if unscored:
    print("Not scored yet:", ", ".join(unscored))
```

```javascript Node.js theme={null}
// Save as quality.mjs: top-level await needs an ES module.
const BASE = "https://wisepim.com/api/public/v1";
const HEADERS = { Authorization: `Bearer ${process.env.WISEPIM_API_KEY}` };

async function qualityForSkus(skus) {
  const rows = [];
  for (let start = 0; start < skus.length; start += 200) {
    const params = new URLSearchParams({ skus: skus.slice(start, start + 200).join(","), limit: "200" });
    while (true) {
      const response = await fetch(`${BASE}/product-quality?${params}`, { headers: HEADERS });
      if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
      const page = await response.json();
      rows.push(...page.data);
      if (!page.has_more) break;
      params.set("cursor", page.next_cursor);
    }
  }
  return rows;
}

const skus = ["JKT-SOFT-NVY-M", "JKT-SOFT-NVY-L", "JKT-SOFT-BLK-M", "TEE-ORG-WHT-S"];
const rows = await qualityForSkus(skus);

const scored = rows.filter((row) => row.scored);
const unscored = rows.filter((row) => !row.scored).map((row) => row.sku);

for (const row of scored.sort((a, b) => a.quality_score - b.quality_score).slice(0, 10)) {
  const top = row.issues.reduce(
    (best, issue) => (best === null || (issue.impact ?? 0) > (best.impact ?? 0) ? issue : best),
    null,
  );
  const hint = top ? `${top.field ?? top.domain}: ${top.message}` : "no open findings";
  console.log(`${row.sku.padEnd(20)} ${row.quality_score.toFixed(1).padStart(5)}  ${hint}`);
}

if (unscored.length) console.log("Not scored yet:", unscored.join(", "));
```

The list is ordered by product ID, not by score, so sort on your side. If your SKUs contain commas, look the products up by `ids` instead, because `skus` is split on commas.

## Product history

[`GET /products/{product_id}/history`](https://docs.wisepim.com/en/api-reference/quality-history/product-history) lists a product's recorded changes, the same history the product editor shows in the app. Use it to audit who changed a price, or to recover a value someone overwrote.

```bash theme={null}
curl "https://wisepim.com/api/public/v1/products/48211/history?limit=50" \
  -H "Authorization: Bearer $WISEPIM_API_KEY"
```

Each entry is one operation that touched the product:

| Field | Meaning |
| - | - |
| `id` | The revision ID. |
| `seq` | The product's revision number. It increases with every change. |
| `changeset_id` | Shared by every product one operation changed, for example all products in one bulk edit. |
| `kind`, `action`, `label` | What kind of operation it was, in machine and human form. |
| `status` | `applied`, or `undone` when someone reverted the operation in the app. |
| `source` | Where the change came from, when recorded. Otherwise `null`. |
| `user` | Who made the change. See below. |
| `created_at` | When the change was recorded. |
| `changes` | The individual before and after values. |

Each item in `changes` has `key`, `label`, `kind`, `before` and `after`:

| `kind` | `key` | `before` / `after` |
| - | - | - |
| `field` | The product field name, for example `price` | The field values |
| `attribute` | `attr:<attribute id>` | The displayed attribute values |
| `category` | `categories` | The product's category names, sorted. The primary category ends in ` (primary)`. |
| `category` | `volume_discounts` | The names of linked volume discounts |

`kind: "category"` is used for any membership list, so check `key` to tell categories and volume discounts apart.

Because of the ` (primary)` suffix, strip it before you match these names against your own category names. Setting a different primary category also shows up as a `categories` change, even when the product stays in the same categories.

### Paging and retention

* Entries come **oldest first**. To read recent changes, page through to the end.
* Pages hold 20 entries by default and at most 50 (`limit`).
* Only changes inside the plan's **retention window** are returned. The window is between 1 and 90 days, depending on the project owner's plan. Older changes are not available through the API. If you need a longer audit trail, read the history regularly and store it yourself.

### What is left out

* Field changes cover the fields the [product resource](https://docs.wisepim.com/en/api-reference/products/get.md) returns, plus `family_id`. Stored channel payloads, review drafts and workflow flags are not shown. An entry whose changes were all to hidden data still appears, with an empty `changes` list.
* Undo and redo actions do not appear as separate entries. The reverted operation shows `status: "undone"` instead.
* `user` is the member's first and last name. A member without a name shows as `Team member`, so email addresses are never exposed. `user` is `null` for system and automation changes.

## Project settings

[`GET /project`](https://docs.wisepim.com/en/api-reference/key/project) returns the project the key is bound to: `id`, `name`, `description`, `status`, `primary_locale`, `available_locales`, `primary_industry`, `currency`, `product_count` and `created_at`.

[`PATCH /project`](https://docs.wisepim.com/en/api-reference/key/update-project) changes five settings. Fields you omit stay as they are.

| Field | Rules |
| - | - |
| `name` | 1 to 255 characters. |
| `description` | Up to 10,000 characters. `null` clears it. |
| `primary_locale` | The catalog's source language, for example `nl` or `en-US`. |
| `available_locales` | The project's translation languages. Replaces the whole list. At most 100 locales. |
| `currency` | ISO 4217 code in upper case, for example `EUR`. An empty string marks it as unknown, and it then reads back as `null`. |

No other project field can be changed through the API.

```bash theme={null}
curl -X PATCH https://wisepim.com/api/public/v1/project \
  -H "Authorization: Bearer $WISEPIM_API_KEY" \
  -H "Idempotency-Key: project-locales-2026-11" \
  -H "Content-Type: application/json" \
  -d '{"primary_locale": "nl", "available_locales": ["en", "de", "fr", "pt-br"], "currency": "EUR"}'
```

Locales are validated and stored in canonical form: `pt-br` becomes `pt-BR` and `nl-nl` becomes `nl`. The response is the `GET /project` shape with the stored values, so compare against the response rather than what you sent.

> [!WARNING]
>
> `project:write` works only while the member who created the key may **manage the project's settings**: owners, admins, and custom roles with the "Manage settings" permission. A key created by an editor gets `403 issuer_permission_denied`, with `denied_scopes` and `required_permissions` in the body. This is checked on every request, so a key stops working for this endpoint if its creator's role changes.

Sending an empty body returns `422 empty_update`. Sending `null` for any field other than `description` returns `422 invalid_project_settings`.

## Common errors

All errors use the shared envelope `{"error": "...", "code": "...", "request_id": "..."}`. Request-schema validation errors return `422` with a per-field `detail` and no `code`.

| Status and code | Cause | What to do |
| - | - | - |
| `403 insufficient_scope` | The key lacks the scope in `missing_scopes`. | Create a replacement key with that scope. |
| `403 issuer_cannot_write` | The key's creator can no longer edit the project. | Ask a project owner to create a new key. |
| `403 issuer_permission_denied` | The key's creator lacks "Manage settings" (`PATCH /project`). | Have an owner or admin create the key. |
| `404 not_found` | The discount or product ID is not in this project. | Check the ID and that the key is bound to the right project with [`GET /me`](https://docs.wisepim.com/en/api-reference/key/me). |
| `409 discount_managed_in_app` | The discount targets specific customers. | Edit it in the WISEPIM app. |
| `409 idempotency_conflict` | The `Idempotency-Key` was used for a different request. | Use a new key for a new write. |
| `422 invalid_discount_scope` | `product_ids` or `category_id` does not match `scope`. | Set the matching `scope` in the same request. |
| `422 invalid_reference` | A product, category or customer group is not in this project, or `product_ids` repeats an ID. | Send distinct IDs from this project. |
| `422 invalid_discount_window` | `end_date` is not after `start_date`. | Fix the dates, including their offsets. |
| `422 coupon_required` | `requires_coupon` is true without a `coupon_code`. | Send a `coupon_code`, or set `requires_coupon` to false. |
| `422 invalid_discount` | A field that cannot be empty was sent as `null`. | Omit the field instead. |
| `422` with `detail` | Overlapping tiers, a percentage above 100, more than 500 `product_ids`, or another schema error. | Read `detail` and correct the field it names. |
| `422 invalid_filter` | A bad filter, for example more than 200 `ids` or `skus`, or an unknown `scope`. | Split the lookup into batches of 200. |
| `422 empty_update`, `422 invalid_project_settings` | `PATCH /project` had no fields, or a `null` the field does not accept. | Send at least one setting with a value. |
| `422 native_operation_rejected` | The settings were refused, for example an unknown locale or a lowercase currency. | Read `field_errors` for the field and reason. |
| `429 rate_limited` | Too many requests for this key. | Wait for `Retry-After`, then retry with the same `Idempotency-Key`. |

## Related

> [card] [Products and variants](https://docs.wisepim.com/en/api-reference/products-and-variants.md)
>
> Create and update products, variants and their prices.

> [card] [Actions and jobs](https://docs.wisepim.com/en/api-reference/actions-and-jobs.md)
>
> Recalculate quality scores in bulk and track the job.

> [card] [Webhooks](https://docs.wisepim.com/en/api-reference/webhooks.md)
>
> Get notified when products change instead of polling.

> [card] [Authentication and scopes](https://docs.wisepim.com/en/api-reference/authentication.md#scopes)
>
> Every scope, and how to replace a key with new ones.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.