SDK code examples

Try our example SDK code.

Example SDK code on this page assumes you have set up your SDK as described in the get started guide of your respective SDK. You may need to modify some code if your environment differs.

Overview

The following SDK code examples demonstrate how to carry out basic commerce tasks such as creating, updating, and querying Customers and Products with commercetools SDKs. You can adapt and build upon these code examples to help integrate Composable Commerce into your code base.

Manage Customers

Create a Customer

To create a Customer, post a CustomerDraft to the Customers endpoint.

CustomerDrafts have two required fields: email and password.

After posting the CustomerDraft, the API returns a CustomerSignInResult. This contains the new Customer and an optional Cart (which is null in these examples). These code examples get the Customer then output its id.

Create a Customer

// Create a CustomerDraft with the required fields (email address and password)
CustomerDraft newCustomerDetails = CustomerDraft
  .builder()
  .email("sdk@example.com")
  .password("password")
  .build();

// Post the CustomerDraft and get the new Customer
Customer customer = apiRoot
  .customers()
  .post(newCustomerDetails)
  .executeBlocking()
  .getBody()
  .getCustomer();

// Output the Customer ID
String customerID = customer.getId();
System.out.println(customerID);

{customerID} is used as a placeholder in following examples.

Query a Customer

You can query the Customer by including its id after the Customers endpoint. This example code outputs the Customer's email, but you can access every field within the Customer.

Query a Customer

// Query a Customer by their ID
Customer queryCustomer = apiRoot
  .customers()
  .withId("{customerID}")
  .get()
  .executeBlocking()
  .getBody();

// Output the Customer's email address
String customerEmail = queryCustomer.getEmail();
System.out.println(customerEmail);

If you query a resource with an id or key that does not exist, the API returns a 404 Not Found error. This may cause your program to crash.

Add a Customer name

To update a Customer, post a CustomerUpdate, which contains the current version of the Customer and an array/collection of update actions, to the specified Customer.

The required update actions for changing a Customer's first and second names are Set First Name and Set Last Name.

Update a Customer

// Create the CustomerUpdate with the current version of the Customer and add the actions
CustomerUpdate customerUpdate = CustomerUpdate
  .builder()
  // The version of a new Customer is 1. This value is incremented every time an update action is applied to the Customer. If the specified version does not match the current version, the request returns an error.
  .version(1l)
  .plusActions(actionBuilder ->
    actionBuilder.setFirstNameBuilder().firstName("John")
  )
  .plusActions(actionBuilder ->
    actionBuilder.setLastNameBuilder().lastName("Smith")
  )
  .build();

// Post the CustomerUpdate and return the updated Customer
Customer updatedCustomer = apiRoot
  .customers()
  .withId("{customerID}")
  .post(customerUpdate)
  .executeBlocking()
  .getBody();

// Output the updated Customer's full name
String updatedCustomerName =
  updatedCustomer.getFirstName() + " " + updatedCustomer.getLastName();
System.out.println(updatedCustomerName);

Find a Customer by their email address

As the email of a Customer is unique, it is a dependable way to find a Customer.

You can find Customers by their email address by querying the Customers endpoint with a where parameter and a Query Predicate.

This example code returns a CustomerPagedQueryResponse that contains a results array. If a Customer exists with the email, results will contain one entry and this Customer's id is output to the console.

Find a Customer by email address

// Search for Customers whose email address matches the predicate variable
CustomerPagedQueryResponse customerToFind = apiRoot
  .customers()
  .get()
  .withWhere("email = :customerEmail", "customerEmail", "sdk@example.com")
  .executeBlocking()
  .getBody();

// As email addresses must be unique, either 0 or 1 Customers will be returned.
// If 0, then no Customer exists with this email address.
if (customerToFind.getCount() == 0) {
  System.out.println("This email address has not been registered.");
} else {
  // Since there can be only one Customer resource in the result, it must be the first entry of the results array. This outputs the Customer's id.
  String customerID = customerToFind.getResults().get(0).getId();
  System.out.println(customerID);
}

Manage Products

Creating Products requires more steps than creating Customers. This is due to how Products are modeled in Composable Commerce.

You must first create a ProductType before you create a Product.

Create a ProductType

To create a ProductType, post a ProductTypeDraft to the ProductTypes endpoint.

ProductTypeDrafts have two required fields: name and description.

After posting the ProductTypeDraft, the API returns the new ProductType. These code examples output the new ProductType's id.

Create a ProductType

// Create a ProductTypeDraft with the required fields (name and description)
ProductTypeDraft newProductTypeDetails = ProductTypeDraft
  .builder()
  .name("The name of your ProductType")
  .description("The description of your ProductType")
  .build();

// Post the ProductTypeDraft and get the new ProductType
ProductType productType = apiRoot
  .productTypes()
  .post(newProductTypeDetails)
  .executeBlocking()
  .getBody();

// Output the ProductType ID
String productTypeID = productType.getId();
System.out.println(productTypeID);

{productTypeID} is used as a placeholder in following examples.

Create a Product

To create a Product, post a ProductDraft to the Products endpoint.

ProductDrafts have three required fields: name, productType, and slug.

After posting the ProductDraft, the API returns the new Product. These code examples output the new Product's id.

Create a Product

// Create a ProductDraft with the required fields (name, productType, and slug)
ProductDraft newProductDetails = ProductDraft
  .builder()
  .name(stringBuilder ->
    stringBuilder
      .addValue("en", "English name for your Product")
      .addValue("de", "German name for your Product")
  )
  .productType(typeBuilder -> typeBuilder.id({productTypeID}))
  .slug(stringBuilder ->
    stringBuilder
      .addValue("en", "human-readable-url-for-english-product")
      .addValue("de", "human-readable-url-for-german-product")
  )
  .build();

// Post the ProductDraft and get the new Product
Product product = apiRoot
  .products()
  .post(newProductDetails)
  .executeBlocking()
  .getBody();

// Output the Product ID
String productID = product.getId();
System.out.println(productID);

{productID} is used as a placeholder in following examples.

Query your Product

You can query the Product by including its id after the Product endpoint. This example code outputs the Product's version, but you can access every field within the Product.

Query a Product

// Query a Product by its ID
Product queryProduct = apiRoot
  .products()
  .withId("{productID}")
  .get()
  .executeBlocking()
  .getBody();

// Output the Product's version
System.out.println(queryProduct.getVersion());

Add a Product key

Keys are user-defined unique identifiers that make it easier to manage various resources in your Project. By assigning keys to Products, you can query and update Products using a human-friendly identifier instead of a randomly generated ID. You can also potentially use keys to sync your Products with their identifiers in external databases.

To update a Product, post a ProductUpdate, which contains the current version of the Product and an array/collection of update actions, to the specified Product.

Adding a key to a Product requires the Set Key update action.

Update a Product with a new key

// Create the ProductUpdate with the current version of the Product and the update actions
ProductUpdate productUpdate = ProductUpdate
  .builder()
  // The version of a new Product is 1. This value is incremented every time an update action is applied to the Product. If the specified version does not match the current version, the request returns an error.
  .version(1l)
  .plusActions(actionBuilder ->
    actionBuilder.setKeyBuilder().key("new-product-key")
  )
  .build();

// Post the ProductUpdate and return the updated Product
Product updatedProduct = apiRoot
  .products()
  .withId("{productID}")
  .post(productUpdate)
  .executeBlocking()
  .getBody();

// Output the updated Product's key
String updatedProductKey = updatedProduct.getKey();
System.out.println(updatedProductKey);

Return a Product by its Key

You can now query the Product by including its key after the Products endpoint. This example code outputs the Product's current English name.

Query a Product by its key

Product findProductByKey = apiRoot
  .products()
  .withKey("{productKey}")
  .get()
  .executeBlocking()
  .getBody();

// Output the Product's current English name
String productName = findProductByKey
  .getMasterData()
  .getCurrent()
  .getName()
  .get("en");
System.out.println(productName);