System Status

Offer management

Learn how to manage offers. You can use Commerce API to manage offers.

The Offers API is a powerful interface that enables seamless integration and management of special deals, discounts, and promotions through your existing promotion setup systems. This API forms a part of our comprehensive headless solution, ensuring that you can offer more value and flexibility to your customers without manual intervention. You can create, update, deploy, retire, and fetch offers through the Offers API, making managing promotions across various platforms easier. Note that the ability to update is not currently available. We will include these features in future releases.

Offers API capabilities

The Offers API empowers you with robust tools for managing special deals, discounts, and promotions directly through your promotion setup systems. Here are the current capabilities:

  • Create offers: You can easily set up new offers, specifying the details and conditions that suit your needs.

  • Deploy offers: This feature allows you to distribute offers across various channels with a single command. By selecting the target audience, channels, and timing, you can ensure that their promotions reach the right customers at the right moment, maximizing the impact of their marketing efforts. Deployment can be automated based on triggers or scheduled in advance, offering unparalleled flexibility in presenting offers to customers.

  • Get an offer by an identifier: This feature enables you to fetch existing offers. You can retrieve details of specific offers or a list of all offers based on various criteria such as offer type, status, or validity period. This capability ensures you can efficiently manage and review their promotional activities, making adjustments to optimize your marketing strategies.

  • Get an offer by the deployed version: This feature allows you to retrieve an offer's details by its deployment status. By specifying the version, you can accurately track the offer's performance, alterations, and reception by the target audience over time. This feature is particularly useful for understanding the impact of revisions to the offer and ensuring consistency in promotional activities across different marketing channels.

  • Retiring offers: You can retire offers when they are no longer needed or relevant. This process involves marking an offer as inactive, ensuring a shopper cannot apply it to future transactions. This feature is crucial for maintaining the accuracy and efficiency of promotional operations, allowing you to remove or replace offers without impacting the system's integrity or confusing the customers with outdated promotions.

We aim to introduce new features regularly to enhance the functionality and flexibility of the Offers API.

Creating an offer

This guide will explore the step-by-step process of creating an offer through our Offers API. From selecting the right type of offer that suits your marketing strategy to defining the offer's eligibility and deployment, we'll cover all the necessary details to ensure your promotion succeeds. Whether you're looking to attract new customers with a compelling discount or engage current shoppers with a unique promotion, this guide will provide the tools and knowledge needed to craft and execute an effective offer programmatically.

Choosing the right offer type is pivotal in crafting a compelling and successful marketing campaign that resonates with your audience and meets your sales objectives.

  1. Provide the offer's name, description, and offer ID or external reference ID:

    • name: The offer's name serves as a clear identifier for your team and customers, making it easier to refer to and promote the offer. This field is required.

    • description: The offer's description gives internal users insight into the offer. This field is optional.

    • externalReferenceOfferId: The external reference ID is essential for tracking the offer's performance across different platforms or systems, helping analyze its success, and making necessary adjustments. This field is optional. 

          "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOffer",

  2. Choose one of the following offer types:

    • discount: Provide a simple discount on one or more products. A discount directly reduces the price of products, making it a straightforward incentive for customers to purchase products. You can do this through coupons, email campaigns, strike-through pricing, and optional shipping discounts. Note that the ability to use the bundle, banner, and featureProducts offer types are not available now. We plan to include them in the future releases.

    • bundle: Provide a discount when a shopper purchases one or more specific products. A encourages customers to buy more by offering discounts when purchasing multiple products, increasing the average order value.

    • banner: Display a banner ad on your store's pages. A banner visually promotes the offer on your website, catching visitors' attention and guiding them towards the products on promotion. For example, add a banner to the home page, shopping cart, or pop-ups.

    • featureProducts: Showcase a collection of products to encourage shoppers to purchase one of a selected group of products featured in a specific place in your store. Feature products highlight particular products and steer customer focus towards items you wish to sell more, potentially clearing stock or introducing new items. 

          "offerType": "discount",

  3. Choose how to trigger the offer:

    • promotionalUrlOrExternalTriggered: Provide the offer in a point of promotion (POP) in your store or as a link to the offer in an email or social media campaign. The offer trigger method, promotionalUrlOrExternalTriggered, allows the activation of an offer through a specific URL or an external event or action. This trigger type is particularly useful for digital marketing campaigns where you can provide a link directly in an email, social media post, or advertisement. The offer is applied when the recipient clicks on the link or engages in the specified external action (such as visiting a point of promotion in-store). This method enables seamless integration of promotions across various platforms, enhancing the customer's ease of access to offers and potentially increasing the campaign's overall engagement and conversion rates. Note that the ability to use the couponCode trigger type is not available now. We plan to include it in a future release.

    • couponCode: Provide a coupon code for shoppers to redeem the offer. Triggering an offer through a couponCode lets you engage customers in a classic yet highly effective way. When you create an offer with a coupon code, you provide a straightforward mechanism for shoppers to redeem the offer. This method is versatile, and you can use it in various promotional activities, such as email marketing, physical mailers, or social media campaigns.

      How it works:

      • The couponCode is a unique identifier the shopper enters at checkout or in a designated promotional field within your store.

      • Upon entering the code, the system automatically applies the discount or promotion associated with the offer to the shopper's purchase.

      • To tailor the promotion to your marketing strategy, you can set restrictions on the coupon code, such as a usage limit per shopper or expiration date.

      Advantages:

      • Direct engagement: Encourages direct interaction with your promotion, increasing shopper engagement.

      • Easy distribution: You can easily share a coupon code through various channels, reaching a wide audience.

      • Customizable: Offers flexibility regarding usage limits and eligibility, allowing for targeted promotions.

      Incorporating a couponCode as a trigger for your offer is a proven strategy to enhance customer participation in your promotions and can significantly impact your campaign's success. 

      "offerTrigger": "promotionalUrlOrExternalTriggered",

  4. Provide the offer's start and end date:

    • The offerStartDate and offerEndDate define the active period for an offer, marking when the promotion begins and ends. These dates are significant because they:

      • Ensure the promotion is only available during the intended timeframe, which is crucial for limited-time offers that aim to drive immediate action from customers.

      • Help plan and manage inventory by predicting increased demand during the promotional period.

      • Allow businesses to analyze the offer's performance within a specific time range, aiding in future marketing strategy adjustments.

          "offerStartDate": "2024-03-22T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",

  5. Determine the behavior: Decide where the discount will apply. You have the following options:

    • discountLevel: The discount level indicates where the discount is applied. This field is required. Choose one of the following options as the value:

      • product: The discount will be applied at the product level.

      • order: The discount will be applied at the order level. Note that the ability to view the order value is not available now. We plan to include it in a future release. Note that the ability to use the order discount level is not available now. We plan to include it in a future release.

    • shippingDiscount: The shipping discount will be applied. If other non-shipping discounts for the products or orders exist, they also will be used. This field is required. Note that the ability to use the shippingDiscount is not available now. We plan to include it in a release.

    • usageControls: Use usageControls to control how often individual shoppers can redeem an offer (limit individual shopper usage) or how many times all shoppers can redeem the offer in your store (limit total usage). This field is optional.

    • localeRestrictions: Either allow the offer for all locales or restrict the offer to specific locales. This field is required. 

          "localeRestrictions": true,

  6. Determine eligibility:

    Note that the ability category offers such as specificCategories and allCategoriesExceptExcludedCategories are not available now. We plan to include them in the future releases.

    • eligibityDeterminedBy: Determine the eligibility for a discount by choosing one of the following options:

      • specificProducts: Eligibility is determined by specific products identified in the value.

        • noDiscount: Apply no discount to the specified products.

        • applyDiscountToAllProducts: Apply discount to all specified products.

        • applyIndividualDiscountsToProducts: Apply individual discounts to the specified products.

        • specificCategories: Eligibility is determined by specific categories identified in the value.

          • noDiscount: Apply no discount to the specified categories.

          • applyDiscountToAllCategories: Apply discount to all specified categories.

        • allProductsExceptExcludedProducts: Eligibility is determined by all products except those products excluded in the value.

          • noDiscount: Apply no discount to all products except the specified products.

          • applyDiscountToAllProducts: Apply discount to all products except the specified products.

        • allCategoriesExceptExcludeCategories: Eligibility is determined by all categories except those products excluded in the value.

          • noDiscount: Apply no discount to all categories except the specified categories.

          • applyDiscountToAllCategories: Apply discount to all categories except the specified categories.

              "eligibityDeterminedBy": [
        {
            "specificProducts": "applyDiscountToAllProducts"
        },
    ],

  7. Describe the offer:

    • offerContent: Provide a brief description of the offer. This field is optional. This text appears (in the cart) when a shopper triggers an offer. Enter the text that promotes or highlights the offer. For example, "You saved $10 on this order with our special holiday promotion." If the offer is for a single product, the offer description appears below the product in the Shopping Cart by default. If the offer is for an entire order, the offer description appears at the bottom of the Shopping Cart by default. If you do not want anything to appear, leave this field blank. 

          "offerContent": "You saved $10 on this order with our special holiday promotion.",
curl --location POST'http://api.digitalriver.com/v1/offers' \
--header 'x-siteId: paytest2' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOffer",
    "offerType": "discount",
    "offerTrigger": "promotionalUrlOrExternalTriggered",
    "offerStartDate": "2024-03-22T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",
    "supportedLocales": [
        {
            "locale": "en_US"
        },
        {
            "locale": "de_DE"
        }
    ],
    "totalUsageLimit": 18,
    "shopperUsageLimit": 12,
    "catalogId": "823600",
    "currency": "USD",
    "priceListType": "listPrice",
    "products": [
        {
            "id": "255678200",
            "discountType": "Percent Off",
            "discountValue": 10
        },
        {
            "id": "255678300",
            "discountType": "Amount",
            "discountValue": 1
        }
    ]
}'

Deploying an offer

Deploying an offer is a straightforward process that transforms your meticulously crafted promotion into a live event accessible by your customers. Once you create an offer, activating it involves a simple yet crucial step—deployment. This phase is where the magic happens; your offer transitions from a well-planned concept to an active element of your marketing strategy, ready to entice customers and drive sales. This section will guide you through the steps to deploy your offer, ensuring it reaches your audience effectively and within the desired timeframe.

You will receive a unique offer ID or ERID after creating an offer. When deploying the offer using the POST v1/offers/{offerID or ERID}/deploy request, provide this ID in the {offerID or ERID} URI path parameter. Replace {yourSiteId} with your actual site ID.

Deploying an offer by offerID

curl --location --request POST 'http://api.digitalriver.com/v1/offers/{offerID}/deploy' \
--header 'x-siteId: {yourSiteId}' \
--header 'Accept: application/json' \

Deploying an offer by ERID

curl --location --request POST 'http://api.digitalriver.com/v1/offers/{ERID}/deploy' \
--header 'x-siteId: {yourSiteId}' \
--header 'Accept: application/json' \
--header 'x-erid-as-oid: true'

Ensure to include the header x-erid-as-oid: true when deploying an offer using ERID to identify the offer using the external reference ID system to identify the offer using the external reference ID system accurately.

Upon successfully deploying the offer, the API response will change the offer's status to Deployed. This status confirms your offer is active and visible in your store, allowing shoppers to redeem it according to the specified start and end dates.

Getting an offer by identifier

Retrieving detailed information about an offer is crucial to managing promotions within your business. Whether you created an offer through Global Commerce or via the Commerce API, you can fetch offer details using its unique identifier. This process involves a simple API call that can be executed with either the offer's ID or its External Reference ID (ERID), ensuring flexibility and ease of access. This section will guide you through the steps to get the most recent version of the offer by its identifier, allowing you to manage and review your promotional offers efficiently.

You will receive a unique offer ID or ERID after creating an offer, irrespective of the creation method (Global Commerce or API). When getting an offer using the POST /v1/offers/{offerID or ERID} request, provide this ID in the {offerID or ERID} URI path parameter. Replace {yourSiteId} with your actual site ID.

Get an offer by offerID

curl --location GET 'http://api.digitalriver.com/v1/offers/{offerId}' \
--header 'x-siteId: paytest2' \
--header 'Accept: application/json' \

Get an offer by ERID

curl --location GET 'http://api.digitalriver.com/v1/offers/{ERID}' \
--header 'x-siteId: paytest2' \
--header 'Accept: application/json' \
--header 'x-erid-as-oid: true'

Ensure to include the header x-erid-as-oid: true when fetching an offer using ERID to identify the offer using the external reference ID system to identify the offer using the external reference ID system accurately.

You can get an offer by offerId or ERID under the following conditions:

  • Regardless of whether you created the offer through Global Commerce or the Commerce API.

  • Regardless of the offer's deployment status.

  • Regardless of whether the offer has been retired or not.

Getting an offer by deployment version

There may be situations where you need to obtain information about an offer based on its deployment status. The status is particularly important when managing offers with different versions, such as draft, deployed, or retired states. Commerce API provides a way to retrieve offer details by specifying the offer ID (or ERID) and the version status in the request. This functionality enables you to access the specific state of an offer, ensuring that you are working with the correct version for your requirements. Whether you need to track changes, manage offer availability, or verify the current status of an offer, this guide will help you efficiently retrieve an offer by its deployed version using the Commerce API.

You will receive a unique offer ID or ERID after creating an offer, irrespective of the creation method (Global Commerce or API). When getting an offer by the ID and deployed version using the GET /v1/offers/{offerID or ERID}?version=deployed request, provide this ID in the {offerID or ERID} URI path parameter and include the version=deployed query parameter with the offer status you want to fetch. Replace {yourSiteId} with your actual site ID.

We only support version=deployed. The request will throw an error if you provide any other offer status.

Get an offer by offerID

curl --location GET 'http://api.digitalriver.com/v1/offers/{offerId}?version=deployed' \
--header 'x-siteId: paytest2' \
--header 'Accept: application/json' \

Get an offer by ERID

curl --location GET 'http://api.digitalriver.com/v1/offers/{ERID}?version=deployed' \
--header 'x-siteId: paytest2' \
--header 'Accept: application/json' \
--header 'x-erid-as-oid: true'

Replace {offerId} or {ERID} with your specific offer identifier and yourSiteId with your actual site ID.

Ensure to include the header x-erid-as-oid: true when fetching an offer using ERID to identify the offer using the external reference ID system to identify the offer using the external reference ID system accurately.

You can get an offer by offerId or ERID under the following conditions:

  • Regardless of whether you created the offer through Global Commerce or the Commerce API

  • Irrespective of the offer's deployment status

  • Regardless of whether the offer has been retired or not

An offer's status

Understanding your offer's status is essential to managing it effectively. Each status represents a different phase in the offer's lifecycle, from creation and deployment to its eventual expiration or retirement. Below, we detail an offer's various statuses and what each status signifies for your offer's availability and visibility to your customers. This comprehensive overview ensures you are well-informed to take the necessary actions at each stage of the offer lifecycle.

The offer's status can be one of the following:

  • Draft: When an offer is in draft state, it is unavailable to shoppers in your store. This status is the default when you do not deploy the offer.

  • Design: This status indicates that while someone applied changes to the deployed store offer, the undeployed changes are unavailable to shoppers. If you want shoppers to see these changes, deploy the changes.

  • Deployed: This status indicates that the offer is active and visible in your store, allowing shoppers to redeem it.

  • Retired: This offer is no longer available as it has been manually retired from your store. Although you cannot reactivate it, you can copy it to create a new offer.

  • Expired: This message indicates that the offer has expired and is no longer available for redemption in the store.

Understanding changes to an offer's status

To effectively manage and understand the lifecycle and visibility of offers within Global Commerce, observing how an offer's status reflects through various API calls is helpful. The table below outlines different Global Commerce statuses and the corresponding responses one can expect when querying offer details via the Commerce API. This information is crucial for ensuring that offers are properly managed, from initial draft to deployment and, ultimately, to their retirement or expiration. Whether an offer is being modified or is ready for shopper interaction, understanding these API responses can significantly streamline offer management processes.

StepsGET /v1/offers/{offerId}GET /v1/offers/{offerId}?version=deployed

Step 1: create an offer Global Commerce status: Draft The offer is not available to shoppers in the store.

The response shows the latest Draft version.

The response shows 404 Not Found.

Step 2: deploy an offer Global Commerce status: Deployed Shoppers can see the offer in the store.

The response shows the latest Deployed version.

The response shows the latest Deployed version.

Step 3: modify an offer Global Commerce status: Design The changes in the Designed state are unavailable to shoppers. The shoppers only see the Deployed version. If you want shoppers to see these change, deploy the offer.

The response shows the latest Design version.

The response shows the latest Deployed version.

Step 4: deploy an offer Global Commerce status: Deployed The shoppers can now see the latest changes to the offer.

The response shows the latest Deployed version.

The response shows the latest Deployed version.

Step 5: Retire an offer Global Commerce status: Retired Shoppers can no longer see the offer in the store.

The response shows the latest Retired version.

The response shows 404 Not Found.

Retiring an offer by identifier

Sometimes, you may need to retire an offer while managing your offers. A retired offer will no longer be available for redemption. Removing offers that have served their purpose or need removal is crucial. Digital River offers a simple way to retire an offer using its unique identifier (ID or ERID) through Commerce API. This guide will explain how to retire an offer by its identifier.

You will receive a unique offer ID or ERID after creating an offer, irrespective of the creation method (Global Commerce or API). When retiring an offer using the POST /v1/offers/{offerId}/retire request, provide this ID in the {offerID or ERID} URI path parameter. Replace {yourSiteId} with your actual site ID.

Retire an offer by offerID

curl --location --request POST 'http://api.digitalriver.com/v1/offers/{offerId}/retire' \
--header 'x-siteId: {siteId}' \
--header 'Accept: application/json' \

Retire an offer by ERID

curl --location --request POST 'http://api.digitalriver.com/v1/offers/{ERID}/retire' \
--header 'x-siteId: {siteId}' \
--header 'Accept: application/json' \
--header 'x-erid-as-oid: true'

Replace {offerId} or {ERID} with your specific offer identifier and yourSiteId with your actual site ID.

Ensure to include the header x-erid-as-oid: true when retiring an offer and using ERID to identify the offer using the external reference ID system to identify the offer using the external reference ID system accurately.

PreviousDownloading the invoiceNextRefund management

Last updated