Pricing Strategy Guide

Overview

This guide explains how product pricing works in the SynthesQ system, including pricing accuracy, profit margins, and different pricing strategies you can implement through the REST API.

Pricing Accuracy

Precision Guarantee

The system uses cent-based precision for all monetary values to eliminate floating-point rounding errors. This means:

✅ Exact calculations: 0.1 + 0.2 = 0.3 (always)
✅ Consistent totals: No rounding discrepancies in invoices
✅ Audit compliance: Financial reports are accurate to the cent
✅ Currency safety: Cannot accidentally mix currencies (USD, EUR, etc.)

How it works: Internally, prices are stored as integers (cents/smallest currency unit). When you send 19.99 via the API, it's stored as 1999 cents and converted back to 19.99 when retrieved.

Supported Currencies

The system supports multi-currency pricing with these standard currency codes:

USD (US Dollar)
EUR (Euro)
GBP (British Pound)
CAD (Canadian Dollar)
And 150+ other ISO 4217 currency codes

Currency consistency: All products within a master product must use the same currency.

Pricing Model

Product Price Fields

Each product has these price-related fields:

Field	Type	Description	Example
`selling_price`	number	Customer-facing price	`99.99`
`cost_price`	number	Your cost from supplier	`50.00`
`currency`	string	ISO currency code	`"USD"`
`margin`	number	Profit margin percentage (read-only)	`49.99`
`profit`	number	Profit amount (read-only)	`49.99`

Calculated fields: margin and profit are automatically calculated from selling_price and cost_price.

Master Product Base Prices

Master products (for variants) have base pricing:

Field	Type	Description
`base_price`	number	Default selling price for all variants
`base_cost_price`	number	Default cost price for all variants
`currency`	string	Currency for entire product family

Variants can inherit these base prices or override them individually.

Pricing Strategies

Strategy 1: Fixed Pricing (Simple Products)

Use Case: Products with one price, no variations.

API Example:

json

POST /api/v1/operations/products
{
  "name": "Office Desk Lamp",
  "sku": "LAMP-001",
  "selling_price": 49.99,
  "cost_price": 25.00,
  "currency": "USD"
}

Result: Selling price: $49.99, Cost: $25.00, Margin: 49.95%

Strategy 2: Size-Based Pricing

Use Case: Different prices for different sizes (clothing, furniture, etc.)

How it works:

Create master product with base price
Generate variants for each size
Override price for premium sizes

API Example:

json

# Create variant with base price (inherited)
POST /api/v1/operations/master-products/1/variants
{
  "variant_selection": {"Size": "M"}
  # Inherits base_price from master
}

# Create variant with premium price (override)
POST /api/v1/operations/master-products/1/variants
{
  "variant_selection": {"Size": "XL"},
  "selling_price": 29.99  # Premium size
}

Strategy 3: Dynamic Pricing with Margins

Use Case: Set target profit margin, let system calculate selling price.

Formula: Selling Price = Cost Price ÷ (1 - Target Margin)

Example:

Cost: $50.00
Target Margin: 40%
Calculated Selling Price: $83.33

How to implement: Calculate selling price before API request, or use bulk pricing updates to apply margin-based pricing.

Strategy 4: Tiered Pricing

Use Case: Different prices based on storage, features, or quality tiers.

API Example:

json

# Base tier - 64GB
POST /api/v1/operations/master-products/1/variants
{
  "variant_selection": {"Storage": "64GB"},
  "selling_price": 699.00
}

# Mid tier - 128GB
POST /api/v1/operations/master-products/1/variants
{
  "variant_selection": {"Storage": "128GB"},
  "selling_price": 799.00
}

# Premium tier - 256GB
POST /api/v1/operations/master-products/1/variants
{
  "variant_selection": {"Storage": "256GB"},
  "selling_price": 999.00
}

Profit Margin Calculations

How Margins are Calculated

The system automatically calculates profit metrics:

Profit Amount:

Profit = Selling Price - Cost Price

Profit Margin (%):

Margin % = (Profit ÷ Selling Price) × 100

Markup (%):

Markup % = (Profit ÷ Cost Price) × 100

Example Calculation

Product with:

Selling Price: $100.00
Cost Price: $60.00

Calculated values:

Profit: $40.00
Margin: 40% (of selling price)
Markup: 66.67% (of cost price)

Viewing Margins via API

bash

GET /api/v1/operations/products/123

Response:

json

{
  "data": {
    "id": 123,
    "selling_price": 100.00,
    "cost_price": 60.00,
    "profit": 40.00,
    "margin_percentage": 40.00,
    "markup_percentage": 66.67
  }
}

Working with Prices via API

Creating Products with Prices

Request:

json

POST /api/v1/operations/products
{
  "name": "Premium Laptop",
  "selling_price": 1299.99,
  "cost_price": 850.00,
  "currency": "USD"
}

Important:

Always use numeric values (not strings)
Don't include currency symbols ($, €)
Use up to 2 decimal places
Maximum value: 9,999,999.99

Updating Prices

Single Product:

json

PUT /api/v1/operations/products/123
{
  "selling_price": 1399.99
}

Bulk Price Update (for variants):

json

POST /api/v1/operations/master-products/1/variants/bulk-update-prices
{
  "action": "increase_percentage",
  "percentage": 10,
  "filters": {
    "variant_selection": {"Size": "L"}
  }
}

Available bulk actions:

set_price - Set all to fixed price
increase_percentage - Increase by X%
decrease_percentage - Decrease by X%
increase_amount - Increase by fixed amount
decrease_amount - Decrease by fixed amount

Price Validation

API Validation Rules

The system enforces these validation rules:

Selling Price:

✅ Must be numeric
✅ Cannot be negative
✅ Maximum: 9,999,999.99
⚠️ Should typically be higher than cost price (warning only)

Cost Price:

✅ Must be numeric
✅ Cannot be negative
⚠️ Should not exceed selling price (negative margin warning)

Currency:

✅ Must be valid ISO 4217 code (USD, EUR, GBP, etc.)
✅ Must match master product currency (for variants)

Validation Error Examples

Invalid selling price:

json

{
  "errors": {
    "selling_price": [
      "Selling price must be a valid number",
      "Selling price cannot be negative"
    ]
  }
}

Negative margin warning:

json

{
  "errors": {
    "cost_price": [
      "Cost price should not be higher than selling price (negative margin)"
    ]
  }
}

Master Product Price Ranges

Price Range Display

For master products with variants at different price points, the API returns price ranges:

Request:

bash

GET /api/v1/operations/products/1

Response:

json

{
  "data": {
    "id": 1,
    "name": "Cotton T-Shirt",
    "price_range": {
      "min": 19.99,
      "max": 29.99,
      "currency": "USD",
      "formatted": "$19.99 - $29.99"
    },
    "variant_count": 12
  }
}

Use cases:

Display "Starting at $19.99" on product listings
Show "$19.99 - $29.99" for products with price variation
Help customers understand pricing before selecting variants

Common Pricing Patterns

Pattern 1: Cost-Plus Pricing

Add fixed markup to cost price.

Formula: Selling Price = Cost × (1 + Markup %)

Example:

Cost: $50
Markup: 50%
Selling Price: $75

Pattern 2: Competitive Pricing

Match or undercut competitor prices.

Strategy: Research market prices, set your price accordingly via API.

Pattern 3: Psychological Pricing

Use prices ending in .99, .95, or .97 for better conversion.

Examples:

$19.99 (instead of $20.00)
$99.95 (instead of $100.00)
$1,299.97 (instead of $1,300.00)

Pattern 4: Volume-Based Pricing

Offer different prices for different quantities (use separate SKUs or manual implementation).

Best Practices

1. Use Numeric Values in API Requests

json

✅ "selling_price": 99.99
❌ "selling_price": "99.99"
❌ "selling_price": "$99.99"

2. Maintain Consistent Currency

All variants of a master product must use the same currency.

json

✅ Master: USD, All variants: USD
❌ Master: USD, Variant: EUR

3. Set Realistic Margins

Monitor profit margins to ensure profitability:

Low margin: < 20% (competitive products)
Healthy margin: 30-50% (standard retail)
High margin: > 60% (premium/luxury)

4. Update Prices Strategically

Consider these factors when updating prices:

Competitor pricing
Market demand
Seasonal trends
Cost changes from suppliers
Target profit margins

5. Use Bulk Updates for Variants

When updating prices for multiple variants:

json

✅ Use bulk-update-prices endpoint (1 request)
❌ Update each variant individually (N requests)

Product Variants Guide - Multi-variant pricing strategies
Inventory Management - Stock valuation and COGS
Product Lifecycle - Product management workflow

Pricing Strategy Guide ​

Overview ​

Pricing Accuracy ​

Precision Guarantee ​

Supported Currencies ​

Pricing Model ​

Product Price Fields ​

Master Product Base Prices ​

Pricing Strategies ​

Strategy 1: Fixed Pricing (Simple Products) ​

Strategy 2: Size-Based Pricing ​

Strategy 3: Dynamic Pricing with Margins ​

Strategy 4: Tiered Pricing ​

Profit Margin Calculations ​

How Margins are Calculated ​

Example Calculation ​

Viewing Margins via API ​

Working with Prices via API ​

Creating Products with Prices ​

Updating Prices ​

Price Validation ​

API Validation Rules ​

Validation Error Examples ​

Master Product Price Ranges ​

Price Range Display ​

Common Pricing Patterns ​

Pattern 1: Cost-Plus Pricing ​

Pattern 2: Competitive Pricing ​

Pattern 3: Psychological Pricing ​

Pattern 4: Volume-Based Pricing ​

Best Practices ​

1. Use Numeric Values in API Requests ​

2. Maintain Consistent Currency ​

3. Set Realistic Margins ​

4. Update Prices Strategically ​

5. Use Bulk Updates for Variants ​

Related Documentation ​

Pricing Strategy Guide

Overview

Pricing Accuracy

Precision Guarantee

Supported Currencies

Pricing Model

Product Price Fields

Master Product Base Prices

Pricing Strategies

Strategy 1: Fixed Pricing (Simple Products)

Strategy 2: Size-Based Pricing

Strategy 3: Dynamic Pricing with Margins

Strategy 4: Tiered Pricing

Profit Margin Calculations

How Margins are Calculated

Example Calculation

Viewing Margins via API

Working with Prices via API

Creating Products with Prices

Updating Prices

Price Validation

API Validation Rules

Validation Error Examples

Master Product Price Ranges

Price Range Display

Common Pricing Patterns

Pattern 1: Cost-Plus Pricing

Pattern 2: Competitive Pricing

Pattern 3: Psychological Pricing

Pattern 4: Volume-Based Pricing

Best Practices

1. Use Numeric Values in API Requests

2. Maintain Consistent Currency

3. Set Realistic Margins

4. Update Prices Strategically

5. Use Bulk Updates for Variants

Related Documentation