Integration

This guide will walk you through the simple process of implementing Shipped, so you can start offering shipping protection and carbon offset to your customers. The cartridges are compatible with SiteGenesis JavaScript Controller (SGJC) and Salesforce reference Architecture (SFRA).

Shipped Suite Repository

Component overview

  1. Cartridge Features
    This integration enables the following features:
    • Order export to Shipped Suite API upon order completion
    • Display of Shipped widget in cart or checkout
    • Creation of Shipped Shield and/or Shipped Green line items on orders
    • Full product catalog export into Shipped Suite API (optional, but recommended)
  2. Use Cases
    For merchants, primary use cases include:
    • Maintain core Shipped functionality directly within Business Manager
    • Display Shipped Shield and/or Green widget in Cart or Checkout
    • Capture customer behavior with Shipped’s analytics module
    • Generate contracts for newly purchased package assurance and/or carbon offset with Shipped
    • Cancel contracts for canceled orders or when customer wants to cancel Shipped Shield and/or Green
      For customers, primary use cases include:
    • Include Shipped Shield and/or Green to their order in the Cart or Checkout page
    • View details, including coverage and terms & conditions about the Shipped Shield and/or Green offer
    • Remove Shipped Shield and/or Green from Cart or Checkout (either by removing the main product or the Shipped widget)
  3. Compatibility
    This cartridge has been developed and tested against Commerce Cloud Digital 22.10 and integrated on top of SFRA and SGJC.
  4. Privacy Policy on Payment
    Shipped does not handle payments from the end-user. The merchant is responsible for charging the end-user for the Shipped Shield and/or Green purchase, using the existing tenders that are currently supported on the specific environment.

Implementation

Upload Cartridges

For version specific upload instructions, please see Cartridge Guide in the documentation directory.

Business Manager Setup

Import Metadata

  1. Go to Business Manager -> Administration -> Site Development -> Import & Export.
  2. Click on Upload and upload the following files from the cartridge.
    • ./metadata/system-objects.xml
    • ./metadata/custom-objects.xml
  3. Then go to Business Manager -> Administration -> Site Development -> Import & Export.
    1. Under the Meta Data section, click on Import and select the previously uploaded file.
    2. Click Next, wait for the validation to finish, click Next again, and then click on Import.
    3. Repeat this process so that both files are imported.

Import Custom Jobs

  1. Go to Business Manager -> Administration -> Operations -> Import & Export.
  2. Click on Upload and upload the following file from the cartridge.
    • ./metadata/jobs.xml
  3. Then go to Business Manager -> Administration -> Operations -> Import & Export.
    1. Under the Jobs section (not Jobs (Deprecated)), click on Import and select the previously uploaded file.
    2. Click Next, select REPLACE when prompted, and click Next.
    3. Wait for the validation to finish, click Next again, and then click on Import.

Import Services

  1. Go to Business Manager -> Administration -> Operations -> Import & Export.
  2. Click on Upload and upload the following file from the cartridge.
    • ./metadata/services.xml
  3. Then to go Business Manager -> Administration -> Operations -> Import & Export.
    1. Under Services section, click on Import and select the previously uploaded file.
    2. Click Next, select MERGE when prompted, and click Next.
    3. Wait for the validation to finish, click Next again, and then click on Import.

Custom Configurations

  1. Go to Business Manager -> Merchant Tools -> Site Preferences -> Custom Preferences -> Shipped Configuration.
  2. Required configurations:
    • Enable Shipped: Select “Yes.” This enables the Shipped Suite Widget, which is required for Shipped Suite functionality.
    • Environment: Select “staging” when on sandbox or developing. Change to “production” for production deployment.
    • Public API Key: Obtain a publishable/public API key from the Shipped Suite Admin. Please reach out to Shipped Suite support if you are unsure about how to obtain this.
    • Shipped Shield: Select “Yes” if you are using the Shipped Shield feature, otherwise select “No”.
    • Shipped Green: Select “Yes” if you are using the Shipped Green feature, otherwise select “No”.
  3. Custom configurations:
    • The remaining configurations are optional/advanced. Please consult the Shipped Suite support team if you think you may need to change additional configuration options.

Service Configurations

  1. Go to Business Manager -> Administration -> Operations -> Services.
  2. Click on the Credentials tab
    1. Obtain a secret API key from the Shipped Suite Admin and enter it into the Password field. Leave the User field blank.
    2. Note: By default, the Service is configured to use Shipped Suite’s staging/sandbox API endpoint. When moving to production, be sure to update the Service configuration to point to the production Shipped Suite API.

Advanced Integrations/Customizations

Please see Advanced Integrations/Customizations file in documentation directory.

Failover/Recovery process

This cartridge’s operations are based on the exchange of data via the Shipped API. Please reach out to the Shipped Suite support team at [email protected] for any integration questions or issues.

Testing

  1. Enable Shipped
    If you have set to enable Shipped, go to Implementation section 5 Custom Configuration to enable and configure Shipped.
  2. Shipped Shield/Green Offers
    1. Add item to cart
      Navigate to any item and add it to the cart.
    2. Confirm Shipped Shield/Green widget is visible
      Proceed to Checkout and confirm Shipped Shield/Green widget is visible on the page.
      If Cart is the selected widget location, proceed to the Cart page instead of Checkout and continue with the following steps.
    3. Test Remove/Add function
      Remove/Add function is working properly when Shipped Shield/Green line item is removed/added respectively.
    4. View Learn more modal
      Click on the “Learn more” link in the widget and confirm the content of the modal is shown properly.
    5. Complete the checkout process.
  3. Sync Job (Staging only)
    1. Go to Business Manager -> Administration -> Operations -> Jobs and click on Shipped Sync Orders.
    2. Click on the Job Steps tab.
    3. Click on Scope and select the relevant site(s) and click Assign.
    4. Click Run Now.
      The order will populate in Shipped Suite merchant admin once the job is synced properly.

Operations, Maintenance

  1. Data storage
    Shipped cartridges extend Salesforce Commerce Cloud system objects to store related Shipped data form requests. The following objects were extended: order and SitePreferences.
  2. Support
    In case when service API doesn’t respond, Shipped will not be available to customers. This does not affect the overall checkout process.
    If there are any availability issues, Shipped Suite support can be reached at [email protected].