Skip to main content

Getting Started with Prices

This guide walks you through creating and managing Price Specifications on the Hii Retail platform. By the end of this guide, you will understand how to set sales prices, purchase prices, and scheduled future prices for your Items.

Overview​

What is a Price Specification?​

A Price Specification is a structured value representing a monetary amount linked to an Item. It includes the price value, currency, validity period, and tax information.

Price Specifications enable:

  • Sales prices for POS terminals
  • Purchase prices for gross profit calculations
  • Scheduled future price changes
  • Price ranges with min/max limits
┌─────────────────┐
│      Item       │
│  "Fanta Orange" │
└────────┬────────┘
         │
         │ has many
         ▼
┌─────────────────────────────────────────────────────────┐
│                  Price Specifications                   │
├─────────────────┬─────────────────┬─────────────────────┤
│ SALES           │ PURCHASE        │ LOWEST_HISTORIC     │
│ €14.99          │ €8.50           │ €12.99              │
│ (customer pays) │ (supplier cost) │ (for promotions)    │
└─────────────────┴─────────────────┴─────────────────────┘
Required Price

An Item must have at least one SALES Price Specification. This ensures POS systems can sell the Item and calculate margins correctly.

Price Types​

TypeDescriptionUse Case
SALESRegular sales price for customersPOS checkout, e-commerce
PURCHASECost price from supplierGross profit calculations, replenishment
LOWEST_HISTORIC_PRICELowest price in last 30 daysRequired for advertised promotions (EU Directive 98/6/EC)

Taxable Groups​

Prices are linked to taxable groups that determine the VAT rate. Common options following European standards:

Taxable GroupDescription
StandardStandard VAT rate (e.g., 25% in Sweden)
ReducedReduced VAT rate (e.g., 12% for food in Sweden)
ReducedLowLower reduced rate
SuperReducedSuper reduced rate
ZeroZero-rated goods

Price Statuses​

StatusDescription
ACTIVEPrice is active and available for use
DELETEDPrice is deleted and should not be used

Prerequisites​

Before you begin, ensure you have:

  1. Items created: At least one Item to assign prices to (see Items guide)
  2. Business Units created: At least one Business Unit or Business Unit Group (see Business Units guide)
  3. Authentication Token: A valid JWT bearer token with the pnp.price-spec.create permission
Authentication

For details on obtaining an access token, see the OAuth2 Authentication documentation.

API Base URL​

All Price Specification Input API requests should be sent to:

https://price-specification-input.retailsvc.com/api/v2

Step 1: Create a Sales Price​

Create a basic sales price for an Item at the Business Unit Group level. This price will propagate to all Business Units in the group.

Required Fields​

FieldTypeDescription
idstringUnique identifier for this price (max 250 characters)
itemIdstringThe Item this price belongs to
typestringSALES, PURCHASE, or LOWEST_HISTORIC_PRICE
statusstringACTIVE or DELETED
valuenumberThe price amount (including tax)
currencyIdstringISO 4217 currency code (e.g., EUR, SEK, USD)
validFromdatetimeWhen the price becomes effective (ISO 8601 format)
businessUnitGroupIdstringThe Business Unit Group where this price applies

Code Examples​

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "s-5449000051578",
    "itemId": "5449000051578",
    "type": "SALES",
    "status": "ACTIVE",
    "value": 14.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'

Response​

A successful request returns 202 Accepted.

Asynchronous Processing

The Price Specification Input API processes requests asynchronously. A 202 Accepted response means your request has been queued for processing.

Step 2: Create a Sales Price with Min/Max Limits​

Add price limits to control what cashiers can charge. This is useful for items where the cashier may need to adjust the price within a defined range.

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "s-5449000051578",
    "itemId": "5449000051578",
    "type": "SALES",
    "status": "ACTIVE",
    "value": 14.99,
    "minPrice": 12.99,
    "maxPrice": 17.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'

Step 3: Create a Purchase Price​

Purchase prices track what you pay suppliers. They're essential for gross profit calculations and replenishment systems.

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "p-5449000051578",
    "itemId": "5449000051578",
    "type": "PURCHASE",
    "status": "ACTIVE",
    "value": 8.50,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'
Gross Profit

With both a sales price (€14.99) and purchase price (€8.50), the system can calculate a gross profit of €6.49 (43.3% margin).

Step 4: Schedule a Future Price Change​

Schedule a price change to take effect at a specific date and time in the future. The new price will automatically become active when validFrom is reached.

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "s-5449000051578-future",
    "itemId": "5449000051578",
    "type": "SALES",
    "status": "ACTIVE",
    "value": 16.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-06-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'
Price ID Convention

Use a unique id for each price. A common convention is to prefix with the price type (s- for sales, p- for purchase) followed by the item ID and an optional suffix for versioning.

Step 5: Create a Lowest Historic Price​

When running advertised promotions in the EU, you must display the lowest price from the last 30 days (EU Directive 98/6/EC).

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "lh-5449000051578",
    "itemId": "5449000051578",
    "type": "LOWEST_HISTORIC_PRICE",
    "status": "ACTIVE",
    "value": 12.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'
EU Price Regulations

The LOWEST_HISTORIC_PRICE is only required when the Item is part of an advertised price reduction. It's not required for regular markdowns or loyalty promotions.

Step 6: Create a Store-Specific Price​

To create a price that only applies to a specific Business Unit (not inherited from a group), use the Business Unit endpoint.

curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "s-5449000051578-store123",
    "itemId": "5449000051578",
    "type": "SALES",
    "status": "ACTIVE",
    "value": 13.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitId": "store-123"
  }'
Business Unit Group vs Business Unit
  • Use POST /api/v2/bu-g-price-specifications with businessUnitGroupId to create prices that propagate to all Business Units in the group
  • Use POST /api/v2/bu-price-specifications with businessUnitId to create prices specific to a single Business Unit

Step 7: Update a Price​

Use PATCH for partial updates. Note that id, itemId, validFrom, validTo, and businessUnitGroupId are immutable.

curl -X PATCH 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications/s-5449000051578?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json-patch+json' \
  -d '[
    {"op": "replace", "path": "/value", "value": 15.99},
    {"op": "replace", "path": "/maxPrice", "value": 18.99}
  ]'
Immutable Properties

The id, businessUnitGroupId, revision, itemId, validFrom, and validTo properties cannot be updated via PATCH. To change these, delete the price and create a new one.

Step 8: Delete a Price​

Delete a price when it's no longer needed. By default, this performs a soft-delete (sets status to DELETED).

# Soft delete (default)
curl -X DELETE 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications/s-5449000051578?businessUnitGroupId=acme-retail-group' \
  -H 'Authorization: Bearer <your-access-token>'

# Hard delete (permanent)
curl -X DELETE 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications/s-5449000051578?businessUnitGroupId=acme-retail-group&permanent=true' \
  -H 'Authorization: Bearer <your-access-token>'

Complete Pricing Example​

Here's a complete example of setting up sales and purchase prices for an Item:

# 1. Create sales price
curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "s-5449000051578",
    "itemId": "5449000051578",
    "type": "SALES",
    "status": "ACTIVE",
    "value": 14.99,
    "minPrice": 12.99,
    "maxPrice": 17.99,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'

# 2. Create purchase price
curl -X POST 'https://price-specification-input.retailsvc.com/api/v2/bu-g-price-specifications' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "p-5449000051578",
    "itemId": "5449000051578",
    "type": "PURCHASE",
    "status": "ACTIVE",
    "value": 8.50,
    "taxableGroupId": "Standard",
    "validFrom": "2024-01-01T00:00:00Z",
    "currencyId": "EUR",
    "businessUnitGroupId": "acme-retail-group"
  }'

Next Steps​

Now that you can create Price Specifications, you can:

  1. Set up promotions: Create promotional prices linked to campaigns
  2. Configure tax rules: Set up taxable groups for different product categories
  3. Automate price updates: Build integrations to sync prices from your ERP system

Next: Tax - Learn how to configure tax regions and taxable groups for your items.