Purchase Prices v3 (BETA)

Sitoo Purchase Prices API is used for handling different purchase prices for different franchisees/stores for products to maintain detailed controls over sales margins and stock values. It is recommended to read the Sitoo API introduction before reading this document.

API Base URL

The service is available at the base URL https://purchaseprices.sitooapis.com/v3. To access the API you combine the base URL and the endpoint URL. Example for adding a new price list:

POST https://purchaseprices.sitooapis.com/v3/price-lists

Authentication

Authentication is done with the HTTP basic authentication mechanism over a secure connection. The API ID and password can be found in the Backoffice under settings/Sitoo REST API (Requires administrator privileges).

Using the API ID and password, add an extra header to the request for authentication:

"Authorization: Basic " + base64_encode("{API ID}" + ":" + "{password}");

Example header (API ID "10020-140" and password "buNxoOx2o5kM2JMc3VhBX20k4Gik4qKXyKfg332A"):

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)

Eshop ID

Each site has an integer value called Eshop ID which uniquely identifies it. The ID 1 is given to the first site with an incremented value to the following sites of an account.

Price Lists

A site can have multiple purchase price lists. All price lists are owned by a site through the owner_eshop_id parameter. Prices are added/set to the price lists for specific SKUs, using the /price-lists/{price_list_id}/items-endpoints.

Mappings

The use of purchase price lists are done by assigning them to sites/stores using the /mappings-endpoints. The mapping includes defining which purchase price lists should be used for each site and also for special cases for specific stores (e.g. Franchise Stores with separate purchase prices). Price lists can be shared to multiple sites and stores.

Mapping Example

Site 1 is the headquarter site (HQ) and has price lists named "A", "B" and "C". Site 2 is the franchisee which has a price list named "F1". HQ has shared price list "A" to the franchisee and uses "C" for itself. HQ also has a special share for price list "B" to store "100" and for store "HQSTORE1" in its own site. The franchise store has "F1" as it's local price list.

assigned:
  price_list_id: C
  stores:
    HQSTORE1:
      price_list_id: B
shared:
  2:
    price_list_id: A
    stores:
      100:
        price_list_id: B

assigned:
  price_list_id: F1

Computed Purchase Prices

To get the final purchase prices for a specific site or store, the /computed-prices-endpoint is used. To be able to compute which prices should be used, the endpoint requires information for which site/store that the prices should be calculated for.

When computing which purchase price list to use for a SKU, the following order is used:

1. Price list assigned to the store
2. Shared price list assigned to the store
3. Price list assigned to the site
4. Shared price list assigned to the site

There is also a way to get purchase prices for a different site by using the target_eshop_id property, for example when we are the HQ site and want to look at the purchase prices we assigned to the franchise store, in that case there is only 1 rule regarding which price list to use.

1. Find purchase price from the ones shared (from HQ) to the franchise store.

Limits

Unless otherwise stated all names and identifiers should have a maximum length of 128 characters.

Price list IDs have a maximum length of 64 characters and are verified with the following regular expression:

^[A-Za-z0-9\._-]{0,64}$