Price Lists

Technical documentation for understanding price lists and their implementation in the Axiom platform.

Overview​

Price lists are a fundamental component of the B2B pricing system, enabling suppliers to manage product pricing across multiple dimensions:

• Store-specific pricing
• Geographic pricing (country and region)
• Currency-based pricing
• Time-based pricing

In B2B commerce, price changes require auditability and approval, unlike B2C where prices can be changed directly. This approval process is managed through the offer approvals system, where each price represents an "offer" that must be reviewed before becoming active.

Price List Architecture​

Price lists operate on a hierarchical system with multiple components:

Geographic Pricing Structure​

• Country Level: Base pricing for each country market
• Regional Level: Specific pricing for regions within countries (e.g., states, provinces)
• Store Level: Individual store pricing requiring procurement approval

Temporal Pricing System​

Price lists incorporate temporal aspects through:

• Start dates (optional) - Defines when pricing becomes active
• End dates (optional) - Indicates when pricing should be superseded
• Precedence rules - Newer price lists take precedence over older ones

Pricing Models​

1. Standard Pricing

   • Fixed price per unit
   • Simplest pricing model
   • Suitable for consistent pricing needs

2. Volume Pricing

   • Price varies based on total quantity
   • All units priced at tier rate
   • Optional flat fee per tier

3. Graduated Pricing

   • Different prices for quantity ranges
   • Each tier priced separately
   • Cumulative pricing calculation

Price Resolution System​

The platform implements a sophisticated price resolution system to determine which price should be active at any given time:

Resolution Rules​

1. Store-specific prices take precedence over public prices
2. Regional prices override country-level prices
3. Active date ranges take priority over indefinite prices
4. Newer price lists supersede older ones for the same scope

Approval Process​

The approval workflow ensures proper oversight of pricing changes in the B2B context:

Process Components​

1. Creation: Supplier defines new price list
2. Validation: System checks for required fields and valid ranges
3. Approval Flow:
   • Public prices: Automatically approved
   • Store prices: Requires procurement review
   • See offer approvals for detailed approval workflow
4. Activation: Approved prices become available in relevant stores

System Constraints​

Understanding these constraints is crucial for proper price list management:

1. Immutability

   • Price lists cannot be edited after creation
   • Changes require creating new price lists
   • Old prices remain in history for audit purposes

2. Approval Requirements

   • Store-specific prices always require approval
   • Public prices are automatically approved
   • Approval status cannot be bypassed

3. Currency Constraints

   • Prices must match store's accepted currencies
   • Currency conversion is not automatic
   • Each currency requires separate price lists

4. Date Handling

   • Dates use YYYY-MM-DD format
   • End dates are indicative only
   • Prices continue until explicitly replaced

Integration Considerations​

When implementing price lists in your system:

1. Data Requirements

   • Mandatory fields must be populated
   • Optional fields provide additional control
   • Field validation follows strict rules

2. Performance Implications

   • Price resolution may impact query performance
   • Consider caching strategies
   • Batch operations for bulk updates

3. Audit Requirements

   • All price changes are tracked
   • History is maintained indefinitely
   • Approval status changes are logged

API Implementation​

The Price Lists API provides comprehensive endpoints for managing price lists programmatically. For detailed API specifications and endpoints, visit our API Documentation.

Core Concepts​

1. Multiple Price Lists

   • Create one or more price lists per product
   • First price list becomes default for country
   • Default price acts as public/list price

2. Price List Behavior

   • Prices cannot be edited after creation
   • New prices override existing ones
   • Store-specific prices require approval
   • Public prices auto-approve

API Examples​

Standard Public Price List​

Create a public price list for a product in a specific country:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List",
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "standard",
    "unit_amount": "300.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive"
}'

Store-Specific Price List​

Create a store-specific price list:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List",
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "standard",
    "unit_amount": "300.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Volume Pricing Implementation​

Create a price list with volume-based pricing tiers:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List",
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "volume",
    "tiers": [
        {
            "up_to": 100,
            "flat_amount": 50,
            "unit_amount": 50
        },
        {
            "up_to": 200,
            "flat_amount": 50,
            "unit_amount": 50
        }
    ],
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Graduated Pricing Implementation​

Create a price list with graduated pricing tiers:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List",
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "graduated",
    "tiers": [
        {
            "up_to": 100,
            "flat_amount": 50,
            "unit_amount": 50
        },
        {
            "up_to": 200,
            "flat_amount": 50,
            "unit_amount": 50
        }
    ],
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Price List Management​

Store Price Creation​

When implementing store-specific pricing:

• Store ID must be specified
• Approval required from store administrators
• Price becomes active only after approval
• Status remains pending until approved

Price Deletion and Archives​

To maintain pricing integrity:

• Approved prices cannot be deleted
• Updates require new price list creation
• Pricing changes go through approval
• Archival available for incorrect pricing

Create a Price List with the API​

1. You can create one or more price lists per product
2. Every product has a default price list for a country, this is a price where a store is not specified and can be regarded as the public or list price for that country. The first price created for the product will automatically be set as the default price for that country.
3. Prices cannot be edited or deleted, only overridden by new prices.
4. If a price is created for a specific store this price must first be approved by the supplier (if required) and then by the store. Until the price is approved the status will be "pending".
5. Prices created without a store specified are automatically approved.

Examples​

Standard Price List - Public​

New price list for the public pricing of a specific product in a specific country and currency

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List", //optional
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme":"standard",
    "unit_amount" : "300.00",
    "currency_code" : "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive"
}'

Standard Price List - Store​

New price list for the store pricing of a specific product in a specific country and currency

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List", //optional
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme":"standard",
    "unit_amount" : "300.00",
    "currency_code" : "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Volume Price List - Store​

New price list for the pricing of a specific product in a specific store, country and currency, with volume pricing.

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List", //optional
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme":"volume",
    "tiers": [
        {
            "up_to" : 100, //integer only
            "flat_amount" : 50, //accept digit and decimal
            "unit_amount": 50 //accept digit and decimal
        },
        {
            "up_to" : 200, //integer only
            "flat_amount" : 50, //accept digit and decimal
            "unit_amount": 50 //accept digit and decimal
        }
    ],
    "currency_code" : "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Graduated Price List - Store​

New price list for the pricing of a specific product in a specific store, country and currency, with graduated pricing.

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--data-raw '{
    "name": "New Price List", //optional
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme":"graduated",
    "tiers": [
        {
            "up_to" : 100, //integer only
            "flat_amount" : 50, //accept digit and decimal
            "unit_amount": 50 //accept digit and decimal
        },
        {
            "up_to" : 200, //integer only
            "flat_amount" : 50, //accept digit and decimal
            "unit_amount": 50 //accept digit and decimal
        }
    ],
    "currency_code" : "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Create Price for a Store​

When creating a new price list you must specify the store where the price is applicable. Once the price list has been created and approved by one of the store administrators it will become live in the store.

Delete a Price​

In order to make it easy for suppliers and store operators to maintain trust in their pricing it is not possible to fully delete approved prices. If you would like to update your pricing for a particular store you will have to upload new pricing and have it approved. If you would like to remove your pricing for a particular country or if it is incorrect, then you can archive it.