---
title: "Work with the Promotions API"
slug: "work-with-the-promotions-api"
abstract: "How to use the Sitecore XC Promotions API to integrate promotion-related operations with other business systems using C# programming."
---
# Work with the Promotions API

This topic contains information on how to use the [Sitecore XC Promotions](https://doc.sitecore.com/xp/en/developers/102/sitecore-experience-commerce/promotions-service.html "Promotions service") API to integrate promotions-related operations with other business systems, using C# programming.

You must include Commerce Engine operations and commands within a container call (using C#) as shown in this [example](https://doc.sitecore.com/xp/en/developers/102/sitecore-experience-commerce/build-a-container--c--.html "Build a container (C#)").

To execute any operation in the Sitecore Experience Commerce (XC) system, the calling system must first [obtain a valid bearer authorization](https://doc.sitecore.com/xp/en/developers/102/sitecore-experience-commerce/obtain-an-authentication-token--c--.html "Obtain an authentication token (C#)") token for the Sitecore Identity Server.

<details>
<summary><h2>Get a promotion book (C#)</h2></summary>

A promotion book is a collection of promotions, which can apply to sellable items that are contained in multiple catalogs.

You can retrieve promotion books using a friendly id. Optionally, as part of the OData query, you can [expand](https://www.odata.org/getting-started/basic-tutorial/#expand) the promotion book components.

Use the following request to retrieve a promotion, for example, with its components, using C#:

```csharp
DataServiceQuerySingle<PromotionBook> query = container.PromotionBooks.ByKey(bookFriendlyId).Expand("Components");
PriceBook book = Proxy.GetValue(query);

```

</details>

<details>
<summary><h2>Get catalogs associated to a promotion book (C#)</h2></summary>

A promotion book can be associated to multiple catalogs.

To retrieve catalogs that are associated with a given promotion book, for example, using C#:

```

DataServiceQuerySingle<PromotionBook> query = container.GetPromotionBookAssociatedCatalogs("MyPromotionBook");
IEnumerable<AssociatedCatalogModel> associatedCatalogs = Proxy.GetValue(query);

```

</details>

<details>
<summary><h2>Get a promotion (C#)</h2></summary>

You can retrieve a promotion by specifying its friendly ID. Optionally, as part of the OData query, you can [expand](https://www.odata.org/getting-started/basic-tutorial/#expand) the promotion book components.

To retrieve a promotion, for example, with its components, using C#:

```csharp
DataServiceQuerySingle<Promotion> query = container.Promotions.ByKey(promotionFriendlyId).Expand("Components");
PriceBook book = Proxy.GetValue(query);

```

</details>