Build the My Account section using Propeller Commerce GraphQL API

Creating a user-friendly and personalized My account section for B2B customers is essential, as it serves as the central hub for account management. With the Propeller Commerce GraphQL API, building this section is intuitive and flexible, allowing you to customize the customer experience seamlessly. This tutorial walks you through key functionalities, including displaying customer data, managing addresses, providing access to orders and quotes, and working with favorite lists.

Why It’s Important

The B2B customer section is not just a place to view information; it’s the customer’s primary control center for managing orders, reviewing quotes, and interacting with account information. By leveraging Propeller's GraphQL API, we can create a highly tailored experience to give customers easy access to everything they need, helping to drive satisfaction and loyalty.

Key Topics Covered:

Displaying Customer-Specific Data
Customizing Account Addresses
Providing Access to Order History
Providing Access to Quotes
Displaying and Modifying Favorite Lists

Let’s dive into each of these areas.

1. Displaying Customer-Specific Data

To fetch account information for a logged-in user using the Propeller Commerce GraphQL API, you can use the viewer query. This query retrieves key information specific to the logged-in customer's account, including details like their name, email, contact information and associated addresses. The response will vary depending on whether the user is a Contact or a Customer.

In the context of the Propeller Commerce platform, Customer and Contact are two distinct entities that represent different types of users or user roles within the system.

Contact (B2B) represents an individual user who is part of a larger organization or company in a B2B setting. Contacts act on behalf of their company to manage transactions, request quotes, and interact with the platform.
Customer (B2C) represents an individual consumer in a B2C environment. This type of user interacts with the platform as the sole owner of their account, primarily for personal use.

Query Example: Fetching Orders

query GetUserData() { 
  viewer {
    __typename
    firstName
    middleName
    lastName
    email
    gender
    phone
    mobile
    primaryLanguage
    dateOfBirth
    isLoggedIn
    mailingList
    ... on Contact {
      userId: contactId
      debtorId
      company {
        companyId
        name
        taxNumber 
        addresses {
          id
          code
          firstName
          middleName
          lastName
          gender
          email
          country
          city
          street
          number
          numberExtension
          postalCode
          company
          phone
          notes
          icp
          type
          isDefault
        }
      }
    }
    ... on Customer {
      userId: customerId
      debtorId
      addresses {
        id
        code
        firstName
        middleName
        lastName
        gender
        email
        country
        city
        street
        number
        numberExtension
        postalCode
        company
        phone
        notes
        icp
        type
        isDefault
      }
    }
  }
}

Once you have the data, you can render it on the frontend in a personalized user profile section. This personalized account section could show:

Name and Contact Info: Display name, email, and phone for quick reference.
Company Information: Company name and VAT for business account validation.
Addresses: List of available addresses for easy selection during checkout. This setup provides a fully personalized dashboard, empowering the customer with easy access to their account details.

2. Customizing Account Addresses

In Propeller Commerce, customers can manage their addresses by using specific GraphQL mutations to either update an existing address, delete existing address or add a new one. Here’s how you can implement these functionalities.

1. Adding a New Address

To allow users to add a new address to their account, you can use the customerAddressCreate mutation if the user is Customer or companyAddressCreate mutation if the user is Contact . This mutation requires information about the new address, such as street address, city, postal code, country, user id and the type of address (e.g., billing or delivery).

Query Example: Create Customer Address

mutation createCustomerDeliveryAddress {
  customerAddressCreate(input: { customerId: 123, type: delivery, postalCode: "1234AB", city: "Amsterdam", country: "NL", street: "Test street" } ) {
    id
    street
    country
    postalCode
    city
  }
}

Once the mutation is successfully executed, it will return the new address details, including the address ID, which can be stored in the user’s dashboard for future modifications or deletions.

2. Modifying an Existing Address

To allow users to update an existing address, you can use the customerAddressUpdate mutation if the user is Customer or companyAddressUpdate mutation if the user is Contact. This requires the id of the address they want to update along with the new values for the fields they wish to modify.

Query Example: Modify Customer Address

mutation updateCustomerDeliveryAddress {
  customerAddressUpdate(input: { id: 123456, customerId: 123, type: delivery, street: "New street" } ) {
    id
    street
    country
    postalCode
    city
  }
}

Query breakdown

input: Fields to be modified. You must provide the address id and you can update one or several fields, including address city, postal code, country etc..

Make sure to fetch and display the current address data in a form so the user can easily see what they’re updating. On successful mutation, the response will contain the updated address details.

3. Deleting an Existing Address

To allow users to delete an existing address, you can use the customerAddressDelete mutation if the user is Customer or companyAddressDelete mutation if the user is Contact. This requires the id of the address they want to delete along with the user's id.

Query Example: Modify Customer Address

mutation deleteCustomerDeliveryAddress {
  customerAddressDelete(input: { id: 123456, customerId: 123 } ) 
}

On successful mutation, the response will return true.

By using these mutations, users can manage their account addresses directly from the dashboard, keeping their information up-to-date and improving the convenience of the ordering process.

3. Providing Access To Order History

To fetch all orders for a specific user in Propeller Commerce using the GraphQL API, you can use the orders query. This query retrieves a list of orders associated with the logged-in user, including details such as order status, date, and items in each order.

Query Example: Fetching Orders For A Specific User In B2B scenarios, orders may be filtered by the user who placed them or the company associated with the order. You can use the userId and companyIds fields to filter orders based on these criteria.

query GetUserOrders() { 
 orders(input: {userId: [12345], companyIds: [678]}) {
    items {
        id
        status
        date
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

By using orders query, you can provide a complete view of order history for the logged in user, making it easy for them to track past transactions and stay organized. This is especially useful in B2B applications where order history may be an essential part of ongoing business processes. For additional details on order management, refer to the Order Management Guide.

4. Providing Access To Quotes

To fetch quotes for a specific user in Propeller Commerce using the GraphQL API, you can use the orders query. This query retrieves all the quotations associated with the logged-in user, allowing them to view details such as quote status, items, and total quoted amount.

Query Example: Fetching Quotes In B2B scenarios, quotes may be filtered by the user who placed them or the company associated with the quote. You can use the userId and companyIds fields to filter quotes based on these criteria.

query GetUserQuotes() { 
 orders(input: { type:quotation, status: "QUOTATION", userId: [12345], companyIds: [678]}) {
    items {
        id
        status
        date
        validUntil
        total {
            gross
            net
            tax
        }
        items {
            id
            quantity
        }
    }
  }
}

This query fetches a list of quotations for a specific user, filtered by the quotation type, status, user ID, and company ID. The returned data includes essential information like the quotation ID, status, creation date, expiration date, total amounts (gross, net, and tax), and a list of items with their quantities. By implementing this query in the user dashboard, you provide users with easy access to their quotations, enabling them to review, track, and manage their quotes efficiently. This is particularly beneficial for B2B applications where quotations are crucial for planning and procurement decisions.

5. Displaying and Modifying Favorite Lists

To fetch favorite lists for a user using the Propeller Commerce GraphQL API, you can use the favoriteLists query. Favorite lists enable users to save products they frequently buy or plan to buy in the future, offering convenience and improving user experience on a B2B ordering portal.

Favorite lists allow users to:

Save and quickly access frequently purchased products.
Group products into multiple favorite lists.
Simplify reordering for B2B customers who often buy the same items.

The Propeller API provides functionality to fetch these lists with details about the products they contain.

Query Example: Fetching Favorite Lists
The favoriteLists query retrieves all favorite lists associated with the logged-in user, including the products saved in each list.

query GetFavoriteLists {
  favoriteLists(input: { contactId: 12345 }) {
    itemsFound
    page
    offset
    items {
      id
      name
      isDefault
      products {
        items {
          names {
            value
            language
          }
          sku
        }
      }
    }
  }
}

Query Breakdown

input: Filters the favorite lists based on the provided criteria.
- contactId: The unique identifier of the contact whose favorite lists are being fetched.
itemsFound: The total number of favorite lists found matching the criteria.
page: The current page number of the results.
offset: The amount of items to show per page.
items: An array containing the favorite lists. Each item includes:
- name: The name of the favorite list.
- id: The unique identifier of the favorite list.
- isDefault: A boolean indicating whether this is the default favorite list.
- products: Contains the products within the favorite list.
  - items: An array of products in the favorite list. Each product includes:
    - names: An array of objects representing the product's name in different languages. Each object includes:
      - value: The name of the product.
      - language: The language code corresponding to the product name.
    - sku: The stock-keeping unit, a unique identifier for the product.

To enhance functionality, consider adding the following:

Adding a Product to Favorites
Use the favoriteListAddItems mutation to allow users to add a product to their favorite lists.

mutation {
  favoriteListAddItems(
    id: "672e1f7bd41e467b8e9341b2"
    input: { productIds: 1234 }
  ) {
    id
    name
    isDefault
    products {
      itemsFound
      items {
        id
        names {
          value
          language
        }
        sku
      }
    }
  }
}

Query Breakdown:

id: The unique identifier of the favorite list to which products are being added.
input: An object containing the details of the products to add.
- productIds: An array of unique identifiers for the products to be added to the favorite list.
Response Fields:
- id: The unique identifier of the favorite list after the products have been added.
- name: The name of the favorite list.
- isDefault: A boolean indicating whether this favorite list is the default one for the user.
- products: An object containing details about the products in the favorite list.
  - itemsFound: The total number of products found in the favorite list.
  - items: An array of product objects in the favorite list. Each product includes:
    - id: The unique identifier of the product.
    - names: An array of objects representing the product's name in different languages. Each object includes:
      - value: The name of the product.
      - language: The language code corresponding to the product name.
    - sku: The stock-keeping unit, a unique identifier for the product.

This mutation facilitates the management of favorite lists by allowing users to add multiple products simultaneously, enhancing the user experience on the platform.

Removing a Product from Favorites
Use the favoriteListRemoveItems mutation to allow users to remove a product from their favorite lists.

mutation {
  favoriteListRemoveItems(
    id: "672e1f7bd41e467b8e9341b2"
    input: { productIds: 1234 }
  ) {
    id
    name
    isDefault
    products {
      itemsFound
      items {
        id
        names {
          value
          language
        }
        sku
      }
    }
  }
}

Query Breakdown:

id: The unique identifier of the favorite list from which products are being removed.
input: An object containing the details of the products to remove.
- productIds: An array of unique identifiers for the products to be removed from the favorite list.
Response Fields:
- id: The unique identifier of the favorite list after the products have been removed.
- name: The name of the favorite list.
- isDefault: A boolean indicating whether this favorite list is the default one for the user.
- products: An object containing details about the products remaining in the favorite list.
  - itemsFound: The total number of products found in the favorite list after the removal operation.
  - items: An array of product objects remaining in the favorite list. Each product includes:
    - id: The unique identifier of the product.
    - names: An array of objects representing the product's name in different languages. Each object includes:
      - value: The name of the product.
      - language: The language code corresponding to the product name.
    - sku: The stock-keeping unit, a unique identifier for the product.

This mutation facilitates the management of favorite lists by allowing users to remove multiple products simultaneously, enhancing the user experience on the platform.

Creating a New Favorite List

Use the favoriteListCreate mutation to allow users to organize products into new favorite lists.

mutation {
  favoriteListCreate(input: { contactId: 12345, name: "Test fav list" }) {
    id
    name
    isDefault
  }
}

Query Breakdown:

input: An object containing the details required to create the favorite list.
- contactId: The unique identifier of the contact (B2B) for whom the favorite list is being created.
- name: The name assigned to the new favorite list. This helps the user identify and manage their lists effectively.
Response Fields:
- id: The unique identifier of the newly created favorite list.
- name: The name of the favorite list, as specified in the input.
- isDefault: A boolean indicating whether this favorite list is set as the default for the user.

This mutation enables users to organize their preferred products by creating personalized favorite lists, enhancing their shopping experience on the platform.

By implementing the favoriteLists query and supporting mutations, you can provide users with a powerful tool to save and manage their favorite products, making their experience more streamlined and enjoyable.

Conclusion

Customizing the user dashboard using the Propeller Commerce GraphQL API offers unparalleled flexibility and efficiency for building a tailored B2B experience. By leveraging the API's robust capabilities, businesses can provide customers with a centralized hub for managing their accounts, streamlining processes such as accessing order history, reviewing quotations, and managing favorite lists.

The key topics covered in this tutorial illustrate how intuitive and powerful the API is, empowering developers to implement essential functionalities like:

Fetching and displaying personalized customer data.
Managing and customizing account addresses.
Viewing order history and tracking transactions.
Managing quotations for improved procurement workflows.
Organizing and utilizing favorite lists to simplify reordering.

These features not only enhance the usability of the platform but also foster better customer engagement and satisfaction by simplifying complex workflows. By following the steps outlined in this tutorial, you can create a user-friendly, efficient, and feature-rich dashboard that meets the unique needs of your B2B customers.

Build the My Account section using Propeller Commerce GraphQL API

Why It’s Important​

Key Topics Covered:​

1. Displaying Customer-Specific Data​

2. Customizing Account Addresses​

1. Adding a New Address​

2. Modifying an Existing Address​

3. Deleting an Existing Address​

3. Providing Access To Order History​

4. Providing Access To Quotes​

5. Displaying and Modifying Favorite Lists​

Conclusion​

Why It’s Important

Key Topics Covered:

1. Displaying Customer-Specific Data

2. Customizing Account Addresses

1. Adding a New Address

2. Modifying an Existing Address

3. Deleting an Existing Address

3. Providing Access To Order History

4. Providing Access To Quotes

5. Displaying and Modifying Favorite Lists

Conclusion