---
title: "Integrate with OrderCloud"
slug: "integrate-with-ordercloud"
abstract: "How to use the built-in integration to sync OrderCloud data to Sitecore Search."
---
# Integrate with OrderCloud

You can use the built-in integration between Sitecore Search and OrderCloud to easily send data into Search, after the data is in OrderCloud. The built-in integration automatically sets up the infrastructure to sync data, such as product or category data, store data for multilocation retailers, and any other entity. To use the integration, you must first set up your domain and then trigger the product sync.

This ensures that OrderCloud product visibility and pricing rules are applied in the search experience delivered by Search. 

You can use the integration for full syncs and incremental syncs. If you choose incremental syncs then only updated products are synced, instead of the full catalog.

> [!note]
> Even though the out-of-the-box product sync and proxy offered by OrderCloud handles most commerce use cases, hosting your own processor is recommended for more complex scenarios. For instance, if you have requirements around [multilevel (store or group) search experiences](https://doc.sitecore.com/search/en/users/search-user-guide/multilevel-business-operations-for-bopis.html), you might want to use a custom processor.

This walkthrough describes how to: 

:::walkthrough
1. [Select an attribute template](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrate-with-ordercloud.html#select-an-attribute-template)
2. [(Optional) Define new attributes for OrderCloud XP properties](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrate-with-ordercloud.html#optional-define-new-attributes-for-ordercloud-xp-properties)
3. [Create an OrderCloud Delivery Configuration](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrate-with-ordercloud.html#create-an-ordercloud-delivery-configuration)
4. [Trigger the product sync](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrate-with-ordercloud.html#trigger-the-product-sync)
5. [(Optional) Set up the Search proxy](https://doc.sitecore.com/search/en/developers/search-developer-guide/integrate-with-ordercloud.html#optional-set-up-the-search-proxy)
:::

> [!note]
> **Before you begin**
> -   Ensure you have access to OrderCloud with the **Marketplace Admin** role and the **ProductSyncConfigAdmin** and **DeliveryConfigAdmin** permissions.
>
> -   Ensure you have access to Sitecore Search with the **TechAdmin** role. For the OrderCloud sync to work, you must have the product entity and its attributes on Search.

## Select an attribute template

To set up your search domain, select an attribute template and then define a source for the OrderCloud sync target. Use the API Push connector to enable OrderCloud to send the incremental updates to Sitecore Search.

To select an attribute template:

1. In Sitecore Search, on the main menu, click **Administration** > **Domain Settings**.
2. On the **General Settings** tab, click **Entities** > **Edit**.

    > [!note]
    > If you don't see **Entities** on the **General Settings** tab, your domain is not enabled for [multiple entities](https://doc.sitecore.com/search/en/users/search-user-guide/configure-entities.html).

3. Click the entity you want to sync, such as *Product*.
4. In the **Attribute Template** drop-down menu, select a template to map attributes that match the OrderCloud data model.
    - For product entities, select the **OrderCloud Product Template v3** template.
    - For any other entity, select the **Base Attribute Template**.
5. If you’re using [OrderCloud’s extended properties](https://ordercloud.io/knowledge-base/extended-properties) to add business specific properties to the OrderCloud data model, add those as attributes in Sitecore Search.
6. Create a source of type [API Push](https://doc.sitecore.com/search/en/users/search-user-guide/en/configure-api-push.html).
7. Click **Save**.

## (Optional) Define new attributes for OrderCloud XP properties

If you want to return [XP properties](https://ordercloud.io/knowledge-base/extended-properties) in the API response of a synced OrderCloud entity or use them for filtering, faceting, rules, and additional search experiences, you must set up those XP properties as attributes in Sitecore Search.

To set up new attributes for your XP properties:

1. On the menu bar, click **Administration** > **Domain Settings** > **Attributes**.
2. In the **Entity** drop-down menu, select **Product**.
3. Click **Add Attribute** and type the attribute name using lowercase letters with an underscore representing nesting.

    For instance, an attribute called `xp.Brand` in OrderCloud must be named `xp_brand` in Sitecore Search.

4. To show product thumbnails in Sitecore Search, create an XP property in OrderCloud called `xp.ThumbnailImageUrl`.

## Create an OrderCloud Delivery Configuration

Now that you have set up your domain by selecting an attribute template and creating a source, you must create an OrderCloud delivery configuration.

To create a delivery configuration:

1. Log in to OrderCloud and click **API Console**.
2. In the main menu, in the **Integrations** section, click **Delivery Configurations**.
3. In the drop-down menu at the top, select the `POST` operation to create a new delivery configuration.
4. Select the **Enabled** check box.
5. In the **Search Ingestion** section, fill in the following fields:
    - **Domain** - your Search domain ID.
    - **Source** - your Search source ID.
    - **Endpoint** - your Search source endpoint URL.
    - **Entity** - enter *product*.
    - **API Key** - your Search source API key.

    > [!note]
    > -   To find the domain ID, on the menu bar, click **Home** and then hover over your domain name.
    >
    > -   To find the source ID, endpoint URL, and API Key, on the menu bar, click **Sources**, and then click a source. On the **Source Settings** page, click **Source Information**.

6. Click **Send**.
7. In the main menu, in the **Integrations** section, click **Product Synchronization**.
8. In the drop-down menu at the top, select the `PUT` operation to create or update a product sync.
9. In the **Request Body**, select the **Sync Product Changed** check box to sync products when they’re created or updated, and select the **Sync Product Deleted** check box to sync products when they're deleted.
10. In the **Delivery Config ID**, enter the ID and click **Send**.

Repeat this process for other Sitecore Search entities (such as *categories*, *stores*/*suppliers*, or *inventory*). Use the **Entity Synchronization** endpoint to create these respectively.

## Trigger the product sync

After setting up the connection in OrderCloud, you're ready to trigger the sync from OrderCloud into Sitecore Search.

> [!note]
> Before performing a full sync on either a catalog or a category, we recommend that you perform an incremental sync on a single product to confirm if your setup is correct. You can do this by running a `PATCH` query to update the product with a new value and then executing the incremental sync.

To trigger the sync:

1. In OrderCloud, click **Self-service** > **Sync tools**.

    > [!note]
    > If you’re using the OrderCloud Portal, go to **Marketplaces** > **Product sync**.

2. To sync the entire catalog, in the **Catalog ID** field, enter the ID.

    Alternatively, to sync only one category, in the **Catalog ID** field, enter the ID, and in the **Category ID** field, enter the ID.

3. Select the **I’m not a robot** check box.
4. Click **Submit**.
5. In Sitecore Search, on the main menu, click **Content Collection**.
6. Click the synced entity, for example, *Product*. The page lists the products from OrderCloud.

    > [!note]
    > If you selected the **Sync Product Changed** and/or **Sync Product Deleted** options, any time products are created, changed, or deleted in OrderCloud, those changes sync to Search.

In Sitecore Search, when you click **Sources**, you can now see an exclamation mark next to a source indicating that it’s queued for indexing. Indexing might take some time to complete, depending on the size of the source.

You can also go to **Analytics** > **Sources** > **Overview**, to view detailed information for all sources on a range of metrics. To view details of a specific source, select it from the list of sources. This gives you information about the source, the summary of its last run, and the number of jobs run. To view details of a specific job, select it from the graph or **Job Run List**.

## (Optional) Set up the Search proxy

With the Sitecore Search proxy, you can get accurate product visibility and pricing from OrderCloud. It also lets you sync multi-locale and non-OrderCloud attributes stored in another system that's required by Search. This is an optional step. You don't need the proxy to sync data from OrderCloud. Use it only if you have a complex marketplace with multiple prices for each product and/or limited product visibility.

To set up the proxy:

1. In OrderCloud, in the top-right corner, in the drop-down menu with your Marketplace name, make a note of the **OrderCloud Region** and **Marketplace ID**.
2. In Search, on the menu bar, click **Sources**, and then click a source. On the **Source Settings** page, click **Source Information** and make a note of the **Search Ingestion API URL**.
3. Log a support case with this information.

### Return accurate products and pricing using the proxy

The payload submitted to the proxy endpoint from a buyer front end is identical to that in Search, except for an additional `ordercloud` section as shown in the following. By appending the visibility rules of the current user to the given filters and applying the proper pricing, this proxy lets you take advantage of all the features available in Search.

```csharp
{
  "context": {
    "page": {
      "uri": "/"
    },
    "user": {
      "uuid": "173929009-e4-05-47-1p-boo1kknmlw-1708358871002"
    }
  },
  "ordercloud": {
      "sellerId": "12345",
      "requiredInventoryLocations": [
            "*-0044"
        ]  },
  "widget": {
    "items": [
      {
        "rfk_id": "rfkid_6",
        "search": {
          "content": {},
          "suggestion": [
            {
              "name": "auto_suggester",
              "max": 6
            }
          ],
          "limit": 6
        },
        "entity": "product"
      }
    ]
  }
}
```

To call the proxy, you need a bearer token. You can retrieve this by calling OrderCloud’s `oauth/userinfo` endpoint with a valid OrderCloud user token. This returns a bearer token containing all the user’s contextual information that you can use to call the proxy.

Proxy endpoint format: `https://uswest-integrations.ordercloud.io/api/v1/search/{domain}`

Region specific endpoints:

- US West - `https://uswest-integrations.ordercloud.io/`
- Europe West - `https://westeurope-integrations.ordercloud.io/`
- US East - `https://useast-integrations.ordercloud.io/`
- Japan East - `https://japaneast-integrations.ordercloud.io/`
- Australia East - `https://australiaeast-integrations.ordercloud.io/`

If you only need to ensure that you're showing the correct products and prices to the correct buyers, this integration does this for you using the proxy method. If you have additional use cases, such as sorting by price or custom rules around product inventory (for example, bury or boost), then you’ll also need to use the multistore/multigroup functionality in Sitecore Search.