Customers

Create, edit, and manage customers

Overview

Each customer has a user account with the customer label, and a document in the customers collection with the ID of the user. The document does not contain personal information as they are already available in the user account.

Customers can be created, edited, verified and suspended.

Customer document model

See here: Customer Details

Create a new customer

To create a new customer, we have to call the create-customer cloud function. This function creates a customer in the following steps:

creates the user account
assign the customer label to the user
creates a new document in the customers collection
verify the user's email if shouldVerify is set to true

It receives the new user's email, name, and label.

{
  "email": "test123@test.com",
  "name": "Test User",
  "phone": "1234567890", // optional
  "shouldVerify": true // optional
}

It returns a JSON string with a status and an optional error message. E.g.:

{
  "status": "success", // or "error"
  "error": "Some error message" // only if status is "error"
}

Below is a complete example of how to create a new customer:

  try {
    const res = await functions.createExecution('CREATE_CUSTOMER_FUNCTION_ID', JSON.stringify({
      "email": "test123d@test.com",
      "name": "Test User",
    }));

    // confirm response status code
    if (res.responseStatusCode != 200) {
      console.error(`Error executing function: ${res.errors}`);
      // display error message to the user
    }

    // check the status of the function execution

    if (res.status == 'processing') {
      console.log('Function is still processing');
      // handle processing state
      return;
    }

    if (res.status == 'failed') {
      console.error(`Function execution failed: ${res.errors}`);
      // display error message to the user
      return;
    }

    // check the output of the function execution
    const body = res.responseBody;
    const data = JSON.parse(body);

    // check if data contains an error key
    if (data.status == 'error') {
      console.log(data.error);
      console.error(`Function execution failed: ${data.error}`);
      // display error message to the user
      return;
    }

    // handle successful function execution
    console.log('Function executed successfully:');

    return;

  } catch (error) {
    if (error instanceof AppwriteException) {
      console.error(`Error executing function: ${error.message} - ${error.code}`);
      // display error message to the user
    } else {
      console.error('Unknown error:', error);
      // display error message to the user
    }
  }

Fetch customers

To fetch all customers, we have to call the get-customers cloud function.

This function returns a list of all customers. It searches for all users with the customer label and returns the Appwrite user object as well as the customer document in a map.

It receives an optional cursor in the body of the request. The cursor is to be used for pagination. If no cursor is provided, the first page will be returned.

{"cursor": "LAST_USER_ID"}

It returns a JSON string with a error or success key that holds a message. E.g.:

{
  "status": "success", // or "error"
  "error": "Some error message", // only if status is "error"
  "data": {
    "total": 200, // total number of customers in the DB. This is only returned on the first page
    "customers": [
      {
        "user": {},
        "customer": {}
        
      }
    ]
  }
}

Below is a complete example of how to fetch all customers:

  try {
    const res = await functions.createExecution('GET_CUSTOMERS_FUNCTION_ID');
    // to fetch the next page, add `JSON.stringify({"cursor": LAST_USER_ID})` to the body

    // confirm response status code
    if (res.responseStatusCode != 200) {
      console.error(`Error executing function: ${res.errors}`);
      // display error message to the user
    }

    // check the status of the function execution

    if (res.status == 'processing') {
      console.log('Function is still processing');
      // handle processing state
      return;
    }

    if (res.status == 'failed') {
      console.error(`Function execution failed: ${res.errors}`);
      // display error message to the user
      return;
    }

    // check the output of the function execution
    const body = res.responseBody;
    const data = JSON.parse(body);

    // check if data contains an error key
    if (data.status == 'error') {
      console.log(data.error);
      console.error(`Function execution failed: ${data.error}`);
      // display error message to the user
      return;
    }

    // handle successful function execution
    console.log('Function executed successfully');

    console.log(data.data);

    return;

  } catch (error) {
    if (error instanceof AppwriteException) {
      console.error(`Error executing function: ${error.message} - ${error.code}`);
      // display error message to the user
    } else {
      console.error('Unknown error:', error);
      // display error message to the user
    }
  }

Verify customer

Use this function to verify or unverify a customer's email address or phone number

note

This function is different from account suspension because it doesn't suspend the user's account, but it toggles the verification status of the customer's email or phone number.

It receives the following parameters in the body of the request:

{
  "userId": "user-id",
  "service": "email", // or "phone"
  "status": true // or false
}

note

All parameters are required.

It returns a JSON string with a status and an optional error message. E.g.:

{
  "status": "success", // or "error"
  "error": "Some error message" // only if status is "error"
}

Below is a complete example of how to toggle email or phone verification for a customer:

  try {
    const res = await functions.createExecution('67e072b30020cf0eaa85', JSON.stringify(
      {
        'userId': '67e095321f7cbe6409c7',
        'service': 'email',
        'status': true,
      }
    )
    );

    // confirm response status code
    if (res.responseStatusCode != 200) {
      console.error(`Error executing function: ${res.errors}`);
      // display error message to the user
    }

    // check the status of the function execution

    if (res.status == 'processing') {
      console.log('Function is still processing');
      // handle processing state
      return;
    }

    if (res.status == 'failed') {
      console.error(`Function execution failed: ${res.errors}`);
      // display error message to the user
      return;
    }

    // check the output of the function execution
    const body = res.responseBody;
    const data = JSON.parse(body);

    // check if data contains an error key
    if (data.status == 'error') {
      console.log(data.error);
      console.error(`Function execution failed: ${data.error}`);
      // display error message to the user
      return;
    }

    // handle successful function execution
    console.log('Function executed successfully');

    return;

  } catch (error) {
    if (error instanceof AppwriteException) {
      console.error(`Error executing function: ${error.message} - ${error.code}`);
      // display error message to the user
    } else {
      console.error('Unknown error:', error);
      // display error message to the user
    }
  }

Suspend customer

Instead of deleting a customer user, you can suspend them. This is done by calling the toggle-account-suspension cloud function. The function takes in the userId parameter.

It returns a JSON string with a error or success key that holds a message. E.g.:

{
  "error": "Some error message"
}

{
  "success": "User suspended" // or "User unsuspended"
}

Below is an example of how to call the function with the Appwrite SDK:

  try {
    const res = await functions.createExecution('TOGGLE_ACCOUNT_SUSPENSION_FUNCTION_ID', JSON.stringify({
      "userId": "USER_ID"
    }));

    // confirm response status code
    if (res.responseStatusCode != 200) {
      console.error(`Error executing function: ${res.errors}`);
      // display error message to the user

    }

    // check the status of the function execution

    if (res.status == 'processing') {
      console.log('Function is still processing');
      // handle processing state
      return;
    }

    if (res.status == 'failed') {
      console.error(`Function execution failed: ${res.errors}`);
      // display error message to the user
      return;
    }

    // check the output of the function execution
    const body = res.responseBody;
    const data = JSON.parse(body);

    // check if data contains an error key
    if (data.error) {
      console.log(data.error);
      console.error(`Function execution failed: ${data.error}`);
      // display error message to the user
      return;
    }

    // handle successful function execution
    console.log('Function executed successfully:', data.success);

    return;

  } catch (error) {
    if (error instanceof AppwriteException) {
      console.error(`Error executing function: ${error.message} - ${error.code}`);
      // display error message to the user
    } else {
      console.error('Unknown error:', error);
      // display error message to the user
    }
  }

Overview​

Customer document model​

Create a new customer​

Fetch customers​

Verify customer​

Suspend customer​