Introducing Flows relationships

Andrew Waters profile picture Written by: Andrew Waters - Published on: 20 Jun 2018
We’re excited to announce a new feature to flows that offers more flexibility when working with flows. You now have the ability to create a new field type which creates relationships to both core resources and to custom flows.

For example, if you wanted to create wishlist functionality for your store, you can create a custom flow for your wishlist that manages relationships between a single customer and products in your catalog.

The API Reference has had the new endpoints added and if you want to reach out, please get in touch via the forum.

Tutorial: Added relationships to your Flows

A relationship is the way two or more people or things are connected. In the context of commerce, there are a number of ways that two things can be connected - for example, a product to a category or a customer to an order.

For the most imperative of relationships, the moltin API already handles these relationships as first-class citizens in that they are clearly documented because of their importance.

If you need to recap, please check out Andy’s introduction to Flows and our extended entities post.

Our latest update to the platform allows you to create a new relationship field on all of your core resource and custom Flows as well.

Let’s take a look at some examples of how they can be used.

Wishlists

You want to give your customers a way to create wishlists so that they can save their interest in some of your products. It’s a fairly common feature, so here’s how you can implement it (securely) using the API.

First, we need to create our custom flow, called “Wishlists”:

  curl -X "POST" "https://api.moltin.com/v2/flows" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "flow",
    "name": "Wishlist",
    "slug": "wishlist",
    "description": “Allow customers to store products they want to purchase at a later date",
    "enabled": true
  }
}'

Now that we have an entity which will store a customer’s desired products, we will need a new field to do that. It is worth noting that because this is a relationship, we do not send the required field that other field types observe:

  curl -X "POST" "https://api.moltin.com/v2/fields" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "field",
    "name": "Products",
    "slug": "products",
    "field_type": "relationship",
    "validation_rules": [
  {
      "type": "one-to-many",
      "to": "product"
  }
    ],
    "description": "Wishlist Products",
    "unique": false,
    "enabled": true,
    “required”: false,
    "relationships": {
  "flow": {
      "data": {
          "type": "flow",
          "id": “{WISHLIST_FLOW_ID}"
      }
  }
    }
  }
}'

Now our custom Flow is setup, we need to create an entry:

  curl -X "POST" "https://api.moltin.com/v2/flows/wishlist/entries" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "entry"
  }
}'

This is an empty entry and we now need to pass in our relationship to products:

  curl -X "POST""https://api.moltin.com/v2/flows/wishlist/entries/{ENTRY_ID}/relationships/{PRODUCT_FIELD_SLUG}" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": [
    {
  "type": "product",
  "id": "ba9ba29d-06da-4ba9-9e2e-f0e776703324"
    },
    {
  "type": "product",
  "id": "394916e8-1d47-44a0-b5d0-a5a61b71bab8"
    }
  ]
}'

Then we can get all of our wishlists:

  curl https://api.moltin.com/v2/flows/wishlist \
     -H "Authorization: Bearer XXXX"
  {
  "data": {
    "id": "{ENTRY_ID}",
    "type": "entry",
    "relationships": {
"products": {
  "data": [
    {
      "type": "product",
      "id": "ba9ba29d-06da-4ba9-9e2e-f0e776703324"
    },
    {
      "type": "product",
      "id": "394916e8-1d47-44a0-b5d0-a5a61b71bab8"
    }
  ]
}
    }
  }
}

But we have an issue: how do we know which customer owns each wishlist? With what we have so far, it’s impossible to tell, we just have the IDs of the wishlists and the products within them.

There are two ways we can conceptually designate a wishlist to a customer - by creating a relationship from the wishlist to the customer or by creating a relationship from a customer to the wishlist. When you take into account the fact that all Flows are accessible to reads to an implicit grant type request, it is more secure to create the relationship from the customer to the wishlist - this will mean you are not opening up access to your customer IDs to implicit requests.

Let’s create a Flow on our customer entity if we don’t already have one:

  curl -X "POST" "https://api.moltin.com/v2/flows" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "flow",
    "name": "Customers",
    "slug": "customers",
    "description": "Extends the default customer object",
    "enabled": true
  }
}'

Now let’s create the relationships field that will link a customer to a wishlist (note that we’re going to create a ‘one to many’ relationship because we might want customers to create multiple wishlists):

  curl -X "POST" "https://api.moltin.com/v2/fields" \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
  "data": {
    "type": "field",
    "name": "Wishlists",
    "slug": "wishlists",
    "field_type": "relationship",
    "validation_rules": [
  {
      "type": "one-to-many",
      "to": "product"
  }
    ],
    "description": "Customers wishlists",
    "unique": false,
    "enabled": true,
    "relationships": {
  "flow": {
      "data": {
          "type": "flow",
          "id": “{CUSTOMER_FLOW_ID}"
      }
  }
    }
  }
}'

We now have the ability to send updates to customers, including their relationships:

  curl -X POST https://api.moltin.com/v2/customers/{CUSTOMER_ID}/relationships/wishlists \
    -H "Authorization: Bearer XXXX" \
    -d $'{
     "data": [
  {
      "type": "wishlist",
      "id": "{WISHLIST_ENTRY_ID}"
  }
    ]
}'

We’ve saved the wishlist to a customer, so when we make API calls to get that customer we will now see the wishlist(s) directly on the customer data object:

  curl -X GET https://api.moltin.com/v2/customers/{CUSTOMER_ID} \
     -H "Authorization: Bearer XXXX"
  {
  "data": {
    "id": "{CUSTOMER_ID}",
    "type": "customer",
    "name": "Ron Swanson",
    "email": "ron@swanson.com",
    "password": true,
    "relationships": [
  "wishlists": [
      {
          "type": "wishlist",
          "id": "{WISHLIST_ENTRY_ID}"
      }
  ]
    ]
  }
}

And we can use the include parameter in our request:

  curl -X GET https://api.moltin.com/v2/customers/{CUSTOMER_ID}?include=wishlists \
     -H "Authorization: Bearer XXXX"
  {
  "data": {
    "id": "c8c1c511-beef-4812-9b7a-9f92c587217c",
    "type": "customer",
    "name": "Ron Swanson",
    "email": "ron@swanson.com",
    "password": true,
    "relationships": [
  "wishlists": [
      {
          "type": "entry",
          "id": "{WISHLIST_ENTRY_ID}"
      }
  ]
    ],
    "included": {
  "wishlists": [
      {
          "id": "{WISHLIST_ENTRY_ID}",
          "type": "entry",
          "relationships": {
              "products": {
                  "data": [
                      {
                          "type": "product",
                          "id": "ba9ba29d-06da-4ba9-9e2e-f0e776703324"
                      },
                      {
                          "type": "product",
                          "id": "394916e8-1d47-44a0-b5d0-a5a61b71bab8"
                      }
                  ]
              }
          }
      }
  ]
    }
  }
}

As always, we invite you to use these new features and if you have any requests or ideas on how we should expand these to make them even more useful, leave some feedback in the forum.

Build something amazing with Moltin