Commerce Customer API Reference

Overview

The Customer API manages contacts, organizations, and addresses. CustomerContext provides the current customer. IOrganizationService and ICustomerContactService handle B2B hierarchies.

Namespace

Optimizely.Commerce.Customers

Key classes and interfaces

Type	Purpose
CustomerContext	Resolves the current customer contact
CustomerContact	Represents an individual customer
Organization	Represents a B2B organization
CustomerAddress	Shipping or billing address

CustomerContext

CurrentContact

Returns the CustomerContact for the current authenticated user.

Returns: CustomerContact or null if anonymous

GetContactById(Guid)

Loads a customer contact by GUID.

Parameters

Name	Type	Description
contactId	Guid	Customer contact GUID

Returns: CustomerContact or null

Get current customer

C# (.NET)

csharp Copy

public class CustomerService
{
  private readonly CustomerContext _customerContext;

  public CustomerService(CustomerContext customerContext)
  {
      _customerContext = customerContext;
  }

  public CustomerContact GetCurrentCustomer()
  {
      return _customerContext.CurrentContact;
  }

  public CustomerContact GetCustomerById(Guid id)
  {
      return _customerContext.GetContactById(id);
  }
}

CustomerContact

Properties

Property	Type	Description
PrimaryKeyId	PrimaryKeyId	Internal primary key
UserId	string	Mapped user identity
FirstName	string	First name
LastName	string	Last name
Email	string	Email address
FullName	string	Computed full name
OwnerId	PrimaryKeyId?	Parent organization ID
ContactAddresses	IEnumerable<CustomerAddress>	Associated addresses
PreferredBillingAddress	CustomerAddress	Default billing address
PreferredShippingAddress	CustomerAddress	Default shipping address

Methods

Method	Returns	Description
SaveChanges()	void	Persists modifications to the database
AddContactAddress(CustomerAddress)	void	Adds a new address
UpdateContactAddress(CustomerAddress)	void	Updates an existing address
DeleteContactAddress(CustomerAddress)	void	Removes an address

Create a new customer contact

C# (.NET)

csharp Copy

public CustomerContact CreateCustomer(string email, string firstName, string lastName)
{
  var contact = CustomerContact.CreateInstance();
  contact.UserId = "String:" + email;
  contact.Email = email;
  contact.FirstName = firstName;
  contact.LastName = lastName;
  contact.SaveChanges();
  return contact;
}

Organization (B2B)

Properties

Property	Type	Description
PrimaryKeyId	PrimaryKeyId	Internal primary key
Name	string	Organization name
OrgCustomerGroup	string	Customer pricing group
Addresses	IEnumerable<CustomerAddress>	Organization addresses
ChildOrganizations	IEnumerable<Organization>	Sub-organizations
Contacts	IEnumerable<CustomerContact>	Member contacts

Methods

Method	Returns	Description
SaveChanges()	void	Persists modifications
AddContact(CustomerContact)	void	Adds a contact to the organization
RemoveContact(CustomerContact)	void	Removes a contact

Create an organization with a contact

C# (.NET)

csharp Copy

public Organization CreateOrganization(string name)
{
  var org = Organization.CreateInstance();
  org.Name = name;
  org.OrgCustomerGroup = "B2B";
  org.SaveChanges();
  return org;
}

public void AssignContactToOrg(CustomerContact contact, Organization org)
{
  contact.OwnerId = org.PrimaryKeyId;
  contact.SaveChanges();
  org.AddContact(contact);
  org.SaveChanges();
}

CustomerAddress

Property	Type	Description
AddressId	PrimaryKeyId	Unique address identifier
Name	string	Address label (e.g., “Home”, “Office”)
FirstName	string	Recipient first name
LastName	string	Recipient last name
Line1	string	Street address line 1
Line2	string	Street address line 2
City	string	City
State	string	State or province
PostalCode	string	ZIP or postal code
CountryCode	string	Two-letter ISO country code
CountryName	string	Country display name
DaytimePhoneNumber	string	Phone number
AddressType	CustomerAddressTypeEnum	Shipping, Billing, or Public

Add address to contact

C# (.NET)

csharp Copy

public void AddShippingAddress(CustomerContact contact)
{
  var address = CustomerAddress.CreateInstance();
  address.Name = "Office";
  address.AddressType = CustomerAddressTypeEnum.Shipping;
  address.Line1 = "123 Commerce St";
  address.City = "New York";
  address.State = "NY";
  address.PostalCode = "10001";
  address.CountryCode = "US";
  address.CountryName = "United States";

  contact.AddContactAddress(address);
  contact.SaveChanges();
}

B2B hierarchy

Organization (Parent)
├── Organization (Division A)
│   ├── CustomerContact (Buyer 1)
│   └── CustomerContact (Buyer 2)
└── Organization (Division B)
    └── CustomerContact (Buyer 3)

Common exceptions

Exception	Cause
EntityNotFoundException	Contact or organization GUID not found
DuplicateKeyException	UserId already exists
ValidationException	Required fields missing

Related content

Continue your journey with these related pages.

📖Understand the concepts

• Optimizely Commerce

🔧Follow a guide

• Commerce Guides