Typical usage scenarios


Import all product information
    Import only changed product information. How to get changed data.


Import all product information

Starting from scratch, you want to populate a commerce solution with product information from Bluestone PIM.

  • Start by: Call the /categories endpoint to find the catalog ID you want to use in your commerce solution.

Please note: If you already know this ID, you may skip this and go directly to the next step.

  • Call /categories/{categoryId} to get a complete layout of the catalog/category structure. You may specify a higher depth level than the default ten if you need to.
  • After import of category structure, call /categories/{categoryId}/products; remember to specify that you want to include products in all subcategories. Then you will get a paginated list of all available products for this catalog.

Please note: Each product will contain a link to the correct structure node, so you can map it correctly to the structure you already imported.

Now you have a complete set of all product data with the desired structure and all related information from PIM Public API.

Import only changed product information.

Tip! After the initial import of all product information, do partial updates.

  • Depending on the number of products, attributes, and categories, a full import can be slow.
  • Doing partial updates means getting the new product info faster to a website. 
  • Transfer and processing of all data every time can get costly on both ends.

Please note: It can still be wise to do a full import once in a while.

How to get changed data

Data is changed in Public API when it is published from PIM, and this produces a new sync record that contains details about the publication.

There are two ways of getting the sync record:

  1. Periodically check /syncs endpoint with parameter createdAfter to get only new syncs.
  2. Get notified of new sync events by using webhooks. The event will contain the new sync id. 

Please note: When you have the sync id, you can use the different endpoints to see more details. 

Below we have used /differences/sync/{id}/products to get the first 100 product changes. 

Request URL: https://api.bluestonepim.com/v1/differences/sync/5f3b9a9ab799cf00109dad9f/products?itemsOnPage=100&pageNo=0

Response body


    "diffType": "ADD",

    "id": "5df0caaf713c09000cd64601"



    "diffType": "CHANGE",

    "id": "5efb27115f1503000d88d4ab"



    "diffType": "DELETE",

    "id": "5f3a488bdc0e82000c7dea07"




In the example below, we see that one product has been added, one changed, and one removed from Public API.

  • Use /products/list endpoint to get information about new and changed products.
Request body

  "ids": [





Please note: It is not possible to filter products in different endpoints. If you only care about products in a specific catalog, you must get the complete product information to see which categories it is in.