Skip to content
  • There are no suggestions because the search field is empty.

How to use the Public API sync

This article explains how sync data to the Public API using the sync API.

Tip! See Get started with Public API for details about the PAPI. Find a step-by-step guide on triggering manual product syncs directly from the UI in Sync/publish product information.

Using the papi-sync API

Syncing products using the API requires three steps. 

  1. Create session
  2. Add products
  3. Finish the session and start the sync

We use a session to batch the products and increase performance. Starting one session per product is not recommended.

Only one sync can run at any time and additional sync sessions will be queued.

1. Create session

POST https://api.bluestonepim.com/papi-sync/session

Example request body

Specify one or more contexts to sync. Products added will be synced in all specified contexts. 

{
  "contexts": [
    "en"
  ]
}

Response

If successful, this will result in a '200 - OK' response.

The response headers will include a Resource-Id containing the GUID of the newly created sync session. 

Try it in readme.io

2. Add products

Use the GUID from the previous step as the {id} in the request to add products to the sync session.

POST https://api.bluestonepim.com/papi-sync/session/{id}/products

Example request body

This request adds two products to the sync session:

{
  "products": [
    {
      "productId": "659ea8f7cd619c778f88a7a4",
      "lastUpdate": 1705073128120
    },
    {
      "productId": "659eac3b4a61902524db1d2c",
      "lastUpdate": 1705073128120    
    }
  ]
}

The lastUpdate timestamp ensures that a product is not synced if it changes between being added and synced.

Before syncing, the system compares the timestamp in the sync session with the timestamp of the product in PIM. If the product in PIM has a newer timestamp, that specific product will fail to sync. If the timestamp matches or is older, the product sync succeeds.

The timestamp should typically be set to the moment the sync session starts.

If lastUpdate is omitted, the product will be synced regardless of any changes made in PIM.

Response

If successful, this will result in a '200 - OK' response.

If the request fails with a '400 - Bad request', none of the products in the request will be added to the sync. The error message will contain information about which products could not be added to the session.

Try it in readme.io

3. Finish the session and start the sync 

Use the GUID from step 1 as the {id} in the request to close the sync session and start the sync. This can only be done once for a sync session. This will start the asynchronous sync job to copy the products from PIM to PAPI.

PUT https://api.bluestonepim.com/papi-sync/session/{id}/done

Example request body

No request body

Response

If successful, this will result in a '200 - OK' response.

Try it in readme.io

How to change product states

The following endpoints are used to change the state of products:

  • Publish
    PAPI Sync API: POST /product/state/list/by-ids
    Action: PUBLISH
  • Unpublish
    PAPI Sync API: POST /product/state/list/by-ids
    Action: UNPUBLISH
  • Archive
    PIM API: PUT /products/archive/by-ids
  • Unarchive
    PIM API: PUT /products/unarchive/by-ids