Zinrelo Cartridge Integration with Salesforce Commerce Cloud

This article will guide you through SFCC integration with Zinrelo.

Introduction

In this document, you will learn how to install Zinrelo’s Salesforce Commerce Cloud cartridge and run the loyalty program on your Salesforce Commerce store.

Cartridge Installation Steps

Follow the below steps to integrate the cartridge:

📘

Please Note:

The plugin supports SFCC version 22.7.

Import metadata

Compress the metadata folder, upload it to Administration > Site Development > Site Import & Export, and import the file. This will import the metadata required (System Objects, Services, Jobs, etc.).

Note: The metadata folder is available within the package parallel to the cartridge folder.

Templates Override

Some SFRA templates- checkout/checkout.isml and product/productDetails.isml are overridden in order to add Zinrelo components. These are the templates that show checkout flow and the PDP page in SFCC.

📘

Note:

This is an optional setting. Enable it only when you want the product price to be displayed in the checkout page.

SFCC Integration SFCC Integration

Compilation

  • Put the int_zinrelo_sfra cartridge in parallel to other cartridges of the project. “int_zinrelo_sfra” is the plugin cartridge that consists of all the code changes that are needed to meet Zinrelo requirements. (Zinrelo repo currently contains other required cartridges such as base cartridge and webpack plugin which can be ignored.)
SFCC Integration
  • Compile the code using the regular compilation process in the project. Make sure that the Zinrelo cartridge is included in the webpack configuration. For example, if webpack is being used for compilation, add the Zinrelo cartridge in the sfraBuilderConfig.js file.

Cartridge Path Setup

Upload/deploy the code in the active code version and include int_zinrelo_sfra in the cartridge path of the site. It should be on the left of the base cartridge and on the right of any custom site cartridge.

For e.g. app_custom:int_zinrelo_sfra:app_storefront_base

SFCC Integration

Client ID Setup

In the Zinrelo integration, we’re using OCAPI and SCAPI endpoints. To be able to use these endpoints a client ID setup is required. Follow the below steps for the setup -

  • Create a Client ID and Password in Account Manager > API Client.
SFCC Integration
  • Provide the required roles for the test environment.
  • Add the following scope in the Allowed Scope section -
    sfcc.customerlists.rw and save.
  • Go to Business Manager Administration > Site Development > Open Commerce API Settings and configure the following settings:

Shop API OCAPI Settings

SFCC Integration
{
   "client_id": "<CLIENT_ID_HERE>",
   "resources": [
       {
           "resource_id": "/order_search",
           "methods": [
               "post"
           ],
           "read_attributes": "(**)",
           "write_attributes": "(**)"
       }
   ]
}

Data API OCAPI Settings

{
   "client_id": "<CLIENT_ID_HERE>",
   "resources": [
       {
           "resource_id": "/sites/*/coupons/*/multiple_codes",
           "methods": [
               "post"
           ],
           "read_attributes": "(**)",
           "write_attributes": "(**)"
       }
   ]
}
  • Set the Client ID and Client Password in the Access Token service. Go to Administration > Services > account.manager.generate.token.credentials and put Client ID in user and Client Password in the password field.

Accessing Zinrelo Settings in SFCC

To access Zinrelo settings in SFCC, follow these steps:

  • Log in to your SFCC account.
  • Navigate to Merchant Tools >> Custom Preferences.
  • From the list of preferences, select ZinreloConfigs.
SFCC Integration

Configuring Zinrelo Settings in SFCC

Enable/ Disable Zinrelo Integration

Enable Zinrelo: This setting will enable Zinrelo integration.

  • If you select “Yes”, it will enable the Zinrelo integration.
  • If you select “No”, you will not be able to see Zinrelo functionality on the website.
SFCC Integration

Authenticating Zinrelo Account with SFCC

To authenticate your Zinrelo account, you'll need the API key, key identifier, and partner ID.

Obtain these details from the Zinrelo admin console. For more details, refer to this document.

  • Zinrelo Partner ID: Enter the obtained partner ID.
SFCC Integration
  • Zinrelo API Key: Enter the store API key.
SFCC Integration
  • zinreloAPIKeyIdentifier: Enter the API key identifier.
SFCC Integration
  • Add Custom Attributes: To ensure seamless integration, it is crucial to incorporate two essential custom attributes:
    • Last website visit timestamp (Date Type)
    • External member id (String Type)

      📘

      Note: For the creation of these attributes, please contact your account manager at [email protected].

Showing Rewards in the Cart Page

Enable In-cart Redemption: Select “yes” from the dropdown to show rewards on the cart page.

SFCC Integration

Showing Potential Points and Text on the Product Page

Enable Reward Points Text On Product Pages: Select “yes” from the dropdown to display potential points to customers on the product page.

SFCC Integration SFCC Integration

Labeling Free Shipping Rewards

Zinrelo Free Shipping Label: Define the label for "Free Shipping Rewards" that appears when customers redeem them. You can customize this label here.

SFCC Integration

Preferred Language Mapping

(Only required if the store supports multi-language)

Preferred Languages: For multilingual stores, map your store's language to SFCC. Separate multiple mappings with commas.

SFCC Integration

For custom languages, replace “ja” and “zh” with the custom language abbreviations.

Cart Session Timeout

Cart Session Timeout (In minutes): Enter the time in minutes that will be considered to reject pending reward points for abandoned cart and send abandoned cart requests.

SFCC Integration

Selecting and Configuring Trigger for Awarding Points

You can trigger following status for awarding points to members:

  • Order created
  • Order placed/confirmation
  • Order shipped
  • Order paid

You have to specify the trigger on which you want to award points to your customer. From the given list of triggers, you can select just one. To specify the event, write to your account manager at [email protected].

Configuring Statues

  • Order created: For awarding points on order creation, enable “Enable Order Creation Event.”
SFCC Integration
  • Order placed/confirmation: For awarding points on order confirmation, enable “Enable Order Confirmation Event.”
SFCC Integration
  • Order shipped/ Order paid: For awarding points on order shipped/ order paid, you need to configure cron jobs. Following the given steps for configuring jobs:
    • Navigate to Administration > Operations > jobs > job steps > configure a step
    • Enter the type ID from steptypes.json.
    • Select the order event (for which this job should run) in orderStatus attribute and also populate the customOrderStatus with the ID of the orderStatus attribute i.e “orderStatus”.
SFCC Integration SFCC Integration

Configuring Triggers for Points Deduction

For point deduction, you need to configure the cron jobs for the following statuses:

  • Order canceled
  • Order fully returned
  • Order partially returned

When the status of SFCC order is changing to either shipped, returned or partially returned via OMS, the OMS flow should also update a custom status attribute in Order object i.e “orderStatus”.

Please Note: These custom attributes are created when the package is imported.

SFCC Integration

Partial Return Setup in SFCC

To set up the json payload for partial returns, please follow these steps.

Merchant Tools >> Ordering >> Orders >> Attributes >> Order Status (Please select order status as partiallyReturned) & In Returned Items, please pass returned products in below json format. Pid & qty will be changed according to the order. Apply the changes after they are done.

SFCC Integration
[
{
"pid": "013742335262M",
"qty": 1
},
{
"pid": "013742000283M",
"qty": 1
}
]

Please Note: For clients supporting online and/or Cash on Delivery (COD)/ offline, we recommend the following events setup.

  • Award points on order_paid event
  • Return points on order_cancelled, order_partially_returned and order_fully_returned.

For its steps, refer to this part of the document.

Purchase and return tracking

To configure a webhook you will need a webhook URL which will be sent by us. To obtain the url write to your account manager at [email protected].

  • Zinrelo Webhook URL: Enter the obtained webhook URL here.
SFCC Integration

Please Note: It is essential to clearly specify the webhook event for seamless integration.

Configuring Rewards in SFCC

To configure rewards in SFCC, please follow the given steps:

Define the rewards in Promotion

  1. Navigate to Merchant Tools>> Online Marketing>> Promotions.
  2. Click on the “New” button.
SFCC Integration
  1. Fill in the details and enable the “Is Zinrelo Promotion” toggle button. And apply.
SFCC Integration

Please Note: Make sure to select “None” in Exclusivity.

  1. In the Promotion Rule, you have to configure Zinrelo Rewards.
SFCC Integration
  • Fixed Amount Discount: When selected, the member receives a fixed discount on the order subtotal.
    • Promotion Class: Select “Order” and “With Number of Qualifying Products.”
    • Discount: Add 1 in “Buy”, fixed amount discount value you want to offer in “or More and Get” and select “Amount Off.”
SFCC Integration
  • Percentage Discount: When selected, the member will get some percent off applied to his order subtotal.

    • Promotion Class: Select “Order” and “With Number of Qualifying Products.”
    • Discount: Add 1 in “Buy”, percentage discount value you want to offer in “or More and Get” and select “Percent Off.”
    SFCC Integration
    • Free Shipping: When selected, the member will not be charged any shipping charges.
      • Promotion Class: Select “Shipping” and “With Number of Shipment- Qualifying Products.”
      • Discount: Select “Free” from the dropdown.
SFCC Integration
  • Product Redemption: When selected, the member will get a free product.
    • Promotion Class: Select “Order” and “With Number of Qualifying Products.”
    • Discount: Select “Bonus Products” and the product ID from the list of the products.
SFCC Integration

Once you obtain the product ID, copy and paste the ID into the Product ID text box in Product Redemption Reward in the Zinrelo admin console. Ensure the reward is enabled.

SFCC Integration

Manage Coupon Codes

Navigate to Merchant Tools >> Online Marketing >> Coupons.

  1. Click on the “New” button.
  2. Add ID, select “Yes” for Case Sensitive and select “Multiple Codes.” And save.
SFCC Integration
  1. Fill in the details, enable the coupon and set the redemption limit of 1 per coupon. And save.
SFCC Integration

Please Note: Coupon codes can be added to SFCC in bulk using OCAPI. You need to update the same coupon codes to Zinrelo for respective rewards.

Campaigns

Navigate to Merchant Tools >> Online Marketing >> Campaigns.

  1. Create a new campaign.
  2. Make all basic configurations and select the configured coupon from “Coupons.”
SFCC Integration

Configuring the Text

To configure the text on SFCC, navigate to Merchant Tools > Content > Content Asset.

Configure In-cart text

  1. Search for InCart to configure in-cart text on the website.
SFCC Integration
  1. Click on the ID to configure the text.
  2. Click on the hyperlink text “Lock.”
SFCC Integration
  1. Scroll down to Content > Body.
  2. Enter the text.
  3. Click on Apply.
  4. And then click on the hyperlink text “Unlock” to lock the configuration.

SFCC Integration

Configure reward text on the product page

  1. Search for PDP to configure reward text on the website.
SFCC Integration
  1. Click on the ID to configure the text.
  2. Click on the hyperlink text “Lock.”
SFCC Integration
  1. Scroll down to Content > Body.
  2. Enter the text
  3. Click on Apply
  4. And then click on the hyperlink text “Unlock” to lock the configuration.
SFCC Integration