Skip to main content
Version: 2025-03

Product Price Tables

A Product Price Table list allows owners/merchants to set custom prices for products through discounts applied at different levels: storewide, specific categories, or individual products. Additionally, it's possible to define business rules such as minimum cart value and minimum product quantity for authenticated customers associated with the price list.

This resource is available in the unstable, v1, and 2025-03 API versions. Unless an endpoint is explicitly marked otherwise, the request and response contract is the same in all three versions.

Price calculation follows the most specific configured rule: a product variant exception takes precedence over a category exception, and a category exception takes precedence over default_discount. A fixed variant price, when provided, is used instead of its percentage discount.

All path parameters are required. id identifies the price table except when it appears after /categories/, /product-variants/, or /customers/, where it identifies the category, product variant, or customer respectively. IDs are represented as strings in request and response bodies, even when they contain only digits.

Properties​

PropertyExplanationTypeRequired in POST
idThe unique identifier for the price tableStringfalse
verification_codeUnique Code that identifies a price table in the client self-registration linkUUIDfalse
store_idThe unique identifier of the store that owns this price tableStringfalse
nameName of the price tableStringtrue
default_discountDiscount percentage applied to all existing products in the storeStringtrue
cart_minimum_priceMinimum cart value required to apply this price tableStringfalse
cart_minimum_quantityMinimum quantity of products required in cart to apply this price tableIntegerfalse
categoriesCategory-specific discount exceptions. See Category exceptions.Arrayfalse
product_variantsProduct-variant discount or fixed-price exceptions. See Product variant exceptions.Arrayfalse
auto_approve_customersFlag to indicate automatic customer association approval (default true in creation)Booleanfalse
activeWhether the price table is currently active and can be appliedBooleanfalse
created_atTimestamp when the price table was created in ISO 8601 formatTimestampfalse
updated_atTimestamp when the price table was last updated in ISO 8601 formatTimestampfalse
has_categoriesIndicates if this price table has specific category configurationsBooleanfalse
has_products_variantsIndicates if this price table has specific product/variant configurationsBooleanfalse
has_customersIndicates if this price table has specific customer associationsBooleanfalse

Endpoints​

POST /products/price-tables​

Create a specific product price table

POST /products/price-tables​

{
  "name": "Price Table",
  "default_discount": "7.00",
  "cart_minimum_price": "250.00",
  "cart_minimum_quantity": 30,
  "auto_approve_customers": true,
  "categories": [
    {
      "id": "135796548",
      "discount": "15.00"
    },
    {
      "id": "542635852",
      "discount": "30.00"
    }
  ],
  "product_variants": [
    {
      "product_id": "84682548",
      "product_variant_id": "234098766",
      "discount": "10.00",
      "price": null
    },
    {
      "product_id": "34567892",
      "product_variant_id": "38946272",
      "discount": "7.00",
      "price": null
    }
  ]
}

HTTP/1.1 201 OK

{
  "id": "1",
  "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
  "store_id": "3776871",
  "name": "Price Table",
  "default_discount": "7.00",
  "cart_minimum_price": "250.00",
  "cart_minimum_quantity": 30,
  "auto_approve_customers": true,
  "active": true,
  "created_at": "2025-11-17T15:12:39.396Z",
  "updated_at": "2025-11-17T15:12:39.396Z",
  "has_categories": true,
  "has_products_variants": true,
  "has_customers": false
}

HTTP/1.1 400 Bad Request

{
  "code": 400,
  "message": "Bad Request",
  "description": "Invalid input parameters",
  "errors": {
    "name": ["The name field is required."],
    "default_discount": ["The default_discount field is required"]
  }
}

GET /products/price-tables/{id}​

Return a specific product price table

GET /products/price-tables/1​

HTTP/1.1 200 OK

{
  "id": "1",
  "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
  "store_id": "3776871",
  "name": "Price Table",
  "default_discount": "7.00",
  "cart_minimum_price": "250.00",
  "cart_minimum_quantity": 30,
  "auto_approve_customers": true,
  "active": true,
  "created_at": "2025-11-17T15:12:39.396Z",
  "updated_at": "2025-11-17T15:12:39.396Z",
  "has_categories": true,
  "has_products_variants": true,
  "has_customers": true
}

GET /products/price-tables​

Return a paginated list of product price tables

ParameterExplanation
pagePage number. Optional; defaults to 1; minimum 1.
per_pageResults per page. Optional; defaults to 10; minimum 1; maximum 10.

GET /products/price-tables?page=1&per_page=10​

HTTP/1.1 200 OK

{
  "total": 2,
  "page": 1,
  "price_tables": [
    {
      "id": "1",
      "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
      "store_id": "3776871",
      "name": "Price Table",
      "default_discount": "7.00",
      "cart_minimum_price": "250.00",
      "cart_minimum_quantity": 30,
      "auto_approve_customers": true,
      "active": true,
      "created_at": "2025-11-17T15:12:39.396Z",
      "updated_at": "2025-11-17T15:12:39.396Z",
      "has_categories": true,
      "has_products_variants": true,
      "has_customers": true
    },
    {
      "id": "2",
      "verification_code": "4f3ba8f8-5698-47d8-9117-547165c42041",
      "store_id": "3776871",
      "name": "Special Price Table",
      "default_discount": "15.00",
      "cart_minimum_price": "399.00",
      "cart_minimum_quantity": 15,
      "auto_approve_customers": false,
      "active": true,
      "created_at": "2025-11-20T12:47:13.786Z",
      "updated_at": "2025-11-20T12:47:13.786Z",
      "has_categories": false,
      "has_products_variants": true,
      "has_customers": true
    }
  ]
}

PUT /products/price-tables/{id}​

Update a specific product price table

PUT /products/price-tables/1​

{
  "name": "Price Table",
  "default_discount": "10.00",
  "cart_minimum_price": "350.00",
  "cart_minimum_quantity": 20,
  "auto_approve_customers": true,
  "active": true,
  "categories": [
    {
      "id": "135796548",
      "discount": "50.00"
    }
  ],
  "product_variants": [
    {
      "product_id": "84682548",
      "product_variant_id": "234098766",
      "discount": "15.00",
      "price": "487.50"
    },
    {
      "product_id": "34567892",
      "product_variant_id": "38946272",
      "discount": "20.00",
      "price": "699.90"
    }
  ]
}

HTTP/1.1 200 OK

{
  "id": "1",
  "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
  "store_id": "3776871",
  "name": "Price Table",
  "default_discount": "10.00",
  "cart_minimum_price": "350.00",
  "cart_minimum_quantity": 20,
  "auto_approve_customers": true,
  "active": true,
  "created_at": "2025-11-17T15:12:39.396Z",
  "updated_at": "2025-11-27T12:15:48.654Z",
  "has_categories": true,
  "has_products_variants": true,
  "has_customers": false
}

HTTP/1.1 400 Bad Request

{
  "code": 400,
  "message": "Bad Request",
  "description": "Invalid input parameters",
  "errors": {
    "name": ["The name field is required."],
    "default_discount": ["The default_discount field is required"]
  }
}

FAQ​

How to clear all category exceptions of a Product Price Table

If you would like to update to clear all categories in a Product Price table, the following body should be sent:

{
  "name": "Price Table",
  "default_discount": "10.00",
  "cart_minimum_price": "350.00",
  "cart_minimum_quantity": 20,
  "auto_approve_customers": true,
  "active": true,
  "categories": [],
  "product_variants": [
    {
      "product_id": "84682548",
      "product_variant_id": "234098766",
      "discount": "15.00",
      "price": "487.50"
    },
    {
      "product_id": "34567892",
      "product_variant_id": "38946272",
      "discount": "20.00",
      "price": "699.90"
    }
  ]
}

HTTP/1.1 200 OK

{
  "id": "1",
  "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
  "store_id": "3776871",
  "name": "Price Table",
  "default_discount": "10.00",
  "cart_minimum_price": "350.00",
  "cart_minimum_quantity": 20,
  "auto_approve_customers": true,
  "active": true,
  "created_at": "2025-11-17T15:12:39.396Z",
  "updated_at": "2025-11-27T12:15:48.654Z",
  "has_categories": false,
  "has_products_variants": true,
  "has_customers": false
}

Product Price Table Categories​

This documentation explains how to configure specific discounts for a category within a price table, allowing merchants to set custom pricing rules that apply to all products within selected categories.

Properties​

PropertyExplanationTypeRequired
idThe unique identifier for the categoryStringtrue
discountDiscount that will be applied to products that have the related categoryStringtrue

Endpoints​

PUT /products/price-tables/{id}/categories​

Updates one or more category exceptions in a product price table list.

PUT /products/price-tables/1/categories​
[
  {
    "id": "1238746858",
    "discount": "20.00"
  },
  {
    "id": "3896583258",
    "discount": "0.00"
  }
]

HTTP/1.1 204 No Content

{}

GET /products/price-tables/{id}/categories/{id}​

Gets a specific category exception from a product price table.

GET /products/price-tables/1/categories/1238746858​

HTTP/1.1 200 Ok

{
  "price_table": {
    "id": "1",
    "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
    "store_id": "3776871",
    "name": "Price Table",
    "default_discount": "7.00",
    "cart_minimum_price": "250.00",
    "cart_minimum_quantity": 30,
    "auto_approve_customers": true,
    "active": true,
    "created_at": "2025-11-17T15:12:39.396Z",
    "updated_at": "2025-11-23T12:48:52.132Z",
    "has_categories": true,
    "has_products_variants": false,
    "has_customers": true,
    "categories": [
      {
        "id": "1238746858",
        "discount": "20.00"
      }
    ]
  }
}

GET /products/price-tables/{id}/categories​

Returns a paginated list of categories from the product price table.

ParameterExplanation
pagePage number. Optional; defaults to 1; minimum 1.
per_pageResults per page. Optional; defaults to 50; minimum 1; maximum 50.
GET /products/price-tables/1/categories?page=1&per_page=50​

HTTP/1.1 200 Ok

{
  "total": 2,
  "page": 1,
  "price_table": {
    "id": "1",
    "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
    "store_id": "3776871",
    "name": "Price Table",
    "default_discount": "7.00",
    "cart_minimum_price": "250.00",
    "cart_minimum_quantity": 30,
    "auto_approve_customers": true,
    "active": true,
    "created_at": "2025-11-17T15:12:39.396Z",
    "updated_at": "2025-11-23T12:48:52.132Z",
    "has_categories": true,
    "has_products_variants": false,
    "has_customers": true,
    "categories": [
      {
        "id": "1238746858",
        "discount": "20.00"
      },
      {
        "id": "3896583258",
        "discount": "0.00"
      }
    ]
  }
}

DELETE /products/price-tables/{id}/categories/{id}​

Delete a specific category exception from a product price table.

DELETE /products/price-tables/1/categories/1238746858​

HTTP/1.1 204 No Content

{}

FAQ​

How to clear all category exceptions of a Product Price Table

If you would like to update to clear all categories in a Product Price table, the following body should be sent:

[]

HTTP/1.1 204 No Content

{}

Product Price Table Products Variants​

This documentation explains how to configure specific discounts for individual products and their variants within a product price table, allowing merchants to set custom pricing rules at the product and variant level.

Properties​

PropertyExplanationTypeRequired
product_idThe unique identifier for the productStringtrue
product_variant_idThe unique identifier for the product variantStringtrue
discountDiscount that will be applied to product variantStringtrue
priceFixed price that will be applied to product variantStringfalse

Endpoints​

PUT /products/price-tables/{id}/product-variants​

Updates one or more products variants exceptions in a product price table.

PUT /products/price-tables/1/product-variants​
[
  {
    "product_id": "136548284",
    "product_variant_id": "136548285",
    "discount": "20.00",
    "price": "150.00"
  },
  {
    "product_id": "246818282",
    "product_variant_id": "246818285",
    "discount": "10.00",
    "price": "250.00"
  },
  {
    "product_id": "358965478",
    "product_variant_id": "358965484",
    "discount": "0.00",
    "price": "350.00"
  }
]

HTTP/1.1 204 No Content

{}

GET /products/price-tables/{id}/product-variants/{id}​

Gets a specific product variant exception from a product price table.

GET /products/price-tables/1/product-variants/136548285​

HTTP/1.1 200 Ok

{
  "price_table": {
    "id": "1",
    "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
    "store_id": "3776871",
    "name": "Price Table",
    "default_discount": "7.00",
    "cart_minimum_price": "250.00",
    "cart_minimum_quantity": 30,
    "auto_approve_customers": true,
    "active": true,
    "created_at": "2025-11-17T15:12:39.396Z",
    "updated_at": "2025-11-23T12:48:52.132Z",
    "has_categories": true,
    "has_products_variants": false,
    "has_customers": true,
    "product_variants": [
      {
        "product_id": "136548284",
        "product_variant_id": "136548285",
        "discount": "20.00",
        "price": "150.00"
      }
    ]
  }
}

GET /products/price-tables/{id}/product-variants​

Returns a paginated list of products variants from the product price table.

ParameterExplanation
pagePage number. Optional; defaults to 1; minimum 1.
per_pageResults per page. Optional; defaults to 50; minimum 1; maximum 50.
GET /products/price-tables/1/product-variants?page=1&per_page=50​

HTTP/1.1 200 Ok

{
  "total": 3,
  "page": 1,
  "price_table": {
    "id": "1",
    "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
    "store_id": "3776871",
    "name": "Price Table",
    "default_discount": "7.00",
    "cart_minimum_price": "250.00",
    "cart_minimum_quantity": 30,
    "auto_approve_customers": true,
    "active": true,
    "created_at": "2025-11-17T15:12:39.396Z",
    "updated_at": "2025-11-23T12:48:52.132Z",
    "has_categories": true,
    "has_products_variants": false,
    "has_customers": true,
    "product_variants": [
      {
        "product_id": "136548284",
        "product_variant_id": "136548285",
        "discount": "20.00",
        "price": "150.00"
      },
      {
        "product_id": "246818282",
        "product_variant_id": "246818285",
        "discount": "10.00",
        "price": "250.00"
      },
      {
        "product_id": "358965478",
        "product_variant_id": "358965484",
        "discount": "0.00",
        "price": "350.00"
      }
    ]
  }
}

DELETE /products/price-tables/{id}/product-variants/{id}​

Delete a specific product variant exception from a product price table.

DELETE /products/price-tables/1/product-variants/136548285​

HTTP/1.1 204 No Content

{}

FAQ​

How to use only the percentage discount

If you would like to use only percentage discount for product variant in a Product Price table, the following body should be sent:

[
  {
    "product_id": "136548284",
    "product_variant_id": "136548285",
    "discount": "20.00",
    "price": null
  }
]

HTTP/1.1 204 No Content

{}
How to clear all products variants exceptions of a Product Price Table

If you would like to update to clear all products variants in a product price table, the following body should be sent:

[]

HTTP/1.1 204 No Content

{}

Product Price Table Customers​

This documentation explains how to associate and disassociate customers with a product price table, allowing merchants to control which customers have access to specific pricing rules and discounts.

Customer Properties​

PropertyExplanationTypeRequired
idThe unique identifier for the customer. Required in customer ID request arrays.Stringtrue
created_atTimestamp when the customer was associated to the price table in ISO 8601 format.Timestampfalse
approved_atTimestamp when the association was approved, or null while approval is pending.Timestampfalse

Endpoints​

PUT /products/price-tables/{id}/customers​

Adds one or more customers to a product price table. This operation is incremental (append) — customers sent in each request are added to the existing associations without removing previously linked customers.

Limits and constraints:

  • Maximum of 10,000 customers per request.
  • A customer can only be associated with one price table at a time. If any customer in the payload is already associated with a price table, the entire batch fails with a 409 Conflict error. Remove the conflicting customers from the payload or disassociate them from their current price table before retrying.
PUT /products/price-tables/1/customers​
["123456789", "654987321", "456897321"]

HTTP/1.1 204 No Content

{}
Error responses​

HTTP/1.1 409 Conflict — One or more customers are already associated with a price table. The errors field lists the conflicting customer IDs.

{
  "code": 409,
  "message": "Conflict",
  "description": "Customers are associated with a product price table.",
  "errors": [
    {
      "customers": ["123456789"]
    }
  ]
}

POST /products/price-tables/{id}/approve-customers​

Approve one or more customers in a product price table.

POST /products/price-tables/1/approve-customers​
["123456789", "654987321", "456897321"]

HTTP/1.1 204 No Content

{}

GET /products/price-tables/customers/{id}​

Returns a paginated list of product price tables associated with a customer.

ParameterExplanation
pagePage number. Optional; defaults to 1; minimum 1.
per_pageResults per page. Optional; defaults to 10; minimum 1; maximum 10.
GET /products/price-tables/customers/123456789?page=1&per_page=10​

HTTP/1.1 200 Ok

{
  "total": 1,
  "page": 1,
  "price_tables": [
    {
      "id": "1",
      "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
      "store_id": "3776871",
      "name": "Price Table",
      "default_discount": "7.00",
      "cart_minimum_price": "250.00",
      "cart_minimum_quantity": 30,
      "auto_approve_customers": true,
      "active": true,
      "created_at": "2025-11-17T15:12:39.396Z",
      "updated_at": "2025-11-23T12:48:52.132Z",
      "has_categories": true,
      "has_products_variants": false,
      "has_customers": true
    }
  ]
}

GET /products/price-tables/{id}/customers​

Returns a paginated list of customers from the product price table.

ParameterExplanation
pagePage number. Optional; defaults to 1; minimum 1.
per_pageResults per page. Optional; defaults to 50; minimum 1; maximum 50.
GET /products/price-tables/1/customers?page=1&per_page=50​

HTTP/1.1 200 Ok

{
  "total": 4,
  "page": 1,
  "price_table": {
    "id": "1",
    "verification_code": "5a23d45e-52b4-470f-8cf8-ff959b9ef0fa",
    "store_id": "3776871",
    "name": "Price Table",
    "default_discount": "7.00",
    "cart_minimum_price": "250.00",
    "cart_minimum_quantity": 30,
    "auto_approve_customers": true,
    "active": true,
    "created_at": "2025-11-17T15:12:39.396Z",
    "updated_at": "2025-11-23T12:48:52.132Z",
    "has_categories": true,
    "has_products_variants": false,
    "has_customers": true,
    "customers": [
      {
        "id": "123456789",
        "created_at": "2026-04-10T19:10:18.795Z",
        "approved_at": "2026-04-22T17:56:42.924Z"
      },
      {
        "id": "987654321",
        "created_at": "2026-04-11T19:10:18.795Z",
        "approved_at": "2026-04-22T17:56:42.924Z"
      },
      {
        "id": "789456321",
        "created_at": "2026-04-12T19:10:18.795Z",
        "approved_at": "2026-04-22T17:56:42.924Z"
      },
      {
        "id": "654987321",
        "created_at": "2026-04-13T19:10:18.795Z",
        "approved_at": "2026-04-22T17:56:42.924Z"
      }
    ]
  }
}

DELETE /products/price-tables/{id}/customers/{id}​

Delete a specific customer from a product price table.

DELETE /products/price-tables/1/customers/987654321​

HTTP/1.1 204 No Content

{}

FAQ​

How do I bulk-associate customers with a price table?

Use PUT /products/price-tables/{id}/customers with batches of up to 10,000 customer IDs per request. Each request appends the provided customers to the price table — existing associations are preserved.

Before sending a batch, make sure none of the customers are already associated with a price table (including the target one). If any customer in the payload has an existing association, the entire batch is rejected with a 409 Conflict error listing the conflicting IDs. You must remove those customers from the payload or disassociate them first using DELETE /products/price-tables/{id}/customers/{customerId}, then retry.

What happens if I send the same customer in multiple requests?

A customer can only be associated with one price table at a time. If a customer is already linked to any price table and you include them in a new request, the entire batch fails with a 409 Conflict response. To move a customer to a different price table, first delete their association using DELETE /products/price-tables/{id}/customers/{customerId}, then add them to the new table.

Last updated on