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.

Every price list is created with a status of pending, regardless of whether a store was specified and regardless of any status sent in the request. A pending price becomes active only once it is approved — either manually by the buyer, or automatically by an auto-approval rule the buyer has configured on the store.

Approval statuses​

Price List Architecture​

Price lists operate on a hierarchical system with multiple components:

Store Scope​

store_id is optional on the request but is never empty on the stored record:

• store_id specified: one price list is created for that store. The store must be one your supplier account is connected to, otherwise the request fails validation.
• store_id omitted: one price list is created for every store your supplier account has an approved connection to, each carrying the same price. This is a convenience for pricing your whole network at once — it is not a separate "public" or "default" price list.

Two things to know about the omitted case:

• You need at least one store you are allowed to price for. If your account has no approved store connection covering the country, the request is refused with a 403 rather than silently creating nothing.
• The response returns one price list, not the whole set. List the product's prices to see every store the fan-out created.

The public_price field is a separate concept: it is the list/RRP price recorded on each price list alongside unit_amount, not a store-less price list.

Geographic Pricing Structure​

• Country Level: Base pricing for each country market. country_code is required.
• Regional Level: Optional pricing for regions within countries (e.g. states, provinces) via region_code. The region must belong to the country given in country_code.
• Store Level: Pricing for an individual store via store_id.

Temporal Pricing System​

Price lists incorporate temporal aspects through:

• start_at (optional) — when the price becomes eligible for use. Defaults to the time of creation, and must be today or later.
• end_at (optional) — must be after both start_at and today. It is recorded for reference but is not used to stop a price being resolved.
• Precedence rules — for the same product, store and country, the approved price with the most recent start_at wins.

Pricing Models​

billing_scheme accepts five values. Three carry a concrete price:

1. Standard Pricing (standard)

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

2. Volume Pricing (volume)

   • Price varies based on total quantity
   • All units priced at tier rate
   • Each tier requires up_to, unit_amount and flat_amount

3. Graduated Pricing (graduated)

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

The remaining two schemes carry no price of their own, so unit_amount, public_price, currency_code and tiers are not required:

4. Quote (quote) — the buyer requests a quotation instead of seeing a price. When you name a store_id, your supplier account must have an RFQ receiver configured for that store and country, or creation fails validation.
5. External (external) — the price is supplied by an external/punchout session at resolution time.

Price Resolution System​

The platform resolves a price for a specific store, country and currency:

Resolution Rules​

1. Only price lists with status approved and a start_at in the past are considered. Pending and denied prices are never resolved.
2. Candidates are filtered to the exact store and country being resolved for. There is no fallback to a store-less price, because none exists.
3. If a region is supplied and any candidate matches that region, only region-matching candidates are considered. Otherwise all candidates for the country apply.
4. Among the remaining candidates, the most recent start_at wins (ties broken by most recent updated_at). end_at is not applied as a filter.
5. A price in the requested currency is preferred. If none exists, another currency is used and the amount is converted for the response.

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:
   • Every price list is created as pending. A status sent in the request is ignored.
   • Buyers can configure auto-approval rules on a store (for example by supplier, category, country, price, or size of price change). A pending price matching an enabled rule is approved — or denied — automatically, usually within moments of creation.
   • Anything not matched by a rule waits for manual review.
   • See offer approvals for detailed approval workflow
4. Activation: Approved prices become available in the relevant store once start_at has passed

System Constraints​

Understanding these constraints is crucial for proper price list management:

1. Immutability

   • Price lists cannot be edited after creation — the supplier API exposes only list, show and create
   • Changes require creating new price lists
   • Superseded prices are archived rather than discarded, for audit purposes

2. Approval Requirements

   • All prices start as pending, including those created without a store_id
   • Approval is controlled by the buyer — either manually or through the buyer's auto-approval rules
   • Suppliers cannot set or bypass the approval status

3. Currency Constraints

   • currency_code must be a currency known to the platform. It is not validated against the store's accepted currencies at creation time
   • Each price list holds a single currency, so covering several currencies requires several price lists
   • At resolution time, if no price exists in the requested currency the platform falls back to another currency and converts the amount

4. Date Handling

   • start_at must be today or later; end_at must be after both start_at and today
   • End dates are indicative only and are not used to stop a price being resolved
   • 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
   • Superseded prices are moved to the price list archive
   • 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, see Create Price List and List Price Lists.

Core Concepts​

1. Multiple Price Lists

   • Create one or more price lists per product
   • Omitting store_id creates the same price for every connected store
   • public_price records the list/RRP price alongside unit_amount

2. Price List Behavior

   • Prices cannot be edited after creation
   • Newer prices override existing ones for the same product, store and country
   • All prices require approval, and approval is the buyer's to give

Request Fields​

status is accepted but ignored — every price list is created as pending.

API Examples​

Standard Price List — Every Connected Store​

Create a price for a product in a specific country and currency, applied to every store you are connected to:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "standard",
    "unit_amount": "300.00",
    "public_price": "350.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive"
}'

Standard Price List — Single Store​

Add store_id to price a single store:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "priceable_type": "product",
    "priceable_identifier": "testproduct",
    "billing_scheme": "standard",
    "unit_amount": "300.00",
    "public_price": "350.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. Every unit is charged at the rate of the tier the total quantity falls into:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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": 45
        }
    ],
    "public_price": "60.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

Graduated Pricing Implementation​

Create a price list with graduated pricing tiers. Each tier is charged at its own rate and the tier prices are added together:

curl --location --request POST 'https://api.axiomdata.io/api/suppliers/price-lists' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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": 45
        }
    ],
    "public_price": "60.00",
    "currency_code": "CHF",
    "country_code": "CH",
    "tax_behaviour": "inclusive",
    "store_id": 1
}'

All four requests return a price list with "status": "pending".

Price List Management​

Store Price Creation​

When implementing store-specific pricing:

• store_id must be a store your supplier account is connected to
• The price becomes live in that store only after it is approved
• Status remains pending until then

Price Deletion and Archives​

To maintain pricing integrity, it is not possible to fully delete an approved price. To change your pricing for a store, create a new price list and have it approved — the superseded price is archived automatically. If a price is wrong, or you want to withdraw pricing for a country, archive it with a price list CSV import using the archive command.

The list endpoint accepts an archives parameter (with to include archived prices alongside live ones, only to return archived prices exclusively). Archived prices are swept into the price list archive shortly after being archived, so this parameter surfaces only those archived very recently.