commercetools Connect Marketplacer Accelerator

About the accelerator

The commercetools Marketplacer Accelerator for Connect provides the following functionality:

• Sync newly created Products in Marketplacer to commercetools
• Sync newly created Sellers in Marketplacer to commercetools

In both cases we employ Marketplacer webhooks to allow for a near real-time sync cadence.

The accelerator is certified for commercetools Connect, which essentially allows you to run it within your existing commercetools instance. You can read more about commercetools Connect here.

Solution Overview

The accelerator is implemented as a Google Cloud Function providing the following 2 HTTPS POST endpoints:

• create-variants-function: This endpoint receives an Advert webhook event from Marketplacer and uses it to create a product in commercetools
• create-custom-objects-function: This endpoint receives a Seller webhook event from Marketplacer and uses it to create a custom object in commercetools

Adverts in Marketplacer are analogous to products, hence why we make use of an Advert webhook.

Setting Up the Accelerator

commercetools set up

Pre-requisites

Before configuring the commercetools Connect Marketplacer Accelerator in commercetools you will require:

• An instance of commercetools and access to Merchant Center
• An API client created via Merchant Center
• API Client credentials set aside (you will need access to these later)
• An access token generated by making a call to the the Authorization API endpoint

Once you have these, you can move on to setting up the accelerator

Step 1: Search for the Accelerator

Make an API call to the following commercetools endpoint to return all certified Connect apps

GET: https://connect.{your-commercetools-region}.commercetools.com/connectors/search

The name of the app that you are looking for is: Marketplacer commercetools connector

You can further refine your search by providing various search criteria as outlined here.

When you locate the app that you want, be sure to copy the following values as you'll need these when creating a deployment:

• connector.id
• connector.version

Step 2: Obtain commercetools product identifiers

In order for the connector to successfully create products in commercetools it needs the following information:

• The Main Product Type
• The Root Category
• A Child Category (of the root)

We can obtain these values from the commercetools Impex tool - note the login credentials for Impex are the same as those for Merchant Center.

• Login to Impex
• Select API Playground

• Select Product Types for the endpoint:

• Running your query should return a series of JSON objects, select a key value for the Product Type that you want to work with. In the example below I've selected shirts:

Set this value aside as we'll be using that as our Main Product Type.

---

Back at the main Impex API Playground search page, select Categories for the endpoint:

• Running your query should return a series of JSON objects, select an id value for an appropriate Root Category, in the example below I have selected the id for the Men category:

Root categories should not have any "Ancestors".

Set this value aside as we'll be using that as our Root Category.

---

• Within the same result payload,(Categories search), find a suitable Child category. A suitable Child category would be one that has the Root category as an "ancestor", in the example below I've selected Tops:

Set this value aside as we'll be using that as our Main Child Category.

Step 3: Deploy the app

The next API call creates a deployment for your selected app, (in this case the Marketplacer connector). To ensure a valid call you need to provide a valid body payload as outlined below, (you will need to insert your own values where directed):

{
  "key": "{insert your own unique key value for this deployment}",
  "connector": {
    "id": "{the id as retrieved from the previous API call}",
    "version": {the version of the connector you want to deploy}
  },
  "region": "{your commercetools region}",
  "configurations": [
    {
      "applicationName": "create-custom-objects-function",
      "standardConfiguration": [
        {
          "key": "CTP_REGION",
          "value": "{your commercetools region}"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_PROJECT_KEY",
          "value": "{your API client project key}"
        },
        {
          "key": "CTP_CLIENT_ID",
          "value": "{your API client id}"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "{your API Client Secret}"
        },
        {
          "key": "CTP_SCOPE",
          "value": "{your api client scope}"
        }
      ]
    },
    {
      "applicationName": "create-variants-function",
      "standardConfiguration": [
        {
          "key": "CTP_REGION",
          "value": "{your commercetools region}"
        }
      ],
      "securedConfiguration": [
        {
          "key": "CTP_PROJECT_KEY",
          "value": "{your API client project key}"
        },
        {
          "key": "CTP_CLIENT_ID",
          "value": "{your API client id}"
        },
        {
          "key": "CTP_CLIENT_SECRET",
          "value": "{your API Client Secret}"
        },
        {
          "key": "CTP_SCOPE",
          "value": "{your api client scope}"
        },
        {
          "key": "mainProductType",
          "value": "{your Product Type}"
        },
        {
          "key": "rootCategory",
          "value": "{your Root Category}"
        },
        {
          "key": "childCategory",
          "value": "{your Child Category}"
        }
      ]
    }
  ]
}

Note: all the configured values are strings, with the exception of version which is a number, so be sure to omit quotes with this value.

Once you have constructed your payload make a POST request as follows:

POST: https://connect.{your-commercetools-region}.commercetools.com/{your-project-key}/deployments

This will create a deployment in the deploying state - you can read more about the deployments endpoint here.

Step 4: Check on your deployment

In order to use the connector you will need to ensure that the state transitions from: deploying to deployed, you can do this by querying your deployments as follows:

GET: https://connect.{your-commercetools-region}.commercetools.com/{your-project-key}/deployments

As part of the return payload for your deployment you should obtain:

• status: this should have a value of deployed
• results.applications[0].url
• results.applications[1].url

In the case of the 2x url values, you should have value for both:

• The Variants function
• The Custom Objects function

Put the 2 values for each url aside (and ensure that you tag them correctly against each function).

Marketplacer set up

Pre-requisites

Before configuring the commercetools Connect Marketplacer Accelerator in Marketplacer you will require:

• An instance of Marketplacer and access to the Operator Portal as an Admin

Once you have this, you can move on to setting up the accelerator in Marketplacer

Step 1: Create an Advert Webhook

Create an Advert Webhook in the Operator by following the instructions here, use the following values:

• Type: Advert
• Event Name (filter): Create
• URL: Use the url value for the create-variants-function that you obtained from the commercetools app deployment
• Headers: You can leave this blank, it is not required for the accelerator to work
• HMAC Key: You can leave this blank, it is not required for the accelerator to work
• GraphQL: Use the query listed below:

query ($id: ID!) {
  node(id: $id) {
    ... on Advert {
      __typename
      id
      legacyId
      title
      fullTitle
      description
      brand {
        name
      }
      displayImage {
        url
      }
      seller {
        businessName
      }
      variants {
        edges {
          node {
            id
            barcode
            sku
            countOnHand
            lowestPrice
            advert
            optionValues {
              nodes {
                name
                optionType {
                  name
                }
              }
            }
          }
        }
      }
    }
  }
}

When done click Save.

Step 2: Create a Seller Webhook

Create a Seller Webhook in the Operator by following the instructions here, use the following values:

• Type: Seller
• Event Name (filter): Create
• URL: Use the url value for the create-custom-objects-function that you obtained from the commercetools app deployment
• Headers: You can leave this blank, it is not required for the accelerator to work
• HMAC Key: You can leave this blank, it is not required for the accelerator to work
• GraphQL: Use the query listed below:

query ($id: ID!) {
  node(id: $id) {
    ... on Seller {
      __typename
      id
      businessName
      businessNumber
      emailAddress
      logoUrl
      marketplaceShippingRulesEnabled
      openingHours
      phone
      sellerRating
      storeDescription
      youtubeVideoUrl
      address {
        fullAddress
        mapUrl
      }
    }
  }
}

When done click Save.

Running the accelerator

Product Creation

To execute the Product create flow you will need to:

1. Create an Advert in Marketplacer

• This can be done via API
• Spreadsheet upload
• Via the Seller Portal

2. Once an Advert is created, this will trigger the Advert Create Webhook which will be received by the accelerator and create a product in commercetools
3. You can check that a product was created in commercetools either by:

• Using Merchant Center
• Using Impex
• Using the API

Seller (Custom Object) Creation

To execute the Custom Object create flow you will need to:

1. Create a Seller in Marketplacer

• This can be done via API
• Via the Seller Portal

2. Once a Seller is created, this will trigger the Seller Create Webhook which will be received by the accelerator and create a custom object in commercetools
3. You can check that a custom object was created in commercetools either by:

• Using Impex
• Using the API