Product Catalog Synchronization

Use Case Overview

Key Model(s) and Fields	Supported Applications
Products sku description images productType remoteCreatedAtMin remoteCreatedAtMax	Shopify, Adobe Commerce (formerly Magento), BigCommerce, WooCommerce, Salesforce Commerce Cloud, SquareSpace, eBay

Data Flow: Commerce Platform <-> Your App

This is a bi-directional integration. In this example, you can GET, POST, PUT/PATCH and DELETE target resources to to ensure that your application is presenting accurate product information to your merchants’ customers.

How to build this use case with Alloy's Unified API

1. Create a Connection

To get started, you'll need to first implement Alloy's Unified API and create a connection. A connection represents each time an end user links an app to Alloy's Unified API. See Getting Started in our Unified API Quickstart.

If you’ve already done this, read on!

2. Sync all products from a user’s commerce platform to your application

Alloy’s [GET List Products] endpoint allows you to retrieve all historical products from a user’s commerce store in a standardized format. In Alloy’s Unified API, the products object includes properties like sku, description, images, and more.

Your request should be structured like this:

cURL

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/products?credentialId=CREDENTIAL_ID' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Your response payload should look something like this:

JSON

{
  "products": [
    {
      "remoteId": "1234567890123",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "productType": "Apparel",
      "productName": "Example Shirt",
      "description": "A stylish shirt for all occasions.",
      "images": [],
      "productStatus": "ACTIVE",
      "tags": ["Fashion", "Comfort"],
      "vendor": "Example Vendor",
      "productUrl": "https://example.com/products/example-shirt",
      "id": "00112233-4455-6677-8899-aabbccddeeff",
      "variants": [
        {
          "remoteId": "200100200100",
          "productId": "00112233-4455-6677-8899-aabbccddeeff",
          "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
          "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
          "remoteDeleted": false,
          "createdAt": "2024-02-22T11:17:53.264Z",
          "updatedAt": "2024-02-22T13:54:03.445Z",
          "title": "Medium",
          "price": "25.00",
          "sku": "SHIRT-M",
          "optionValues": [
            {
              "name": "Size",
              "value": "Medium"
            }
          ],
          "inventory": {
            "totalCount": 50
          },
          "weight": [
            {
              "value": 0.5,
              "unit": "kg"
            }
          ],
          "id": "11001100-1122-3344-5566-77889900aabb"
        }
      ]
    },
    {
      "remoteId": "2345678901234",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "productType": "Electronics",
      "productName": "Example Headphones",
      "description": "High-quality wireless headphones.",
      "images": [],
      "productStatus": "ACTIVE",
      "tags": ["Gadgets", "Audio"],
      "vendor": "Tech Solutions",
      "productUrl": "https://example.com/products/example-headphones",
      "id": "11223344-5566-7788-99aa-bbccddeeff00",
      "variants": [
        {
          "remoteId": "300200300200",
          "productId": "11223344-5566-7788-99aa-bbccddeeff00",
          "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
          "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
          "remoteDeleted": false,
          "createdAt": "2024-02-22T11:17:53.264Z",
          "updatedAt": "2024-02-22T13:54:03.445Z",
          "title": "Black",
          "price": "75.00",
          "sku": "HP-BLACK",
          "optionValues": [
            {
              "name": "Color",
              "value": "Black"
            }
          ],
          "inventory": {
            "totalCount": 100
          },
          "weight": [
            {
              "value": 0.3,
              "unit": "kg"
            }
          ],
          "id": "22112233-4455-6677-8899-aabbccddeeff"
        }
      ]
    },
    {
      "remoteId": "3456789012345",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "productType": "Accessory",
      "productName": "Example Watch",
      "description": "Elegant and modern wristwatch.",
      "images": [],
      "productStatus": "ACTIVE",
      "tags": ["Luxury", "Time"],
      "vendor": "Watch World",
      "productUrl": "https://example.com/products/example-watch",
      "id": "22334455-6677-8899-aabb-ccddeeff0011",
      "variants": [
        {
          "remoteId": "400300400300",
          "productId": "22334455-6677-8899-aabb-ccddeeff0011",
          "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
          "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
          "remoteDeleted": false,
          "createdAt": "2024-02-22T11:17:53.264Z",
          "updatedAt": "2024-02-22T13:54:03.445Z",
          "title": "Silver",
          "price": "150.00",
          "sku": "WATCH-SILVER",
          "optionValues": [
            {
              "name": "Color",
              "value": "Silver"
            }
          ],
          "inventory": {
            "totalCount": 30
          },
          "weight": [
            {
              "value": 0.2,
              "unit": "kg"
            }
          ],
          "id": "33221100-1122-3344-5566-778899aabbcc"
        }
      ]
    },
    {
      "remoteId": "4567890123456",
      "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
      "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
      "remoteDeleted": false,
      "createdAt": "2024-02-22T11:17:53.264Z",
      "updatedAt": "2024-02-22T13:54:03.445Z",
      "productType": "Book",
      "productName": "Example Novel",
      "description": "Captivating fiction novel.",
      "images": [],
      "productStatus": "ACTIVE",
      "tags": ["Literature", "Fiction"],
      "vendor": "Book Haven",
      "productUrl": "https://example.com/products/example-novel",
      "id": "33445566-7788-99aa-bbcc-ddeeff001122",
      "variants": [
        {
          "remoteId": "500400500400",
          "productId": "33445566-7788-99aa-bbcc-ddeeff001122",
          "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
          "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
          "remoteDeleted": false,
          "createdAt": "2024-02-22T11:17:53.264Z",
          "updatedAt": "2024-02-22T13:54:03.445Z",
          "title": "Hardcover",
          "price": "20.00",
          "sku": "NOVEL-HC",
          "optionValues": [
            {
              "name": "Format",
              "value": "Hardcover"
            }
          ],
          "inventory": {
            "totalCount": 75
          },
          "weight": [
            {
              "value": 0.8,
              "unit": "kg"
            }
          ],
          "id": "44332211-0022-3344-5566-778899bbaacc"
        }
      ]
    }
  ]
}

3. Narrow your list (optional)

You can filter by query parameters if you want to access a subset of the list — for example:

• remoteCreatedAtMin can be used to only retrieve products created after a certain time
• productType can be used to retrieve a specific type of product
• descriptionContains can be used to retrieve products with a description that contains a specific value

See our API reference for a full list of query params. As an example, if you were filtering by productType, your request would look like this:

cURL

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/products?credentialId=CREDENTIAL_ID&productType=Apparel' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

4. Get individual products

You can use the [GET Product] endpoint to retrieve an individual product based on productId.

Here's what that request looks like:

cURL

curl --request GET \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/products/00112233-4455-6677-8899-aabbccddeeff?credentidlId=CREDENTIAL_ID' \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json'

And the response:

JSON

{
  "product": {
    "remoteId": "11650443640992",
    "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
    "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
    "remoteDeleted": false,
    "createdAt": "2024-02-22T11:17:53.264Z",
    "updatedAt": "2024-02-22T13:54:03.445Z",
    "productType": null,
    "productName": "Winter coat",
    "description": "A puffy coat to keep you warm",
    "images": [],
    "productStatus": "ACTIVE",
    "tags": [],
    "vendor": "Alloy Security",
    "productUrl": "https://alloy-security.myshopify.com/products/winter-coat",
    "id": "00112233-4455-6677-8899-aabbccddeeff",
    "variants": [
      {
        "remoteId": "47728579674272",
        "productId": "00112233-4455-6677-8899-aabbccddeeff",
        "remoteCreatedAt": "2023-11-19T17:00:17.000Z",
        "remoteUpdatedAt": "2023-11-19T17:00:17.000Z",
        "remoteDeleted": false,
        "createdAt": "2024-02-22T11:17:53.264Z",
        "updatedAt": "2024-02-22T13:54:03.445Z",
        "title": "Default Title",
        "price": "100.00",
        "sku": "COAT-T",
        "optionValues": [
          {
            "name": "Title",
            "value": "Default Title"
          }
        ],
        "inventory": {
          "totalCount": 0
        },
        "weight": [
          {
            "value": 0.7087373136020865,
            "unit": "kg"
          },
          {
            "value": 708.7373136020865,
            "unit": "g"
          },
          {
            "value": 25,
            "unit": "oz"
          },
          {
            "value": 1.5624964563134318,
            "unit": "lb"
          }
        ],
        "id": "ea9ddc0b-8b4f-495f-a5b8-8640d90b24d4"
      }
    ]
  }
}

5. Write and update products in your user’s commerce platform

To make this a bi-directional integration, you can use the [POST Create Product] endpoint to create an individual product in your user’s commerce platform, complete with productName, description, and more.

Here's what that request would look like:

cURL

curl --request POST \
     --url 'https://embedded.runalloy.com/2024-03/one/commerce/products?credentialId=CREDENTIAL_ID' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
       "productStatus": "ACTIVE",
       "variants": [
         {
           "price": 40,
           "sku": "HOODIE-T"
         }
       ],
       "productName": "New Hoodie",
       "description": "A cool hoodie to keep you warm"
     }'

Help your users present accurate product information

By reading product information from users’ commerce platforms, you can ensure that your app always presents accurate images, pricing, descriptions and more to shoppers.