How to use the Public API sync

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

Using the 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

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.

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.

Example request body

No request body

Response

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

Try it in readme.io

APIs for changing product states

Publishing and Unpublishing Products

• PAPI Sync API
  POST /product/state/list/by-ids
  Actions: PUBLISH, UNPUBLISH

Archiving and Unarchiving Products

• PIM API
  PUT /products/archive/by-ids
PUT /products/unarchive/by-ids