Get started with the .NET SDK

Learn how to set up and use the .NET SDK.

This step-by-step guide leads you through setting up and making API calls using the .NET SDK.

Requirements

To follow this guide you should have the following:

A commercetools Project
An API Client
.NET Standard 2.1 (or later)

For more information on setting up a commercetools Project or API Client, follow our Getting started with commercetools guides.

Objectives of the get started guide

By the end of this guide you will have:

Installed the .NET SDK
Set up your client
Learned how to make API calls with the .NET SDK

Placeholder values

Example code in this guide uses the following placeholder values. You should replace these placeholders with the following values.

If you do not have an API Client, follow our Get your API Client guide.

Placeholder	Replace with	From
`{projectKey}`	project_key	your API Client
`{clientID}`	client_id	your API Client
`{clientSecret}`	secret	your API Client
`{scope}`	scope	your API Client
`{region}`	your Region	Hosts

Install the .NET SDK

PackageReference

Add the following to your .csproj file.

<ItemGroup>
  <PackageReference Include="commercetools.Sdk.Api" Version="*" />
</ItemGroup>

You must install commercetools.Sdk.Api to use the HTTP API. To access the Import API, Audit Log API, or Checkout API, include the respective PackageReference within the same <ItemGroup> block:

For Import API

For Audit Log API

For Checkout API

  <PackageReference Include="commercetools.Sdk.ImportApi" Version="*" />

This installs the latest version of each package. To use a specific version, replace * with the version number.

.NET CLI

Alternatively, run the following command in your project directory:

dotnet add package commercetools.Sdk.Api

To install packages for other APIs, run one of the following commands:

dotnet add package commercetools.Sdk.ImportApi
dotnet add package commercetools.Sdk.HistoryApi
dotnet add package commercetools.Sdk.CheckoutApi

You can also search for and install packages from NuGet Gallery.

Set up the client

Add the following code to your Program based on the API being accessed.

For HTTP API

For Import API

For Audit Log API

For Checkout API

// Include the following imports:
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using commercetools.Sdk.Api;

var services = new ServiceCollection();
var httpApiConfiguration = new ConfigurationBuilder()
  .AddInMemoryCollection(new List<KeyValuePair<string, string>>()
  {
    new KeyValuePair<string, string>("HTTPAPIClient:ApiBaseAddress", "https://api.{region}.commercetools.com/"),
    new KeyValuePair<string, string>("HTTPAPIClient:AuthorizationBaseAddress", "https://auth.{region}.commercetools.com/"),
    new KeyValuePair<string, string>("HTTPAPIClient:ClientId", "{clientID}"),
    new KeyValuePair<string, string>("HTTPAPIClient:ClientSecret", "{clientSecret}"),
    new KeyValuePair<string, string>("HTTPAPIClient:ProjectKey", "{projectKey}")
  })
.Build();

services.UseCommercetoolsApi(httpApiConfiguration, "HTTPAPIClient");
services.AddLogging();

var serviceProvider = services.BuildServiceProvider();
var httpApiRoot = serviceProvider.GetService<commercetools.Sdk.Api.Client.ProjectApiRoot>();

You can now use the httpApiRoot to build requests to the HTTP API.

Configure using appsettings.json

For ASP.NET Core web applications, you can store your client configuration in appsettings.json instead of in-memory configuration. The configuration section name must match the string passed to the corresponding UseCommercetools method.

Configure client credentials in appsettings.jsonjson
{
  "Client": {
    "ClientId": "{clientID}",
    "ClientSecret": "{clientSecret}",
    "AuthorizationBaseAddress": "https://auth.{region}.commercetools.com/",
    "Scope": "{scope}",
    "ProjectKey": "{projectKey}",
    "ApiBaseAddress": "https://api.{region}.commercetools.com/"
  }
}

Register clients in Program.cs or Startup.cscsharp
// HTTP API
services.UseCommercetoolsApi(configuration, "Client");

// Import API
services.UseCommercetoolsImportApi(configuration, "ImportClient");

// Audit Log API
services.UseCommercetoolsHistoryApi(configuration, "HistoryClient");

After registration, inject IClient into your controllers and call WithProject to get a ProjectApiRoot:

Inject IClient into a controllercsharp
using commercetools.Base.Client;

public class ProductController(IClient client)
{
    public async Task<IProduct> GetProduct(string id)
    {
        var projectApiRoot = client.WithProject("{projectKey}");
        return await projectApiRoot.Products().WithId(id).Get().ExecuteAsync();
    }
}

When using the UseCommercetools methods, a ProjectApiRoot is automatically registered with the service provider using the project key from the configuration. You can inject it directly instead of calling WithProject.

Set up multiple clients

You can register multiple clients in the same application with different configurations or token providers. The following example sets up two clients that each read from their own section in appsettings.json:

Register multiple clientscsharp
services.UseCommercetoolsApi(
    configuration,
    new List<string> { "AdminClient", "StoreClient" },
    CreateTokenProvider);

public static ITokenProvider CreateTokenProvider(
    string clientName,
    IConfiguration configuration,
    IServiceProvider serviceProvider)
{
    var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
    var clientConfiguration = configuration.GetSection(clientName).Get<ClientConfiguration>();
    return TokenProviderFactory.CreateClientCredentialsTokenProvider(
        clientConfiguration,
        httpClientFactory);
}

Your appsettings.json must contain a configuration section for each client name. To select a specific client, inject IEnumerable<IClient> and filter by name:

Select a client by namecsharp
public class OrderController(IEnumerable<IClient> clients)
{
    private readonly IClient _storeClient =
        clients.First(c => c.Name == "StoreClient");
}

Create a client with certain token flows

Use ClientFactory to create a client on the fly with a certain token provider. This is useful when you need to use the Me endpoints, which require a password or anonymous token flow:

Create a client with a password token providercsharp
var configuration = serviceProvider.GetService<IConfiguration>();
var httpClientFactory = serviceProvider.GetService<IHttpClientFactory>();
var serializerService = serviceProvider.GetService<SerializerService>();

var clientConfiguration = configuration.GetSection("MeClient").Get<ClientConfiguration>();

var passwordTokenProvider = TokenProviderFactory.CreatePasswordTokenProvider(
    clientConfiguration,
    httpClientFactory,
    new InMemoryUserCredentialsStoreManager(email, password));

var meClient = ClientFactory.Create(
    "MeClient",
    clientConfiguration,
    httpClientFactory,
    serializerService,
    passwordTokenProvider);

var myProfile = await meClient.WithApi()
    .WithProjectKey("{projectKey}")
    .Me()
    .Get()
    .ExecuteAsync();

When using ClientFactory, call the SetupClient extension method on the service collection to attach the default error handling and logging handlers to the client.

Test the Client

The following code contains test calls which outputs to the log.

For HTTP API

For Import API

For Audit Log API

For Checkout API

// Make a call to get the Project
var myProject = await httpApiRoot
  .Get()
  .ExecuteAsync();

// Output the Project name
Console.WriteLine(myProject.Name);

Use the .NET SDK

Imports

Without importing resource-specific types/namespaces you cannot use specific objects and methods.

For example, to create a Shopping List you must import:

Import the Shopping Lists namespacecsharp
using commercetools.Sdk.Api.Models.ShoppingLists;

If not imported, the SDK returns the The type or namespace name '{name}' could not be found. error and your program will not run.

When using the Import API, Audit Log API, or Checkout API, take care when importing resources as some resources share names in different packages. For example, the HTTP API, Import API, and Audit Log API all have an Asset type. Always use API-specific resources to avoid errors and conflicts.

Create objects

The .NET SDK uses C# object and collection initializer syntax to construct drafts, update actions, and other objects with multiple fields.

Create objects using initializer syntaxcsharp
// Include the following imports:
// using commercetools.Sdk.Api.Models.Categories;
// using commercetools.Sdk.Api.Models.Common;

// Create a LocalizedString
LocalizedString multiLanguageString = new LocalizedString(){
  {"en", "English value"},
  {"de", "German value"}
};

// Create US$100.00
Money money = new Money()
{
  CurrencyCode = "USD",
  CentAmount = 10000
};

// Create a CategoryDraft
CategoryDraft categoryDraft = new CategoryDraft()
{
  Name = new LocalizedString() { { "en", "english name" } },
  Slug = new LocalizedString() { { "en", "english-slug" } },
  Key = "category-key"
};

Consult the API reference for the HTTP API, Import API, Audit Log API, and Checkout API to ensure that you include all required fields.

Structure your API call

Add an endpoint

Add an endpoint to httpApiRoot. The following targets the Shopping Lists endpoint:

var shoppingListInfo = httpApiRoot
  .ShoppingLists()
  // ...

If your IDE supports auto-complete, you can see the full list of endpoints.

If you do not specify an endpoint, the SDK references the Project.

Retrieve data

Get a single resource

When targeting a specific resource, you should include its ID or key followed by Get(), ExecuteAsync(), and Result.

Get a Shopping List by ID or keycsharp
// Get a specific Shopping List by ID
var shoppingListInfo = httpApiRoot
  .ShoppingLists()
  .WithId("a-shoppinglist-id")
  .Get()
  .ExecuteAsync()
  .Result;

// Get a specific Shopping List by key
var shoppingListInfo = httpApiRoot
  .ShoppingLists()
  .WithKey("a-shoppinglist-key")
  .Get()
  .ExecuteAsync()
  .Result;

If you query a resource with an id or key that does not exist, your program will crash with a Not Found error.

In this example, shoppingListInfo now contains the data of the specified Shopping List. You can access information from the fields within that object:

Screenshot of autocomplete for ShoppingList object

Get multiple resources

If you do not include an ID or key, the endpoint returns a PagedQueryResponse, which is identical to PagedQueryResults in the HTTP API.

Query Shopping Listscsharp
// Return an IShoppingListPagedQueryResponse
var shoppingListsQuery = httpApiRoot
  .ShoppingLists()
  .Get()
  .ExecuteAsync()
  .Result;

You can alter the results of these calls by including WithWhere(), WithSort(), WithExpand(), WithLimit(), or WithOffset() after Get().

These are identical to the parameters you can add to standard HTTP API calls. If your IDE supports autocomplete you can view a full list of methods available:

Screenshot of autocomplete for parameters

Use the Query Predicate builder

For querying results you can also use the type safe Query Predicate builders. They allow you to programmatically create a Query Predicate using the withQuery method.

Query using a predicate buildercsharp
// Return all Customers that have not verified their email address
var response = httpApiRoot
 .Customers()
 .Get()
 .WithQuery(c => c.IsEmailVerified().Is(false))
 .ExecuteAsync()
 .Result;

For more examples and available operators, see .NET SDK Query Predicate builders.

Access query results

Regardless of whether you use query parameters or the Query Predicate builder, you can access the list of resources within a PagedQueryResponse using Result:

Access query resultscsharp
// Return an IShoppingListPagedQueryResponse
var shoppingListsQuery = httpApiRoot
  .ShoppingLists()
  .Get()
  .ExecuteAsync()
  .Result;

// Put the returned Shopping Lists in a list
var listOfShoppingLists = shoppingListsQuery.Results;

// Output the first Shopping List's English name
Console.WriteLine(listOfShoppingLists[0].Name["en"]);

Write a resource

Create a new resource

Creating a new resource requires a draft of the resource to create. For Shopping Lists this is a ShoppingListDraft. You create these drafts using builders.

Build a ShoppingListDraftcsharp
// Build a ShoppingListDraft with the required fields (name)
var newShoppingListDetails = new ShoppingListDraft()
{
  Name = new LocalizedString() { { "en", "English name of Shopping List" } }
};

Include newShoppingListDetails within Post() and follow it with ExecuteAsync().

Create a Shopping Listcsharp
// Post the ShoppingListDraft and get the new Shopping List
var newShoppingList = httpApiRoot
  .ShoppingLists()
  .Post(newShoppingListDetails)
  .ExecuteAsync()
  .Result;

Update an existing resource

Updating an existing resource requires posting an update payload. This payload (in the case of Shopping Lists, a ShoppingListUpdate) contains a collection of update actions and the last seen version of the resource.

You can create update actions and payloads by using builders.

Build a ShoppingListUpdatecsharp
// Build a ShoppingListUpdate with the required fields (version and list of IShoppingListUpdateActions)
var shoppingListUpdate = new ShoppingListUpdate()
{
  Version = 1,
  Actions = new List<IShoppingListUpdateAction>
  {
    {
      new ShoppingListSetKeyAction(){Key="a-new-shoppinglist-key"}
    }
  }
};

You can then post the payload to a single resource (using WithId() or WithKey()).

Update a Shopping Listcsharp
// Post the ShoppingListUpdate and return the updated Shopping List
var updatedShoppingList = httpApiRoot
  .ShoppingLists()
  .WithId("{shoppingListID}")
  .Post(shoppingListUpdate)
  .ExecuteAsync()
  .Result;

Delete a resource

Deleting a resource requires using the .Delete() method with the last seen version of the resource. You must identify the resource to delete using WithId() or WithKey().

Delete a Shopping Listcsharp
// Delete and return a Shopping List
var deletedShoppingList = httpApiRoot
  .ShoppingLists()
  .WithId("{shoppingListID}")
  .Delete()
  .WithVersion(1)
  .WithDataErasure(true) // Include to erase related personal data
  .ExecuteAsync()
  .Result;

Use GraphQL

The .NET SDK supports two approaches for working with the GraphQL endpoint.

Basic GraphQL queries

For simple GraphQL queries, use the Graphql() endpoint with a raw query string. The response data is returned as JsonElement and can be accessed using the System.Text.Json API:

Send a basic GraphQL querycsharp
IGraphQLResponse response = await projectApiRoot
    .Graphql()
    .Post(new GraphQLRequest()
    {
        Query = "query($productFilter:String) { products(where: $productFilter) { results { id } } }",
        Variables = new GraphQLVariablesMap()
        {
            { "productFilter", $"id = \"{productId}\"" }
        }
    })
    .ExecuteAsync();

Type-safe GraphQL with the GraphQL package

The .NET SDK has a GraphQL package that provides type-safe GraphQL support.

With the help of ZeroQL you can generate a type-safe query and projection client. The results are then mapped to the correct response type.

The response types have all available fields defined by the selector.

Send a type-safe GraphQL querycsharp
var variables = new { productFilter = $@"id = ""{productId}""" };
var response = await client.Query(variables,
  static (i, o) => o.Products(where: i.productFilter,
      selector: r => new { results = r.Results(product => new { product.Id })}
  )
);

Assert.NotNull(response.Data?.results[0].Id);

Next steps

Continue learning about the .NET SDK by checking our SDK code examples. You will find example code for creating, querying, and updating Customers and Products.

The Me Endpoint Checkout app demonstrates how to use the Me endpoints to create an example web store.

Get started with the .NET SDK

Requirements.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Objectives of the get started guide.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Placeholder values.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Install the .NET SDK.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

PackageReference.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

.NET CLI.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set up the client.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Configure using appsettings.json.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Set up multiple clients.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create a client with certain token flows.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test the Client.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use the .NET SDK.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Imports.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create objects.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Structure your API call.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Add an endpoint.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Retrieve data.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get a single resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Get multiple resources.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use the Query Predicate builder.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Access query results.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Write a resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Create a new resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Update an existing resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Delete a resource.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Use GraphQL.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Basic GraphQL queries.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Type-safe GraphQL with the GraphQL package.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Next steps.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Requirements

Objectives of the get started guide

Placeholder values

Install the .NET SDK

PackageReference

.NET CLI

Set up the client

Configure using appsettings.json

Set up multiple clients

Create a client with certain token flows

Test the Client

Use the .NET SDK

Imports

Create objects

Structure your API call

Add an endpoint

Retrieve data

Get a single resource

Get multiple resources

Use the Query Predicate builder

Access query results

Write a resource

Create a new resource

Update an existing resource

Delete a resource

Use GraphQL

Basic GraphQL queries

Type-safe GraphQL with the GraphQL package

Next steps