Getting StartedImportsAPI Reference
Developer API

Welcome to the Price API reference

The single source of truth for all API endpoints, request schemas, response formats, and integration examples.

Explore pricing workflows, understand request structures, and integrate customer-specific pricing into your applications with confidence.

Endpoints

Resolve & Bulk Resolve

Response Format

JSON

Authentication

API Key

Pricing modes

Choose the shape that matches the integration pattern you want to support.

Single Resolve

Single Resolve

Pick this mode when you need single-customer pricing and the default api flow.

Request shape
A flat products array with an optional customer_id and default mode behavior.
Response shape
A single flat priced item list under data.items.
Best use case
single-customer pricing and the default API flow
Business
Use when you price one customer at a time.
Best price
Not used for multi-customer batch comparisons.
Bulk Resolve

Bulk Resolve

Pick this mode when you need batch pricing across several customers in one call.

Request shape
A requests[] batch where each entry can carry its own customer_id and products.
Response shape
A grouped result set keyed by customerId.
Best use case
batch pricing across several customers in one call
Business
Not the default shape, but supported when you want a single-customer response model.
Best price
Best for quoting multiple accounts and comparing outcomes.

Security

Authentication

All requests require a bearer token in the Authorization header.

Bearer token

Use a live key from your workspace to authenticate every request.

Authorization: Bearer sk_live_xxxxx
Keys are shown once at creation time and can’t be retrieved later.Generate API key
POST/api/v1/pricing/resolve

1. Resolve pricing

Resolve product pricing using active pricing rules.

Authentication
Bearer Token
Response
JSON
Version
v1
Rate limit
1000 req/min
API Playground:(Single Customer)
POSThttps://pricerules.app/api/v1/pricing/resolve
curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "10",
    "products": [
        {
            "sku": "123-000-987-654",
            "quantity": 21
        }
    ]
}' \
  https://pricerules.app/api/v1/pricing/resolve

Payload

Request body

The schema explorer below stays aligned with the JSON example that follows it.

Prices one customer's products as a flat list. This is the shape used when mode is omitted or set to business.

Request bodyapplication/jsonPOST/api/v1/pricing/resolve
5 fields
customer_idstringOptional
Scope pricing rules to this customer's code. If omitted, only rules that apply to every customer are evaluated.
Example
"101"

Example
[{ sku: "32599", quantity: 1 }]
Each item in products[] · 2 fields
products[].skustringRequired
The product SKU to price.
Example
"32599"
products[].quantityintegerOptional
Quantity used to evaluate minimum-quantity pricing rules.
Default
1
Constraint
Minimum 1
Example
1
mode"business"|"best_price"Optional
Which pricing engine to use for this request — see "Pricing modes" below.
Default
"business"
Example
"business"
Example body for this schema
Business mode request bodyJSONPOST/api/v1/pricing/resolve
{
"customer_id": "10",
"products": [
{
"sku": "123-000-987-654",
"quantity": 21
}
]
}

Notes

A couple of request-shape details that are easy to miss in a code sample.

  • Use business mode for a single customer payload.
  • Quantity defaults to 1 when omitted.

Limits

Limits

The endpoint remains fast, but there are hard caps to keep batch runs predictable.

Maximum products

500

Across the entire request payload.

Recommended payload

< 2 MB

Keep request bodies small for faster processing and reliable retries.

Timeout

15 sec

Large batches may still complete faster, but this is the ceiling.

Rate limit

Plan-based

Per workspace. See your plan limits for the requests-per-minute cap.

Warning for Single Call Limit Exceeded

A single call can price up to 500 product line items in total. If you submit more than that, the first 500 are still processed and the response includes a warning field.

Output

Response

Inspect the returned schema first, then switch to the live example payload below.

data.items is a flat array — one entry per product you submitted.

Response bodyapplication/json200 OK
28 fields
mode"business"|"best_price"
Echoes back the mode used to resolve this request.
Example
"business"
successboolean
Whether the request was processed successfully.
Example
true
warningstring
Only present when more than 500 line items were submitted — see Limits below.
Example
"Only first 500 SKUs were processed."

Fields of data · 2 fields
data.customer_idstring
The customer ID associated with the request.
Example
"cust_123456"

Each item in items[] · 7 fields
items[].skustring
The product SKU that was priced.
Example
"ORRATINUQ"
items[].base_pricenumber|null
The product's list price before any pricing rule is applied.
Example
90
items[].quantityinteger
The quantity that was priced, echoed back from the request.
Example
10
items[].final_pricenumber|null
The resolved price after applying the matched rule, if any.
Example
90

Fields of applied_rule · 5 fields
applied_rule.idstring
ID of the applied pricing rule.
Example
"1cd75890-9f8c-4a65-972d-d2e675f4f27d"
applied_rule.namestring
Name of the applied pricing rule.
Example
"TEST"
applied_rule.type"fixed"|"discount"
Whether the rule set a flat price or a percentage discount.
Example
"fixed"
applied_rule.valuenumber
The rule's configured value (a price for fixed, a percentage for discount).
Example
1

Fields of constraints · 1 field
constraints.minimum_quantityinteger|null
Minimum quantity required for the rule to match, if any.
Example
41
items[].match_reason"LOWEST_PRICE_WINS"|"MOST_SPECIFIC_RULE"|"SKU_LEVEL_RULE"|"CUSTOMER_LEVEL_RULE"|"DEFAULT_RULE"|"PRODUCT_NOT_FOUND"|"NO_RULE"
Why this rule was selected — e.g. "NO_RULE" or "LOWEST_PRICE_WINS". Treat this as an open set of values, since more may be added over time.
Example
"MOST_SPECIFIC_RULE"

Fields of pricing_summary · 2 fields
pricing_summary.savingsnumber
base_price minus final_price, multiplied by quantity. Can be negative if a fixed-price rule sets a price above the base price.
Example
100.00
pricing_summary.messagestring
Human-readable summary of the pricing outcome, safe to show directly to customers.
Example
"Customer saved 100.00 due to active pricing rules"

Fields of billing · 3 fields
billing.limitinteger
Your plan's request quota for the current billing period.
Example
10000
billing.usageinteger
Requests used so far in the current period.
Example
193
billing.remaininginteger
Requests remaining in the current period.
Example
9807

Fields of meta · 2 fields
meta.request_idstring
Unique ID for this request — include it when contacting support.
Example
"req_d82d6fa5-040d-4bf9-8b64-fd330f274d23"
meta.processing_msnumber
Server-side processing time, in milliseconds.
Example
2072.0881
Example response for this schema
200 OK responseJSON200 OK
{
"mode": "business",
"success": true,
"data": {
"customer_id": "10",
"items": [
{
"sku": "123-000-987-654",
"base_price": 500,
"quantity": 21,
"final_price": 450,
"applied_rule": {
"id": "0d338b61-8862-494c-a6fb-6fba93c3ec84",
"name": "TEst for each level",
"type": "discount",
"value": 10,
"constraints": {
"minimum_quantity": 20
}
},
"match_reason": "MOST_SPECIFIC_RULE",
"pricing_summary": {
"savings": 50,
"message": "Customer saved 50.00 due to active pricing rules"
}
}
]
},
"billing": {
"limit": 10000,
"usage": 286,
"remaining": 9714
},
"meta": {
"request_id": "req_736c0f44-f351-453b-ae4c-f7980d6a73a7",
"processing_ms": 882.994099999778
}
}

Response notes

A short checklist for the fields that matter most when integrating the endpoint.

  • data.items mirrors the request order.
  • billing and meta stay at the top level for every response.

Errors

Response status

These tabs summarize the common HTTP statuses returned by the endpoint.

200

Request processed

Description

The request was authenticated, validated, and processed successfully. Individual products may still have no pricing rule or may not exist.

Possible causes

  • Valid bearer token
  • Valid request body
  • Pricing request processed successfully
Response exampleJSON200 Request processed
{
"mode": "business",
"success": true,
"data": {},1 field
"billing": {},3 fields
"meta": {}2 fields
}

Diagnostics

Error codes

Use these codes to map API failures to actionable client messages or retries.

VALIDATION_ERROR

The request body is malformed or does not match the expected schema.

Suggested fix

Check the required fields, field types, enum values, and nested objects against the API schema before resubmitting.

UNAUTHORIZED

The API key is missing, invalid, expired, or no longer active.

Suggested fix

Verify the Authorization header uses a valid Bearer token and that the API key is active.

RATE_LIMIT_EXCEEDED

The workspace has exceeded its allowed request rate for the current rate-limit window.

Suggested fix

Wait until the rate limit resets, respect the Retry-After header, or reduce request bursts and unnecessary retries.

MONTHLY_LIMIT_REACHED

The workspace has reached its request quota for the current billing period.

Suggested fix

Wait for the current billing period to reset, or upgrade the workspace plan if additional requests are required.

MAX_PRODUCTS_EXCEEDED

The request contains more products than the maximum number processed per request. The API processes only the first 500 products.

Suggested fix

Split the products into smaller requests containing no more than 500 products each.

PRODUCT_NOT_FOUND

The requested product SKU does not exist in the workspace.

Suggested fix

Verify the SKU matches an imported product in the workspace and check for differences in spelling, casing, or formatting.

NO_RULE

The product exists, but no applicable pricing rule matched the request.

Suggested fix

Check the customer's code, product SKU, rule scope, minimum quantity, and rule priority.

INTERNAL_ERROR

The API encountered an unexpected server error while processing the request.

Suggested fix

Retry the request. If the issue persists, provide the request ID to support so the failure can be investigated.

POST/api/v1/pricing/resolve/bulk

2. Resolve bulk pricing

Resolve pricing across multiple customer requests in a single call.

Authentication
Bearer Token
Response
JSON
Version
v1
Rate limit
1000 req/min
API Playground:(Bulk Customers)
POSThttps://pricerules.app/api/v1/pricing/resolve/bulk
curl -X POST \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
        {
            "customer_id": "101",
            "products": [
                { "sku": "ORRATINUQ", "quantity": 99 },
                { "sku": "123-000-987-654" }
            ]
        },
        {
            "customer_id": "10",
            "products": [
                { "sku": "123-000-987-654", "quantity": 50 }
            ]
        }
    ] ,
    "mode": "best_price"
}' \
  https://pricerules.app/api/v1/pricing/resolve/bulk

Payload

Request body

The schema explorer below stays aligned with the JSON example that follows it.

Prices products across one or more customers in a single call, and returns results grouped per customer.

Request bodyapplication/jsonPOST/api/v1/pricing/resolve/bulk
6 fields

Example
[{ customer_id: '101', products: [...] }]
Each item in requests[] · 2 fields
requests[].customer_idstringOptional
Scope this request's pricing rules to this customer.
Example
"101"

Example
[{ sku: "32599", quantity: 1 }]
Each item in products[] · 2 fields
products[].skustringRequired
The product SKU to price.
Example
"32599"
products[].quantityintegerOptional
Quantity used to evaluate minimum-quantity pricing rules.
Default
1
Constraint
Minimum 1
Example
1
mode"best_price"Required
Must be set to "best_price" to use this request shape.
Example
"best_price"
Example body for this schema
Best price request bodyJSONPOST/api/v1/pricing/resolve/bulk
{
"requests": [
{
"customer_id": "101",
"products": [
{
"sku": "ORRATINUQ",
"quantity": 99
},
{
"sku": "123-000-987-654"
}
]
},
{
"customer_id": "10",
"products": [
{
"sku": "123-000-987-654",
"quantity": 50
}
]
}
],
"mode": "best_price"
}

Notes

A couple of request-shape details that are easy to miss in a code sample.

  • Set mode to best_price when sending requests[] batches.
  • Each nested request can carry its own customer_id and products array.

Limits

Limits

The endpoint remains fast, but there are hard caps to keep batch runs predictable.

Maximum products

500

Across the entire request payload.

Recommended payload

< 2 MB

Keep request bodies small for faster processing and reliable retries.

Timeout

15 sec

Large batches may still complete faster, but this is the ceiling.

Rate limit

Plan-based

Per workspace. See your plan limits for the requests-per-minute cap.

Warning for Bulk Call Limit Exceeded

A single call can price up to 10 requests in total and up to 500 product line items. If you submit more than product line items, the first 10 requests and the first 500 products are still processed and the response includes a warning field.

Output

Response

Inspect the returned schema first, then switch to the live example payload below.

data is an array grouped by customer — each entry has its own nested list of priced items.

Response bodyapplication/json200 OK
28 fields
mode"business"|"best_price"
Echoes back the mode used to resolve this request.
Example
"business"
successboolean
Whether the request was processed successfully.
Example
true
warningstring
Only present when more than 500 line items were submitted or more than 10 requests were submitted — see Limits below.
Example
"Only first 500 SKUs were processed.", "Only first 10 requests were processed."

Each item in data[] · 2 fields
data[].customerIdstring
The customer_id this group of results belongs to.
Example
"101"

Each item in items[] · 7 fields
items[].skustring
The product SKU that was priced.
Example
"ORRATINUQ"
items[].base_pricenumber|null
The product's list price before any pricing rule is applied.
Example
90
items[].quantityinteger
The quantity that was priced, echoed back from the request.
Example
10
items[].final_pricenumber|null
The resolved price after applying the matched rule, if any.
Example
90

Fields of applied_rule · 5 fields
applied_rule.idstring
ID of the applied pricing rule.
Example
"1cd75890-9f8c-4a65-972d-d2e675f4f27d"
applied_rule.namestring
Name of the applied pricing rule.
Example
"TEST"
applied_rule.type"fixed"|"discount"
Whether the rule set a flat price or a percentage discount.
Example
"fixed"
applied_rule.valuenumber
The rule's configured value (a price for fixed, a percentage for discount).
Example
1

Fields of constraints · 1 field
constraints.minimum_quantityinteger|null
Minimum quantity required for the rule to match, if any.
Example
41
items[].match_reason"LOWEST_PRICE_WINS"|"MOST_SPECIFIC_RULE"|"SKU_LEVEL_RULE"|"CUSTOMER_LEVEL_RULE"|"DEFAULT_RULE"|"PRODUCT_NOT_FOUND"|"NO_RULE"
Why this rule was selected — e.g. "NO_RULE" or "LOWEST_PRICE_WINS". Treat this as an open set of values, since more may be added over time.
Example
"MOST_SPECIFIC_RULE"

Fields of pricing_summary · 2 fields
pricing_summary.savingsnumber
base_price minus final_price, multiplied by quantity. Can be negative if a fixed-price rule sets a price above the base price.
Example
100.00
pricing_summary.messagestring
Human-readable summary of the pricing outcome, safe to show directly to customers.
Example
"Customer saved 100.00 due to active pricing rules"

Fields of billing · 3 fields
billing.limitinteger
Your plan's request quota for the current billing period.
Example
10000
billing.usageinteger
Requests used so far in the current period.
Example
193
billing.remaininginteger
Requests remaining in the current period.
Example
9807

Fields of meta · 2 fields
meta.request_idstring
Unique ID for this request — include it when contacting support.
Example
"req_d82d6fa5-040d-4bf9-8b64-fd330f274d23"
meta.processing_msnumber
Server-side processing time, in milliseconds.
Example
2072.0881
Example response for this schema
200 OK bulk responseJSON200 OK
{
"mode": "best_price",
"success": true,
"data": [
{
"customerId": "101",
"items": [
{
"sku": "ORRATINUQ",
"base_price": 90,
"quantity": 99,
"final_price": 1,
"applied_rule": {
"id": "1cd75890-9f8c-4a65-972d-d2e675f4f27d",
"name": "TEST",
"type": "fixed",
"value": 1,
"constraints": {
"minimum_quantity": 41
}
},
"match_reason": "LOWEST_PRICE_WINS",
"pricing_summary": {
"savings": 89,
"message": "Customer saved 89.00 due to active pricing rules"
}
},
{
"sku": "123-000-987-654",
"base_price": 500,
"quantity": 1,
"final_price": 1400,
"applied_rule": {
"id": "4a9be77a-af98-4101-a2a2-fcd21519eb4a",
"name": "Fixed for sku number 32599 & customer 10",
"type": "fixed",
"value": 1400,
"constraints": {
"minimum_quantity": null
}
},
"match_reason": "LOWEST_PRICE_WINS",
"pricing_summary": {
"savings": -900,
"message": "Customer saved -900.00 due to active pricing rules"
}
}
]
},
{
"customerId": "10",
"items": [
{
"sku": "123-000-987-654",
"base_price": 500,
"quantity": 50,
"final_price": 1,
"applied_rule": {
"id": "1cd75890-9f8c-4a65-972d-d2e675f4f27d",
"name": "TEST",
"type": "fixed",
"value": 1,
"constraints": {
"minimum_quantity": 41
}
},
"match_reason": "LOWEST_PRICE_WINS",
"pricing_summary": {
"savings": 499,
"message": "Customer saved 499.00 due to active pricing rules"
}
}
]
}
],
"billing": {
"limit": 10000,
"usage": 285,
"remaining": 9715
},
"meta": {
"request_id": "req_530efaf0-e124-474e-8f54-94a4d31db548",
"processing_ms": 6402.180099999532
}
}

Response notes

A short checklist for the fields that matter most when integrating the endpoint.

  • Each data[] entry maps back to a requested customer.
  • Nested data[].items[] items use the same pricing shape as business mode.

Errors

Response status

These tabs summarize the common HTTP statuses returned by the endpoint.

200

Request processed

Description

The bulk request was authenticated, validated, and processed successfully. Individual products or customers may still have no applicable pricing result.

Possible causes

  • Valid bearer token
  • Valid bulk request body
  • Bulk pricing requests processed successfully
Response exampleJSON200 Request processed
{
"mode": "best_price",
"success": true,
"data": [],1 item
"billing": {},3 fields
"meta": {}2 fields
}

Diagnostics

Error codes

Use these codes to map API failures to actionable client messages or retries.

VALIDATION_ERROR

The request body is malformed or does not match the expected schema.

Suggested fix

Check the required fields, field types, enum values, and nested objects against the API schema before resubmitting.

UNAUTHORIZED

The API key is missing, invalid, expired, or no longer active.

Suggested fix

Verify the Authorization header uses a valid Bearer token and that the API key is active.

RATE_LIMIT_EXCEEDED

The workspace has exceeded its allowed request rate for the current rate-limit window.

Suggested fix

Wait until the rate limit resets, respect the Retry-After header, or reduce request bursts and unnecessary retries.

MONTHLY_LIMIT_REACHED

The workspace has reached its request quota for the current billing period.

Suggested fix

Wait for the current billing period to reset, or upgrade the workspace plan if additional requests are required.

MAX_PRODUCTS_EXCEEDED

The request contains more products than the maximum number processed per request. The API processes only the first 500 products.

Suggested fix

Split the products into smaller requests containing no more than 500 products each.

PRODUCT_NOT_FOUND

The requested product SKU does not exist in the workspace.

Suggested fix

Verify the SKU matches an imported product in the workspace and check for differences in spelling, casing, or formatting.

NO_RULE

The product exists, but no applicable pricing rule matched the request.

Suggested fix

Check the customer's code, product SKU, rule scope, minimum quantity, and rule priority.

INTERNAL_ERROR

The API encountered an unexpected server error while processing the request.

Suggested fix

Retry the request. If the issue persists, provide the request ID to support so the failure can be investigated.