My Customer Profile

The My Customer Profile endpoint creates and provides access to a customer profile scoped to a specific user. The endpoint requires an access token from the password flow or anonymous session flow. This endpoint is also used to sign up (create) a customer from an anonymous session, or sign in (merge) an anonymous session to an existing account.

The My Customer Profile endpoint intentionally provides access to a limited subset of the fields on a Customer. This provides extra security in scenarios when the client application must communicate directly with the commercetools API on behalf of a customer, such as commerce in a mobile application. If you need to modify a field available on the full Customer resource, do it from a trusted, server-side application. Use an API Extension to make the modification during the API call.

Representations

All representations are JSON objects submitted or received as payload to API requests or responses. Responses are equal to the responses on the customers endpoint, but requests may differ. The customer group, the customer number and external ID can not be set via this endpoint.

MyCustomerDraft

  • email - String
  • password - String
  • firstName - String - Optional
  • lastName - String - Optional
  • middleName - String - Optional
  • title - String - Optional
  • salutation - String - Optional
  • dateOfBirth - Date - Optional
  • companyName - String - Optional
  • vatId - String - Optional
  • addresses - Array of Address - Optional
    Sets the ID of each address to be unique in the addresses list.
  • defaultBillingAddress - Number - Optional
    The index of the address in the addresses array. The defaultBillingAddressId of the customer will be set to the ID of that address.
  • defaultShippingAddress - Number - Optional
    The index of the address in the addresses array. The defaultShippingAddressId of the customer will be set to the ID of that address.
  • custom - CustomFieldsDraft - Optional
    The custom fields.
  • locale - String conforming to ↗ IETF language tag - Optional

Get Customer

Endpoint: /{projectKey}/me
Method: GET
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer

Get Customer in a Store beta

Endpoint: /{projectKey}/in-store/key={storeKey}/me
Method: GET
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer

Create Customer (Sign Up)

Creates a customer.

If used with an access token for Anonymous Sessions, all orders and carts belonging to the anonymousId will be assigned to the newly created customer.

Endpoint: /{projectKey}/me/signup
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Request Representation: MyCustomerDraft
Response Representation: CustomerSignInResult

Signing up a customer produces the CustomerCreated message.

Create Customer (Sign Up) in a Store beta

Creates a customer in a specific Store. The {storeKey} path parameter maps to a Store’s key.

If omitted in the request representation, the customer’s stores field is set to the store specified in the path parameter.

If used with an access token for Anonymous Sessions, all orders and carts belonging to the anonymousId will be assigned to the newly created customer.

Endpoint: /{projectKey}/in-store/key={storeKey}/me/signup
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Request Representation: MyCustomerDraft
Response Representation: CustomerSignInResult

Signing up a customer produces the CustomerCreated message.

Authenticate Customer (Sign In)

Retrieves the authenticated customer (a customer that matches the given email/password pair).

If used with an access token for Anonymous Sessions, all orders and carts belonging to the anonymousId will be assigned to the newly created customer.

  • If the customer does not have a cart yet, the anonymous cart that was modified most recently becomes the customer’s cart.
  • If the customer already has a cart, the most recently modified anonymous cart will be handled according to the AnonymousCartSignInMode.

If a cart is is returned as part of the CustomerSignInResult, it has been recalculated (It will have up-to-date prices, taxes and discounts, and invalid line items have been removed.).

Endpoint: /{projectKey}/me/login
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: CustomerSignInResult
Fields:

  • email - String - Required
    Treated as case-insensitive.
  • password - String - Required
  • activeCartSignInMode - AnonymousCartSignInMode - Optional - Defaults to MergeWithExistingCustomerCart
  • updateProductData - Boolean - Optional, defaults to false
    If set to true, the line item product data (name, variant and productType) of the returned cart will be updated. If set to false, only the prices, discounts and tax rates will be updated.

Specific Error Codes:

Authenticate Customer (Sign In) in a Store beta

Retrieves the authenticated customer (a customer that matches the given email/password pair) if they are part of the specific Store.

If used with an access token for Anonymous Sessions, all orders and carts belonging to the anonymousId will be assigned to the newly created customer.

  • If the customer does not have a cart yet, the anonymous cart that was modified most recently becomes the customer’s cart.
  • If the customer already has a cart, the most recently modified anonymous cart will be handled according to the AnonymousCartSignInMode.

If a cart is is returned as part of the CustomerSignInResult, it has been recalculated (It will have up-to-date prices, taxes and discounts, and invalid line items have been removed.).

Endpoint: /{projectKey}/in-store/key={storeKey}/me/login
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: CustomerSignInResult
Fields:

  • email - String - Required
    Treated as case-insensitive.
  • password - String - Required
  • activeCartSignInMode - AnonymousCartSignInMode - Optional - Defaults to MergeWithExistingCustomerCart
  • updateProductData - Boolean - Optional, defaults to false
    If set to true, the line item product data (name, variant and productType) of the returned cart will be updated. If set to false, only the prices, discounts and tax rates will be updated.

Specific Error Codes:

Update Customer

Endpoint: /{projectKey}/me
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer
Fields:

  • version - Number - Required
    The expected version of the customer on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the customer.

Update Customer in a Store beta

Endpoint: /{projectKey}/in-store/key={storeKey}/me
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

  • version - Number - Required
    The expected version of the customer on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
  • actions - Array of UpdateAction - Required
    The list of update actions to be performed on the customer.

Update Actions

Change Email

  • action - String - "changeEmail"
  • email - String - Required

Set First Name

  • action - String - "setFirstName"
  • firstName - String - Optional

Set Last Name

  • action - String - "setLastName"
  • lastName - String - Optional

Set Middle Name

  • action - String - "setMiddleName"
  • middleName - String - Optional

Set Title

  • action - String - "setTitle"
  • title - String - Optional

Set Salutation

  • action - String - "setSalutation"
  • salutation - String - Optional

Add Address

Adds an address to the customer’s addresses array. Sets the address ID to be unique in the addresses list.

  • action - String - "addAddress"
  • address - Address - Required

Change Address

Replaces the address with the given ID, with the new address in the customer’s addresses array. The new address will have the same ID.

  • action - String - "changeAddress"
  • addressId - String - Required
  • address - Address - Required

Remove Address

Removes the address with the given ID from the customer’s addresses array.

  • action - String - "removeAddress"
  • addressId - String - Required

Set Default Shipping Address

Sets the default shipping address from the Customer’s addresses.
If the address is not in the Customer’s shipping addresses it will be added to the Customer’s shippingAddressIds.

  • action - String - "setDefaultShippingAddress"
  • addressId - String - Optional
    If not defined, the customer’s defaultShippingAddress is unset.

Add Shipping Address ID

Adds an existing address from the Customer’s addresses - referred to by its id - to the Customer’s shippingAddressIds.

  • action - String - "addShippingAddressId"
  • addressId - String

Remove Shipping Address ID

Removes an existing shipping address from the Customer’s shippingAddressesIds.
If the shipping address is the Customer’s default shipping address the Customer’s defaultShippingAddressId will be unset.

  • action - String - "removeShippingAddressId"
  • addressId - String

Set Default Billing Address

Sets the default billing address from the Customer’s addresses.
If the address is not in the Customer’s billing addresses it will be added to the Customer’s billingAddressIds.

  • action - String - "setDefaultBillingAddress"
  • addressId - String - Optional
    If not defined, the customer’s defaultBillingAddress is unset.

Add Billing Address ID

Adds an existing address from the Customer’s addresses - referred to by its id - to the Customer’s billingAddressIds.

  • action - String - "addBillingAddressId"
  • addressId - String

Remove Billing Address ID

Removes an existing billing address from the Customer’s billingAddressesIds.
If the billing address is the Customer’s default billing address the Customer’s defaultBillingAddressId will be unset.

  • action - String - "removeBillingAddressId"
  • addressId - String

Set Company Name

  • action - String - "setCompanyName"
  • companyName - String - Optional
    If not defined, the company name is unset.

Set Date of Birth

  • action - String - "setDateOfBirth"
  • dateOfBirth - Date - Optional
    If not defined, the date of birth is unset.

Set Vat Id

  • action - String - "setVatId"
  • vatId - String - Optional
    If not defined, the vat ID is unset.

Set Custom Type

This action sets or removes the custom type for an existing customer.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to a Type - Optional
    If absent, the custom type and any existing custom fields are removed.
  • fields - * - Optional
    A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

This action overwrites any existing custom type and fields.

Set CustomField

Set Locale

Sets the locale. Must be one of the languages supported for this Project.

Change Customer’s Password

Endpoint: /{projectKey}/me/password
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer
Fields:

  • version - Number - Required
  • currentPassword - String - Required
  • newPassword - String - Required

Specific Error Codes:

Change Customer’s Password in a Store beta

Endpoint: /{projectKey}/in-store/key={storeKey}/me/password
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

  • version - Number - Required
  • currentPassword - String - Required
  • newPassword - String - Required

Specific Error Codes:

Reset Customer’s Password

Set a new password using a token. The last step of the customer password reset flow.

Endpoint: /{projectKey}/me/password/reset
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer
Fields:

  • tokenValue - String - Required
  • newPassword - String - Required

Reset Customer’s Password in a Store beta

Set a new password using a token. The last step of the customer password reset flow.

Endpoint: /{projectKey}/in-store/key={storeKey}/me/password/reset
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

  • tokenValue - String - Required
  • newPassword - String - Required

Verify Customer’s Email

Verifies customer’s email using a token. The last step of the customer email verification.

Endpoint: /{projectKey}/me/email/confirm
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}
Fields:

  • tokenValue - String - Required

Verify Customer’s Email in a Store beta

Verifies customer’s email using a token. The last step of the customer email verification.

Endpoint: /{projectKey}/in-store/key={storeKey}/me/email/confirm
Method: POST
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Fields:

  • tokenValue - String - Required

Delete Customer

Endpoint: /{projectKey}/me
Method: DELETE
OAuth2 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer
Query parameters:

  • version - Number - Required

Delete Customer in a Store beta

Endpoint: /{projectKey}/in-store/key={storeKey}/me
Method: DELETE
OAuth2 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Query parameters:

  • version - Number - Required