Retail Cloud API, SPI, and Webhook Overview

Retail Cloud supports common POS workflows with APIs, SPIs, and Webhooks. Retail Cloud provides a set of APIs for merchants to provide, update, or read data in the Retail Cloud system. Retail Cloud's backend systems hook into these APIs to complete the POS integration. Retail Cloud's SPIs provide extensibility and the opportunity to leverage outside systems for POS workflows.

• Environment: Used to determine URLs for OAuth2 and Retail Cloud API. Possible values: Production, Staging
• Retail Cloud secret: Used as header PredictSpring-Secret while calling Retail Cloud API
• x-api-key: Used as header x-api-key while calling Retail Cloud API
• OAuth2 client ID: Used for OAuth2 token generation
• OAuth2 client secret: Used for OAuth2 token generation

See Retail Cloud SPI Error Handling.

These tables provide a comprehensive list of Retail Cloud API endpoints along with their usage descriptions.

Create, search, update, and delete CMS users from Retail Cloud.

Manage inventory in Retail Cloud, including interactions related to cycle counts and receivings.

Send notifications directly to specific app users.

Create, update, and delete products in Retail Cloud.

Create, update, retrieve, and delete promotions in Retail Cloud.

Create, search, update, and deactivate store associates from Retail Cloud.

Manage store inventory.

Create, search, retrieve, and repost orders from Retail Cloud.

SPIs are outbound API calls made from Retail Cloud that expect a response from the customer system and alter the behavior of the transaction journey for an associate. On the merchant side, they are hosting a web server that listens to this API request and handles the same. In response, Retail Cloud expects a full JSON response that is used to update the cart or customer data (for example, Clienteling API, promotion calculation, etc.).

To implement the Retail Cloud SPI, provide both a staging (sandbox) environment for testing and a production environment. Requests to the SPI APIs take these forms.

https://<staging_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>

Example:

https://**staging.mycompany.com/spi**/1.0/customer/1234?api_key=ibafw4ehb2vhibdsih3vbadv

https://<production_path>/<api_version>/<api_path>?api_key={API_KEY}&<additional_request_parameters>

Example:

https://**www.mycompany.com/spi**/1.0/customer/1234?api_key=zmcnv9lzjkxn2vcl8nzcx

To implement the Retail Cloud SPI, provide an authentication mechanism for accessing the SPI APIs through the use of an API key. Retail Cloud provides suitable API keys (one for staging and one for production) to validate, and all SPI API requests contain an api_key request parameter.

If an invalid API key is supplied, the API must respond with a 401 Unauthorized response containing an empty response body.

Sample Request with Authentication

Sample Authentication Failure Response

1. In CMS, go to Store Management > Integrations > Custom Connectors.
2. Click Create.
3. For Connector Type, select SPI.
4. For Endpoint Name, select an endpoint. For example, CREATE_CUSTOMER.
5. Set the API Endpoint to an external endpoint for the SPI. For example, https://sample/external/endpoint/to/create/customer.
6. Select or enter the integration type. For example, HTTP_POST.
7. Set the header for the API in JSON Headers. Headers can be Content-Type or Authorization attributes (clientId or password). For example:

Retail Cloud's Custom Connection supports NetSuite's OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. This setup is configured directly in the CMS.

1. In CMS, go to Store Management > Integrations > Custom Connectors.
2. Edit an existing configuration or create a new one.
3. Turn on NetSuite OAuth for the OAuth Config. This automatically retrieves the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

You can define custom attributes to be passed in a product's SPI response. For example, when integrating with the Delivery Group SPI define custom attributes in the spiCustomProductAttributes setting, and these attributes are included in the SPI response.

1. In CMS, go to Store Management > Store Settings > Product and
2. Go to Merchant-specific product attributes to be provided in SPI request (spiCustomProductAttributes) and enter a comma-separated list of case-insensitive attributes from the product collection (For exampel, variantGroupId, salePrice, manufacturer, brand).

These tables provide a comprehensive list of Retail Cloud SPIs along with their usage descriptions.

Create, search, update, and retrieve details of a specific customer from an external system rather than from Retail Cloud’s system of record.

Customer Address

Used to create, search, update, and delete a customer's address from an external system rather than from Retail Cloud’s system of record

Inventory

Used for retrieving inventory count of products online or in-store from an external system rather than from Retail Cloud’s system of record, and for reverting reserved inventory

Loyalty

Used for retrieving loyalty points redeemed in a transaction and the available rewards for a customer.

Orders

Used to retrieve, search, and export orders from an external system rather than from Retail Cloud’s system of record

Important: Starting in June 2024, Retail Cloud has updated the order SPIs. Specifically, the JSON schema has been modified to use the transaction data model for exporting and importing store transactions, including sales, returns, and exchanges. The documentation is available in Retail Cloud API Specifications.

Other

Used to verify employee status, retrieve delivery/pickup dates, validate cart, etc.

Shipping Methods

Used for receiving applicable shipping methods from an external system rather than from Retail Cloud’s system of record

Taxes

Used to calculate taxes, retrieve tax exemptions, and download tax rates

• For product details, there are two fields orderProductList and productList. orderProductList contains a list of products sold while productList is a subset (if there have been any returns/exchanges) and it contains a list of products sold with returned products/quantities removed/adjusted. For example, productList gives you the remaining products in the order which are not returned. If mapping to an ERP system, orderProductList and returnProductList should be used instead of productList to simplify the ingestion logic.
• For fulfillment details, there are two fields omniFulfillmentType and fulfillmentType. If mapping to an ERP system for cash/carry/charge, fulfillmentType and fulfillmentSubType should be used instead of omniFulfillmentType

Webhooks are outbound API calls made from Retail Cloud to an external system when specified events are triggered on POS.

1. In CMS, go to Store Management > Integrations > Custom Connectors.
2. Click Create in the upper right.
3. Under Connector Type, select "Webhook".
4. Under Endpoint Name, select an endpoint (e.g., "CREATE_CUSTOMER").
5. Under API Endpoint, provide an external endpoint for the webhook (e.g., "https://sample/external/endpoint/to/create/customer").
6. Under Integration Type, select or enter the type of integration (e.g., "HTTP_POST").
7. Under JSON Headers, provide the header for the API. Headers can be Content-Type or Authorization attributes i.e., clientId/password. See example below:

Retail Cloud's Custom Connection supports NetSuite's OAuth authentication, ensuring secure access and synchronization of customer data while reducing the risk of authentication errors. This setup can be configured directly in the CMS.

Important: Before proceeding, ensure that an ERP configuration is properly set up in the CMS. Without this configuration, the SPI will fail to process and result in an error within the CMS.

1. In CMS, go to Store Management > Integrations > Custom Connectors.
2. Edit an existing configuration or create a new one.
3. Under OAuth Config, enable NetSuite OAuth. This will automatically retrieve the necessary OAuth credentials from the ERP configuration.
4. Save your changes.

Retail Cloud offers the ability to manually repost failed webhook events.

1. In CMS, go to Store Management > Reporting and Analytics > Repost Failed Webhook Events.
2. Search for the failed webhook event by configuring the search query parameters.
3. Click View Details to view the details of the payload inside the selected webhook event.
4. Click Repost to manually trigger a webhook event repost.

The table below provides a comprehensive list of all available Retail Cloud webhooks along with their usage descriptions.

E-Receipt

Used for sending order details for email purposes

Inventory Events

Used for sending inventory data to an external system

Orders

Used for sending order posting-related data to an external system

Others

Used for sending non-categorized data (e.g., void carts) to an external system

The API spec schema indicates that dates are represented with an integer data type. What is the expected date format we should use when passing dates to the API? Additionally, can you provide a sample date along with its transformed value as an example?

Dates are expected in epoch times, represented as integers (measured in milliseconds). Epoch time is the number of milliseconds that have elapsed since January 1, 1970, 00:00:00 UTC. See example:

• Example Date: 2023-01-15 08:30:00
• Epoch Time (in milliseconds): 1642246200000

See example with currentLoyatlyProfile. currentTier.expiryDate::

Can Multi-Region Feeds Be Managed Through the Product API?

Our platform supports Multi-Region Feeds, allowing the master region to run the product feed while enabling other countries to inherit the product metadata, with specific pricing and sizing data provided for each country. However, this capability does not extend directly through the Product API.

• For Multi-Region Pricing Updates: Currently, we do not offer a dedicated pricing API. For multi-region operations, pricing updates must be conducted through the CMS feed mechanism, allowing for regional-level adjustments.

• For Single-Region Pricing Updates: In a single-region setup, the Product API can be utilized to update pricing information. However, for multi-region scenarios, the Product API lacks a "region" field in its specifications (as observed in this guide).

• Workaround for Pricing Updates: Given the absence of a pricing API, pricing information must be included within POST and PUT calls when managing product data. If operating with a single instance per region, the Product API can facilitate pricing updates effectively.\

Do you offer GraphQL for precise querying?

GraphQL is not available externally. It is used exclusively for the POS app and CMS, and is not accessible to customers via the API specification.

How can I search by credit card number using the search order SPI?

To search by credit card number using the search order SPI, you need to map the card number to the appropriate fields in the payload. The card number should be included under the payment card section. Hotwax will then read this information, search for orders, and return the results.

Does Retail Cloud support query parameters for all of our SPIs?

No, Retail Cloud does not support dynamically populating query parameters. However, we do support setting up endpoints with static query parameters.

When we make a call to an endpoint, we use the provided URL exactly as it is configured. This means that merchants can receive the configured locale (e.g., cb-en-us) and store type (e.g., stores) as part of the URL. We do not apply any special handling or logic to these static query parameters; we simply call the URL as it is.

If merchants are comfortable with the static nature of the query parameters, they can configure them accordingly. This allows them to add conditional processing on their side. Additionally, merchants can use static query parameters to receive authentication codes.

Note: Dynamically populating query parameters is not supported.

For all SPIs, when error fields are returned with a 200 HTTP response code, should non-nullable fields still be included in the response? For example, in the customer detail API response, the loyaltyProfile field is not nullable and the profile field, while nullable, is required. Please confirm the expected behavior.

Non-nullable fields or any fields not needed in the response should be left out of the response entirely. Instead of inserting a null value for any field not being passed, it is recommended to exclude the field from the response.

In scenarios where a resource is not found and we would normally return a 404 status, should we return a 200 with error fields populated instead? For instance, if an associate tries to look up a return item based on a registry ID, and the registry ID is invalid, should we return a 200 with an error message instead of a 404?

If returning a 200 status code in a scenario with an empty result string and an error message, we should display no results and the error message. If returning a 400 status code, a generic error message will be displayed in the app, and the specific error message will be captured in the logs.

What is the expected response payload for the order webhook when the status code indicates success? What HTTP status code should we return, and what values should be included in the response fields as indicated in the Swagger documentation?

The current schema does not indicate any required fields, but we will update this. As of now, only a status code response is expected.

If the Address SPI setup, will the POS always trigger the endpoint and disregard the data in the customer SPI addressList object?

The POS utilizes the POST address SPI (CREATE_CUSTOMER_ADDRESS) to add an address from the cart's "Select Shipping Address" screen. Once the address is added, the POS relies on the addressList provided by CREATE_CUSTOMER_ADDRESS for the checkout process.

What triggers an Order to flow into the Repost Failed Webhook Report?

An order will be categorized as a failure and appear in the Repost Failed Webhook report if specific criteria are met during the order export process:

1. HTTP Response Status Code: The order export will fail if the HTTP response status code is in the 4xx or 5xx range, indicating a client or server error.
2. HTTP Response Payload: Even with a successful HTTP status code in the 2xx range, the order export will still be considered a failure if the response payload includes either or both of the following attributes:
   • errorMessage
   • errorCode
   • Example: If the HTTP status code is 200, but the payload contains an error message like the following, the order will be marked as a failure:

Is the eReceipt webhook qued in offline mode so that it can be sent once the POS returns to online mode?
The eReceipt webhook is triggered when the app calls the eReceipt API. No emails are sent when an order is synced. However, if automatic receipt emails are configured in the store settings, eReceipts will be sent for all orders, even in offline mode. Currently, no customer has automatic receipt emails enabled.

What happens if automatic eReceipts are enabled in offline mode?
If automatic eReceipt emails are configured, the system will generate and send eReceipts during offline sync for every transaction. In this case, it is recommended to remove the email CTA from the order confirmation layout.

Which settings should be enabled to ensure eReceipts are sent automatically in both online and offline modes?
The following settings in CMS need to be enabled:

• sendOrderConfirmationEmailAutomatically
• sendRefundEmailAutomatically
• HideReceiptEmailShare

Please note there is no option to send an email only when requested by the customer in offline mode once these settings are enabled.