Documentation
BETA

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 AddressDraft - Optional
    id in the AddressDraft, if given, will be overwritten and set unique within the Customer.
  • 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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer

Get Customer in a Store BETA

Endpoint: /{projectKey}/in-store/key={storeKey}/me
Method: GET
OAuth 2.0 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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}
Request Representation: MyCustomerDraft
Response Representation: CustomerSignInResult

Signing up a customer produces the CustomerCreatedMessage.

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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Request Representation: MyCustomerDraft
Response Representation: CustomerSignInResult

Signing up a customer produces the CustomerCreatedMessage.

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 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
OAuth 2.0 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 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
OAuth 2.0 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
OAuth 2.0 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
OAuth 2.0 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.

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

Address Selection

The address to be updated can be specified either by its ID or by its key.
Choose one of the options below:

Selection by ID

  • addressId - String - Required
    ID of an existing Address.

Selection by key

  • addressKey - String - Required
    Key of an existing Address.

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.

Remove Address

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

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"
  • Address selection - Optional
    If not defined, the customer's defaultShippingAddress is unset.

Add Shipping Address identifier

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

Remove Shipping Address identifier

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.

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"
  • Address selection - Optional
    If not defined, the customer's defaultBillingAddress is unset.

Add Billing Address identifier

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

Remove Billing Address identifier

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.

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. If present, this action overwrites any existing custom type and fields.

  • action - String - "setCustomType"
  • type - ResourceIdentifier of 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.

Set CustomField

  • action - String - "setCustomField"
  • name - String - Required
  • value - Value - Optional
    If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Set Locale

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

  • action - String - "setLocale"
  • locale - String conforming to IETF language tag - Optional

Change Customer's Password

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

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

Changing the password produces the CustomerPasswordUpdatedMessage with reset=false.

Specific Error Codes:

Change Customer's Password in a Store BETA

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

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

Changing the password produces the CustomerPasswordUpdatedMessage with reset=false.

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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}
Response Representation: Customer
Fields:

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

Resetting the password produces the CustomerPasswordUpdatedMessage with reset=true.

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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

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

Resetting the password produces the CustomerPasswordUpdatedMessage with reset=true.

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
OAuth 2.0 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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Fields:

  • tokenValue - String - Required

Delete Customer

Endpoint: /{projectKey}/me
Method: DELETE
OAuth 2.0 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
OAuth 2.0 Scopes: manage_my_profile:{projectKey}, manage_my_profile:{projectKey}:{storeKey}
Response Representation: Customer
Query parameters:

  • version - Number - Required