Offer management

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

The Offers API is a powerful interface designed for our clients, enabling seamless integration and management of special deals, discounts, and promotions directly through their existing systems. This API forms a part of our comprehensive headless solution, ensuring that our clients can offer more value and flexibility to their customers without manual intervention. Clients 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, retire, and fetch is not currently available. We will include these features in future releases.

Current Capabilities of the Offers API

The Offers API is designed to empower our clients with robust tools for managing special deals, discounts, and promotions directly through their systems. Here are the current capabilities:

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

  • Deploy offers: This feature allows clients to distribute offers across various channels with a single command. By selecting the target audience, channels, and timing, clients 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.

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

Creating an offer

Creating a compelling offer for your products can significantly enhance customer engagement and sales during a promotional period. However, ensuring the deployment of the offer requires a systematic approach, especially when handling the process programmatically. This section will guide you through the steps necessary to craft and deploy an offer programmatically, ensuring it meets the promotion’s success criteria and avoids deployment issues. Follow along carefully to learn how to create an offer that attracts attention and drives results.

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 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.

  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.

  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 that shoppers can use 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.

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

      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.

  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.

  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.

  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.

  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.

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

Once you have created an offer, deploying it is the next crucial step to make it available to your customers. This process allows your offer to be active and accessible based on the defined start and end dates. Follow these steps to deploy your offer:

  1. Identify the Offer ID or ERID: You will receive a unique offer ID or ERID after creating an offer. This ID is necessary for the deployment process.

  2. Prepare the Deployment Request: You must use the Digital River API to deploy your offer. Prepare a POST request using the endpoint designed for deploying offers. The request should include your site ID and acknowledge the use of an external reference ID (ERID) if applicable.

  3. Execute the Request:

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

    Replace {offerId} with your unique offer ID and {yourSiteId} with your actual site ID.

  4. Verify Deployment: Upon successfully deploying the offer, the API response will change the offer's status to "Deployed." This status confirms your offer is active and will be available to customers according to the specified start and end dates.

By following these steps, you can seamlessly deploy your offers, ensuring they are timely and effectively presented to your target audience.

The following example deploys an offer with a specific {offerId}.

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

An ERID request requires a specific {ERID} and the x-erid-as-oid: true header.

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

PreviousDownloading the invoiceNextRefund management

Last updated