> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/commerce-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/commerce-api/shopper-apis/product-discovery/offers/how-to-use-offers.md).
# How to use offers
Offers are promotions or discounts that can be applied to products or services within your Digital River store. They can boost sales, engage customers, and drive traffic to your platform. In this section, you will learn how to manage and retrieve offers using the Digital River API, including creating, updating, and fetching offer details by their unique identifiers.
## Getting an offer by identifier
When you need to retrieve specific details of an offer, you can obtain it using its unique identifier. This section explains how to send a request to get an offer by its ID, detailing the necessary API endpoint, request method, and required headers for authentication.
To get an offer by its identifier, send [`GET /shoppers/me/offers/{offerId}`](https://docs.digitalriver.com/commerce-api-references/shopper-apis/browse-product-discovery/offers#v1-shoppers-me-offers-offerid) request. Replace `{offerId}` with the actual offer ID you want to retrieve. Include a valid API key in the authorization header.
Example:
{% tabs %}
{% tab title="cURL" %}
```http
curl --location --request GET
'https://api.digitalriver.com/shoppers/me/offers/{offerId}' \
--header 'Authorization: Bearer {API_key}'
```
{% endtab %}
{% tab title="200 OK response" %}
```json
{
"offer": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709",
"id": 154344709,
"name": "Home Page Security & Backup Recovery Features",
"policyName": "string",
"type": "FeatureProducts",
"image": "https://drh1.img.digitalriver.com/DRHM/Storefront/Site/demosft1/images/promo/security_header.gif",
"trigger": "Always Triggered",
"salesPitch": [
"[\"Header Message\",\"Footer Message\",\"Sales Pitch Extra Info\",\"Sales Pitch Extra Info 2\"]"
],
"productOffers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers",
"productOffer": [
{
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers/64358400",
"id": 64358400,
"product": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/products/64358400",
"displayName": "Class III",
"thumbnailImage": "https://drh1.img.digitalriver.com/DRHM/Storefront/Company/demosft1/images/product/thumbnail/classIIIThumb_v2.jpg"
},
"pricing": {
"listPrice": {
"currency": "USD",
"value": "19.99"
},
"salePriceWithQuantity": {
"currency": "USD",
"value": "19.99"
},
"formattedListPrice": "$39.99",
"formattedSalePriceWithQuantity": "$38.99",
"listPriceIncludesTax": "false"
}
}
]
},
"categoryOffers": {},
"offerBundleGroups": {}
}
}
```
{% endtab %}
{% endtabs %}
A successful `200 OK` response returns the offer details in JSON format, including its status, discount amount, and terms.
## Getting the product for the offer
You can access precise details about the product offer, including its pricing, images, and additional promotional information. This can be particularly useful for shoppers who wish to evaluate individual products within a broader promotional offer.
To retrieve a specific product for an offer, send a [`GET /shoppers/me/offers/{offerId}/product-offers/{productOfferId}`](https://docs.digitalriver.com/commerce-api-references/shopper-apis/browse-product-discovery/offers#v1-shoppers-me-offers-offerid-product-offers-productofferid) request. Replace `{offerId}` and `{productOfferId}` with the respective IDs. Include a valid API key in the authorization header.
Example:
{% tabs %}
{% tab title="cURL" %}
```http
curl --location --request GET
'https://api.digitalriver.com/shoppers/me/offers/{offerId}/product-offers/{productOfferId}' \
--header 'Authorization: Bearer {API_key}'
```
{% endtab %}
{% tab title="200 OK response" %}
```json
{
"productOffer": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers/64358400",
"id": 64358400,
"product": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/products/64358400",
"displayName": "Class III",
"thumbnailImage": "https://drh-sys-ora.img.digitalriver.com/Storefront/Company/demosft1/images/product/thumbnail/classIIIThumb_v2.jpg"
},
"addProductToCart": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/carts/active/line-items?productId=64578500&offerId=154344709",
"cartUri": "https://api.digitalriver.com/v1/shoppers/me/carts/active?productId=64578500&offerId=154344709"
},
"salesPitch": "For testing purposes",
"image": "https://drh-sys-ora.img.digitalriver.com/Storefront/Site/demosft1/images/promo/business_header.gif",
"pricing": {
"listPrice": {
"currency": "USD",
"value": "19.99"
},
"salePriceWithQuantity": {
"currency": "USD",
"value": "19.99"
},
"formattedListPrice": "$39.99",
"formattedSalePriceWithQuantity": "$38.99",
"listPriceIncludesTax": "false"
}
}
}
```
{% endtab %}
{% endtabs %}
A successful request returns a `200 OK` response.
## Retrieving all offers for a product
Retrieving all offers for a specific product can be useful when displaying available promotions or deals associated with that product. Below, you'll find the necessary endpoint and an example of how to make the request and handle the response.
To retrieve all offers for a product, send a [`GET /shoppers/me/products/{productId}/offers`](https://docs.digitalriver.com/commerce-api-references/shopper-apis/browse-product-discovery/offers#v1-shoppers-me-products-productid-offers) request. Replace `{productId}` with the respective product ID. Include a valid API key in the authorization header.
Example:
{% tabs %}
{% tab title="cURL" %}
curl --location --request GET
'https://api.digitalriver.com/shoppers/me/products/{productId}/offers' \
--header 'Authorization: Bearer {API_key}' \
{% endtab %}
{% tab title="200 OK response" %}
```json
{
"offers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers",
"offer": [
{
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709",
"name": "Home Page Security & Backup Recovery Features",
"trigger": "Always Triggered",
"productOffers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers"
},
"categoryOffers": {},
"offerBundleGroups": {}
}
],
"totalResults": 1,
"totalResultPages": 1
}
}
```
{% endtab %}
{% endtabs %}
A successful request returns a `200 OK response`.
## Retrieving all offers
Retrieving all offers for a specific product is essential for showcasing various promotions, deals, and discounts available. This allows customers to take advantage of special pricing and other promotional benefits. The following guide explains retrieving these offers.
The retrieved offers include:
* All always-triggered offers
* All user-triggered promotional URLs and externally triggered offers
* All user-triggered coupon code offers
To retrieve all offers for a specific product, send a [`GET /shoppers/me/offers`](https://docs.digitalriver.com/commerce-api-references/shopper-apis/browse-product-discovery/offers#v1-shoppers-me-offers) request. Additionally, ensure a valid API key is included in the authorization header. This request retrieves all available offers for the specified product.
Example:
{% tabs %}
{% tab title="cURL" %}
curl --location --request GET
'https://api.digitalriver.com/shoppers/me/offers' \
--header 'Authorization: Bearer {API_key}' \
{% endtab %}
{% tab title="200 OK respone" %}
```json
{
"offers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers",
"offer": [
{
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709",
"name": "Home Page Security & Backup Recovery Features",
"trigger": "Always Triggered",
"productOffers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers"
},
"categoryOffers": {},
"offerBundleGroups": {}
}
],
"totalResults": 1,
"totalResultPages": 1
}
}
```
{% endtab %}
{% endtabs %}
A successful request returns a `200 OK response`.
## Getting all products for the offer
You can gather comprehensive information about the products included in the offer, ensuring you have all the necessary data for further processing or display.
To get all products for an offer, send a [`GET /shoppers/me/offers/{offerId}/product-offers`](https://docs.digitalriver.com/commerce-api-references/shopper-apis/browse-product-discovery/offers#v1-shoppers-me-offers-offerid-product-offers) request. Replace `{offerId}` with the appropriate offer ID. Include a valid API key in the authorization header. This request retrieves all products associated with the specified offer.
Example:
{% tabs %}
{% tab title="cURL" %}
curl --location --request GET
'https://api.digitalriver.com/shoppers/me/offers/{offerId}/product-offers' \
--header 'Authorization: Bearer {API_key}' \
{% endtab %}
{% tab title="200 OK response" %}
```json
{
"productOffers": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers",
"productOffer": [
{
"uri": "https://api.digitalriver.com/v1/shoppers/me/offers/154344709/product-offers/64358400",
"id": 64358400,
"product": {
"uri": "https://api.digitalriver.com/v1/shoppers/me/products/64358400",
"displayName": "Class III",
"thumbnailImage": "https://drh-sys-ora.img.digitalriver.com/Storefront/Company/demosft1/images/product/thumbnail/classIIIThumb_v2.jpg"
},
"pricing": {
"listPrice": {
"currency": "USD",
"value": "19.99"
},
"salePriceWithQuantity": {
"currency": "USD",
"value": "19.99"
},
"formattedListPrice": "$39.99",
"formattedSalePriceWithQuantity": "$38.99",
"listPriceIncludesTax": "false"
}
}
]
}
}
```
{% endtab %}
{% endtabs %}
A successful request returns a `200 OK response`.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.digitalriver.com/commerce-api/shopper-apis/product-discovery/offers/how-to-use-offers.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.