Query Create and Update Customer via GraphQL

Essential knowledge

Author:

Fluent Commerce

Changed on:

12 July 2024

Overview

A best practice guide of creating customer entity.

Key points

A user guide on how to manage customer entities in OMS.
Best practice guide on creating Customer entity in OMS before the createOrder mutation.
Relationship between user entity and customer entity.

Query Customer in OMS

The user can use the `customers` or `customer` queries to search/retrieve customer data in the OMS.The GraphQL schema can be found here:https://api.production.shared-sydney-01.fluentcommerce.com/graphql/docs/operation/query/Here is a sample GraphQL `customer` query:

1POST: {{fluentApiHost}}/graphql
2
3// QUERY
4query getCustomer($customerRef:String!){
5   customer(ref:$customerRef) {
6      id
7      ref
8      username
9      firstName
10      lastName
11      status
12      createdOn
13      updatedOn
14   }
15}
16
17
18
19// GraphQL Variables:
20{
21    "customerRef":"1_Marietta_Will5@gmail.com"
22}
23
24

1POST: {{fluentApiHost}}/graphql
2
3// QUERY
4{
5    customers(ref:"%arietta_Will5@gmail.com%"){
6        edges{
7            node{
8                createdOn
9                updatedOn
10                status
11                ref
12                department
13                username
14                firstName
15                lastName
16                timezone
17                primaryEmail
18                promotionOptIn
19                primaryPhone
20                status
21                retailer{
22                    id
23                }
24            }
25        }
26    }
27}
28

Create Customer in OMS

The user can use the `createCustomer` mutation to create a customer entity in the OMS.The GraphQL schema can be found here:https://api.production.shared-sydney-01.fluentcommerce.com/graphql/docs/mutation/createcustomer/Here is a sample GraphQL `createCustomer` mutation:

1POST: {{fluentApiHost}}/graphql
2
3// QUERY
4mutation createCustomer($retailerId:ID!, $username:String!){
5  createCustomer(input:{
6    username:$username
7    title:"Ms"
8    firstName:"{{$randomFirstName}}"
9    lastName:"{{$randomLastName}}"
10    primaryEmail:"{{$randomEmail}}"
11    primaryPhone:"+1234567890"
12    promotionOptIn: false
13    timezone:"GMT+10"
14    retailer:{
15      id: $retailerId
16    }
17  }) {
18    id
19    ref
20    username
21    primaryEmail
22    
23  }
24}
25
26
27// GraphQL Variables:
28{
29	"retailerId": "{{retailer_id}}",
30	"username": "{{retailer_id}}_{{$randomEmail}}"
31}
32
33

Update Customer in OMS

The user can use the `updateCustomer` mutation to update a customer entity in the OMS.The GraphQL schema can be found here:https://api.production.shared-sydney-01.fluentcommerce.com/graphql/docs/mutation/updatecustomer/Here is a sample GraphQL `updateCustomer` mutation:

1POST: {{fluentApiHost}}/graphql
2
3// QUERY
4mutation updateCustomer ($input: UpdateCustomerInput) {
5    updateCustomer (input: $input) {
6        id
7        ref
8        status
9        createdOn
10        updatedOn
11        retailer{
12            id
13        }
14        title
15        country
16        firstName
17        lastName
18        username
19        primaryEmail
20        primaryPhone
21        timezone
22        promotionOptIn
23    }
24}
25
26
27// GraphQL Variables:
28{
29  "input": {
30    "username": "1_Clarissa.Stokes@yahoo.com",
31    "primaryPhone": "3333344444",
32    "primaryEmail": "new2@emailnew.com"
33  }
34}
35
36

Best practice for creating Customers in OMS

Validate customer details before Order Creation

Since the `createOrder` mutation requires a customer ID, the below flowchart demonstrates the best practice for creating a customer: No alt provided

Ensure the customer username is unique across the account, not just the retailer.

The customer entity is located at the retailer level (same as the Order entity) in the OMS data structure. It is a best practice to ensure the customer->username is unique across the Account level, not just the retailer level. This will reduce any confusion when it comes to cross-retailer setup.

use retailer ID as part of the customer username

A recommendation is to use the retailer ID prefix/suffix as part of the username value. For example:`{``"retailerId": "{{retailer_id}}",``"username": "{{retailer_id}}_{{$Email}}"``}`

Relationship between user entity and customer entity

In the current data technical structure, the username field must be unique across user and customer entities. Hence, the best practice is to ensure that the user->username and customer->username are unique in both entities.

Query Create and Update Customer via GraphQL

Overview

Key points

Query Customer in OMS

Create Customer in OMS

Update Customer in OMS

Best practice for creating Customers in OMS

Validate customer details before Order Creation

Ensure the customer username is unique across the account, not just the retailer.

Related content

Users, Roles, and Permissions

Fluent Commerce

Building Blocks

By Type

Helpful Resources

Quick Links