Skip to main content
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. Lists use the shared keyset paging described in the introduction: pass next_cursor back as cursor until has_more is false.

Scopes at a glance

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. Existing keys do not gain these scopes automatically. Create a replacement key with the scopes you need. See Authentication and 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. 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".
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: 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.
Changing scope away from products unlinks the discount’s products. Changing it away from category clears the category.
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 accepts these filters, which combine with AND: 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 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, 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

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.
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 returns one row. GET /product-quality returns pages of rows ordered by product ID. Narrow it with ids or skus: comma-separated, up to 200 values each.
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.
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 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.
Each entry is one operation that touched the product: Each item in changes has key, label, kind, before and after: 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 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 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 changes five settings. Fields you omit stay as they are. No other project field can be changed through the API.
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.
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.

Products and variants

Create and update products, variants and their prices.

Actions and jobs

Recalculate quality scores in bulk and track the job.

Webhooks

Get notified when products change instead of polling.

Authentication and scopes

Every scope, and how to replace a key with new ones.