Me endpoints overview

Ask about this Page
Copy for AI
View as Markdown

How to work with the me endpoints.

Me endpoints are designed to access the resources of a single Customer and are named due to the common /me URL path they all share.
Each me endpoint contains a subset of functionality compared to its corresponding general endpoint. For example, My Carts is derived from the full-featured Carts API general endpoint.
When we refer to one of these endpoints individually, we call them My + resource endpoint, for example:
Access to the Customer's resources is restricted through dedicated scopes, like manage_my_orders. Assuming every Customer should have full control over their own resources, we only provide manage scopes for the me endpoints, but no view scopes.

When to use

We recommend that you only use the me endpoints in the absence of a middleware layer.

For those using commercetools Frontend, we recommend that you use the general endpoints from API Hub which provides better capability for customizing and controlling the experience for your customers.

For those using a custom frontend, we recommend that you integrate the general endpoints via a middleware layer. This method maximizes the full potential of our APIs, allowing for a more robust and flexible implementation.

Working with the me endpoints

My Customer Profile

The My Customer Profile API creates and provides access to a Customer profile scoped to a specific Customer.
The API requires an access token from the password flow or anonymous session flow.
The My Customer Profile API can also be used to create (sign up) a Customer from an anonymous session, or merge (sign in) an anonymous session to an existing account.
When used with an access token obtained by an anonymous session flow, all Orders and Carts belonging to the anonymousId are assigned to the Customer.
The API intentionally provides access to a limited subset of fields on Customer to provide extra security in scenarios when the client application must communicate directly with the API on behalf of a customer, such as commerce in a mobile application. If you need to modify a field available on the Customer resource, do it from a trusted, server-side application.
Customer Group, customer number, external ID, and ExternalAuth authentication mode cannot be set with this API.

My Business Units

The API requires an access token from the password flow.
A Business Unit created using the My Business Units API is Inactive by default. Additionally, there is a restriction on updating Business Unit status using the My Business Units API. This ensures that a merchant can inspect a Business Unit created by a Customer, assign the appropriate Products and Prices, and activate it only when it is ready to be used. You can change this default configuration through a Project-level setting.
The My Business Units API allows Customers with the AddChildUnits Permission to create new Business Units and edit their existing ones. New Customers can also sign-up and create and manage new Business Units.
The My Business Units API does not support managing the Stores of a Business Unit, changing the Business Unit status, or assigning new Associates. This intentional restriction provides additional security in scenarios when the client application must communicate directly with the API, for example in the case of mobile applications. If you need to update a field available only on the full Business Unit resource, do so from a trusted, server-side application.
To update a Business Unit using the My Business Units API, the authenticated user must be an Associate in the Business Unit with sufficient Permissions to perform the update action. If a required Permission is missing, an AssociateMissingPermission error is returned.

My Carts

The API requires an access token from the password flow or anonymous session flow.
The My Carts API intentionally provides write access only to a limited subset of the fields on a Cart. This provides extra security in scenarios when a mobile or browser application communicates directly with the API on behalf of a customer. For example, the mobile application can not set external line item prices. If you need to modify a protected field available on the full Cart resource, do it from a trusted, server-side application. Use an API Extension to make the modification during the API call.

Custom Line Items and custom Tax Rates cannot be set via this API.

When creating B2B Carts, the Customer must have the CreateMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
When updating B2B Carts, the Customer must have the UpdateMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
When deleting B2B Carts, the Customer must have the DeleteMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.

My Orders

The API requires an access token from the password flow or anonymous session flow.
The My Orders API intentionally provides no write access on an Order. This provides extra security in scenarios when a mobile or browser application communicates directly with API on behalf of a customer. For example, the mobile application cannot set the order number. If you need to modify a protected field available on the full Order resource, do it from a trusted, server-side application. Use an API Extension to make the modification during the API call.
Orders cannot be changed via this API once created, and paymentState and orderNumber cannot be set.

My Payments

The API requires an access token from the password flow or anonymous session flow. The endpoints intentionally provide access to a limited subset of the fields on a Payment. This provides extra security in scenarios when the client application must communicate directly with the API on behalf of a customer.
The My Payments API can help in synchronous or asynchronous communication with a payment service provider (PSP). For example, if a client application receives a token for a credit card from a payment service, it can create a MyPaymentDraft with the token, and optionally add a Transaction to authorize a certain amount. The Payment can then be passed to another service that uses the general Payment endpoint and can communicate with the PSP to charge the credit card. This service can be triggered by a Subscription, or be implemented as an API Extension.
After a Transaction is added to a Payment, it can no longer be updated or deleted using My Payments.

My Shopping Lists

The API requires an access token from the password flow or anonymous session flow.
The My Shopping Lists API intentionally provides access to a limited subset of the fields on a Shopping List. This provides extra security in scenarios where the client application must communicate directly with the API on behalf of a customer, such as commerce in a mobile application. If you need to modify a field available on the full Shopping List resource, pass the response from the My Shopping Lists API to an internal service in your client application which accesses the Shopping List resource.

My Quote Requests

The API requires an access token from the password flow.
When creating B2B Quote Requests, the Customer must have the CreateMyQuoteRequestsFromMyCarts Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.
When updating B2B Quote Requests, the Customer must have the UpdateMyQuoteRequests Permission. If the required Permission is missing, an AssociateMissingPermission error is returned.

My Quotes

The API requires an access token from the password flow.

Checkout flow limitations

A checkout flow that uses My Business Units, My Carts, and My Orders endpoints does not support the use of external prices or external taxes.