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, you might want to use a custom processor.

This walkthrough describes how to: 

  1. Select an attribute template

  2. (Optional) Define new attributes for OrderCloud XP properties

  3. Create an OrderCloud Delivery Configuration

  4. Trigger the product sync

  5. (Optional) Set up the Search proxy

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.

  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 Order Cloud Product Spec 2 template.

    • For any other entity, select the Base Attribute Template.

  5. If you’re using OrderCloud’s 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.

  7. Click Save.

(Optional) Define new attributes for OrderCloud XP properties

If you want to return XP 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.

RequestResponse
{ 
  "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.

Do you have some feedback for us?

If you have suggestions for improving this article,