API Reference

Shop API v1

The following endpoints are documented:

API URL and authorization

API access to the Shop API is enabled by activating the Shop API plugin in the System->Stores admin section of Centra. The URI name field in the configuration will be appended to the base URL for the API. For example, if the URI field is set to “shop”, the full API will be:

http://demo.example.com/store/api/shop

All requests to the API need to include a secret key as authorization. The secret key is displayed in the configuration for the Shop API plugin and it should be passed as an HTTP header with each request as follows:

API-Authorization: <key>

Parameter passing

Parameters for API requests are either passed as a part of the base URL for GET requests, e.g. GET <base>/products/1 to fetch the product with ID 1, or as a data body for the request in the case of POST and PUT. In this case, the parameter set should be JSON encoded, for example:

1
2
3
4
 {
    "categories": "117",
    "market": "1"
 }

Data models

All responses from the API are provided as JSON encoded data. Data returned corresponds to the data seen in Centra’s admin, and because of this the fields returned for a certain type of object will vary depending on how Centra is configured, which plugins are active, and so on.

Product data model

object key

product object
required

The product-id for the product object.

"13": {"productSku": "ABC123"} for product ID 13.

productSku

string
The product SKU.

items

object

The list of items for this product. The keys in the object is the item IDs.

"items": {"123": {...}} for item ID 123.

name

string
Name of the product item size.

ean

string
EAN code of the item.

sku

string
SKU for the item.

stockByMarket

object

List with quantities for this item in each market. The keys in the object is the market IDs.

object value

int

The amount of items in stock for this market.

{"stockByMarket": {"23": 12}} means 12 items for market ID 23.

markets

object

The list of markets for this product. The keys in the object is the market ID.

{"markets": {"23": {"pricesByPricelist": {}}}} will show prices for the product in market ID 23.

pricesByPricelist

object

The list of prices for each pricelist in this market. The keys in the object is the pricelist IDs.

{"pricesByPricelist": {"15": {"price": 123}}}} will show prices for the product in pricelist ID 15.

priceAsNumber

decimal2 (0.00)
The price after discounts for this product in this pricelist represented as a number.

price

string
The price after discounts for this product in this pricelist represented as a string with the proper currency formatting.

priceBeforeDiscountAsNumber

decimal2 (0.00)
The price before discount represented as a number.

priceBeforeDiscount

string
The price before discount represented as a string with proper currency formatting.

discountPercent

int
The percentage of discount applied on the product price.

priceReductionAsNumber

decimal2 (0.00)
The amount that was reduced from the current price represented as a number.

priceReduction

string
The amount that was reduced from the current price represented as a string with proper currency formatting.

showAsOnSale

boolean
If the product should be listed as currently on sale or not.

newProduct

boolean
If the product should be listed as being added recently.

Example response

Example object for a product with ID 12:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
{
   "12" : {
      "productSku" : "ABC123",
      "canonicalUri" : "category/subcategory/example-name",
      "measurementChart" : "0",
      "weight" : 0.35,
      "sku" : "ABC123",
      "media" : [
         {
            "sources" : {
               "thu" : {
                  "height" : 200,
                  "url" : "https://centracdn.net/client/xyz/dynamic/images/497_xyz.jpg",
                  "width" : 200,
                  "mimeType" : "image/jpeg"
               }
            },
            "type" : "image"
         }
      ],
      "excerpt" : "... description excerpt ...",
      "google_merchant_product_group" : "xyz",
      "metaTitle" : "Example Name - Category",
      "categories" : {
         "138" : {
            "sortOrder" : "1",
            "category" : "138",
            "uri" : "category/subcategory/example-name",
            "name" : "example-name"
         }
      },
      "google_merchant_material" : "xyz",
      "metaDescription" : "... meta description ...",
      "weightUnit" : "kg",
      "canonicalCategory" : 138,
      "silkVariantName" : "",
      "harmCodeDescription" : "Harm code description",
      "items" : {
         "1198-359" : {
            "name" : "One Size",
            "ean" : "1234012340123",
            "stockByMarket" : {
               "13" : 229,
            },
            "sku" : "ABC123",
            "item" : "1198-359"
         }
      },
      "uri" : "product-name",
      "countryOfOriginName" : "China",
      "brandName" : "brand",
      "measurementChartRows" : {},
      "markets" : {
         "13" : {
            "stockOfAllItems" : 229,
            "pricesByPricelist" : {
               "47" : {
                  "priceBeforeDiscount" : "175.00 USD",
                  "priceAsNumber" : 175,
                  "price" : "175.00 USD",
                  "discountPercent" : 0,
                  "priceBeforeDiscountAsNumber" : 175,
                  "showAsOnSale" : false,
                  "priceReductionAsNumber" : 0,
                  "newProduct" : false,
                  "priceReduction" : "0.00 USD"
               },
         }
      },
      "collectionName" : "SS13",
      "localized" : {
         "sv" : {
            "metaDescription" : "... meta desc sv ...",
            "name" : "product name sv",
            "description" : "... desc sv ...",
            "metaKeywords" : "... keywords sv ...",
            "excerpt" : "... excerpt sv ...",
            "metaTitle" : "title sv",
            "categories" : {
               "138" : {
                  "name" : "name sv"
               },
            }
         }
      },
      "name" : "Product Name",
      "countryOfOrigin" : "CN",
      "description" : "... description ...",
      "google_merchant_color" : "Beige",
      "harmCode" : "0123 01 01 01",
      "silkProductName" : "Product Name",
      "product" : "1198",
      "stockUnit" : "",
      "collection" : "14",
      "silkProduct" : "497",
      "brand" : "1",
      "silkVariant" : "1933",
      "google_merchant_product_type" : "Category",
      "variantName" : "",
      "metaKeywords" : "",
      "google_merchant_category" : "Category1 > Category2 > Category3"
   }
}

Selection data model

TBC …

Caching

Please note that this API is not built for real-time querying for every pageview on the frontend website. Product catalog queries in particular should be cached locally by the frontend implementation for optimal performance and in order to not overload the Centra API backend. Partial cache invalidation is possible by relying on updates from Centra through the “Push URL” functionality. Checkout operations that rely on real-time information should however of course not be cached.

Push URL

A “Push URL” can be set in the Shop API plugin configuration inside Centra’s admin. Centra will send POST requests to this URL (typically on the frontend) in case certain data is updated in Centra’s database and therefore should be refreshed by the frontend. The POST request contains the variable “payload”, which is an array that will contain one or many of the following fields, each of them being an array with the entity IDs that have been updated in each section.

statics
products
pricelists
markets
maps
giftCertificates
cms
categories
campaignSites
campaigns
affiliates