LogoLogo
System Status
  • Commerce API
    • Test and use cases
    • Roles and permissions
    • Sending API calls
  • Shopper APIs
    • Shopper basics
      • Common use cases
        • Creating a customer
        • Applying store credit
        • Private store workflow
        • Guest checkout
    • OAuth
      • Authentication
      • OAuth 2.0 APIs
      • Token
      • Access tokens
      • Session-aware access tokens
      • Authorizing a shopper
    • Shoppers
      • Managing shoppers
        • User management
        • Single sign-on (SSO)
        • Data validation
        • Bulk user management
        • Bulk user account export
      • Managing a shopper's account
      • Managing a shopper's address
      • Managing payment options
    • Product discovery
      • Categories
      • Products
      • Product variations
      • Pricing
      • Inventory status
      • Financing
      • Offers
        • Understanding offers
        • How to use point of promotions (POPs)
          • Retrieving all point of promotion offers for a specific product
          • Retrieving all offers for a specific point of promotion
        • How to use offers
      • Private stores
        • Managing private stores
        • Submitting an order for a private store
        • Useful APIs
      • Fulfillment
        • Electronic Fulfillment Service (OFI)
        • Digital rights
        • Digital rights revocation
        • Physical fulfillment
          • EDI X12 832 definition data elements
          • EDI X12 846 definition data elements
          • EDI X12 850 definition data elements
          • EDI X12 855 definition data elements
          • EDI X12 856 definition data elements
          • EDI X12 180-1 definition data elements
          • EDI X12 180-2 definition of data elements
          • EDI X12 180-3 definition of data elements
    • Cart
      • Applying a shopper to a cart
      • Getting the current cart
      • Creating or updating a cart
        • Adding a product to a cart
          • Gifting
        • Capturing the customer's IP address
        • Providing address information
        • Managing the shipping or billing address
        • Providing subscription information
        • Managing payment methods
        • Capturing the Terms of Sale (TOS) acceptance
      • Managing offers in a cart
        • Applying an offer
        • Applying a coupon or promo code
        • Getting all applied offers
        • Removing an applied offer
        • Removing eligible offers
        • Reconciling conflicting offers
        • Dynamic offers/personalization
          • Skipping Global Commerce merchandising offer arbitration
          • Triggering a promotional URL offer
          • Overriding a promotional URL offer discount
      • Pricing
        • Landed cost
          • Mixed cart support
          • Tax-included pretty price
      • Redirecting to a Digital River-hosted cart
      • Configuring taxes
        • Managing tax identifiers
      • Managing shipping options
        • Getting shipping options
        • Providing a shipping discount
      • Managing line items
      • Applying a price override
      • Managing payment sessions
      • Managing web checkout
      • Submitting a cart
        • Initiating a charge
        • Authorization declines
      • Resuming cart submission
      • HGOP2
    • Orders
      • Getting orders
      • Selling entities
      • Retrieving addresses from an order
      • Retrieving line items from an order
      • Order lookup
      • Returns
        • Initiate an authenticated session
        • Setting up returns in Global Commerce
        • Managing returns
    • Subscriptions
      • Retrieve the subscription
        • Getting all orders for a subscription
        • Getting a subscription's pending actions
        • Getting all subscriptions for a shopper
        • Getting a subscription by identifier
      • Update subscription at the next renewal
        • Changing the subscription renewal type
        • Changing the subscription renewal quantity
        • Adding or updating a perpetual unit price
        • Changing the subscription's payment option
        • Changing the subscription's payment source
      • Immediately change the subscription
        • Updating the subscription's shipping address
        • Updating a subscription's billing and shipping email address
        • Cancelling a subscription
      • Immediately apply a midterm subscription change
        • Reducing the subscription renewal quantity
  • Admin APIs
    • Admin basics
      • Available Admin API calls
    • Order management
      • Getting the order's details
      • Downloading the invoice
    • Offer management
    • Refund management
      • Authorization
      • Refund reason codes
      • Creating a satisfaction refund
      • Getting the available refunds for a specific order
      • Getting refunds for a specific order
      • Getting refunds available for a shopper's order
      • Getting the JSON schema for an order refund
      • Managing a refund for a delayed payment method
      • Refund error scenarios
    • Subscription management
      • Retrieve the subscription
        • Getting all orders for a subscription
        • Getting a subscription's pending actions
        • Getting all subscriptions for a shopper
        • Getting a subscription by identifier
      • Update the subscription at the next renewal
        • Changing the subscription renewal type
        • Changing the subscription renewal product
        • Changing the subscription renewal price
        • Changing the subscription renewal quantity
        • Adding or updating a perpetual unit price
        • Changing the subscription's payment option
        • Changing the subscription's payment source
      • Immediately change the subscription
        • Activating a subscription
        • Changing the subscription's external reference identifier
        • Updating a subscription's billing and shipping email address
        • Cancelling a subscription
        • Updating the subscription's expiration date
      • Immediately apply a midterm subscription change
        • Applying a midterm change with price override
        • Reducing the subscription renewal quantity
      • Subscription notifications
        • Updating the subscriber's email address
        • Card Account Updater
        • Sending a payment information change notification
        • Sending an expired credit card notification
        • Sending an invalid payment account notification
        • Sending a payment failure notification
        • Sending a subscription renewal reminder notification
        • Setting up subscription renewal reminders
        • Setting up trial subscription renewal reminders
        • Setting up marketing reminders
      • Using the Expired Card Optimizer
    • Customer management
      • Retrieving customer details
      • Requesting PII removal for a customer
    • Site management
      • Configuring authorized shipping and billing countries
      • Getting a site's authorized billing countries
      • Getting a site's authorized shipping countries
    • Product management
      • Getting started
      • Manage products (asynchronous API)
        • Creating or updating a product
        • Adding or updating a product variation
        • Deploying a product
        • Applying live changes
        • Retiring a product
        • Deleting a product variation
        • Deleting a base or individual product's locale
      • Retrieve products (synchronous API)
        • Getting a product by locale
        • Getting a product variation
        • Getting a product variation by locale
      • Get the task status for a product (synchronous API)
        • Getting the latest information on a product task
        • Retrieving the tasks for a specific product
        • Retrieving the tasks for products
      • Bulk operation
        • Asynchronous bulk operations
          • Creating products in bulk
          • Updating products in bulk
          • Deploying products in bulk
          • Deleting product variations in bulk
        • Bulk product upload (BPU)
        • Bulk Product Export (BPE)
          • Line-item level satisfaction refund
          • Order-level satisfaction refund
          • Auto-created line-item level return product
          • Line-item level return product
    • File management
      • Downloading a file
  • Payments
    • Payments solutions
      • Drop-in payments
        • How Drop-in payments work
        • Drop-in payments integration guide
      • DigitalRiver.js with Elements
        • Elements integration guide
        • Configuring payment methods
          • Configuring Afterpay
          • Configuring Alipay+ (cross-border)
          • Configuring Alipay (domestic)
          • Configuring Amazon Pay
          • Configuring Apple Pay
          • Configuring Bancontact
          • Configuring BLIK
          • Configuring Boleto
          • Configuring CCAvenue
          • Configuring Clearpay
          • Configuring Credit Cards
          • Configuring FPX Online Banking
          • Configuring Google Pay
          • Configuring iDEAL
          • Configuring Klarna
          • Configuring Konbini
          • Configuring Online Banking (IBP)
          • Configuring Online Banking (Korea Bank Transfer)
          • Configuring PayCo
          • Configuring PayPal
          • Configuring SEPA Direct Debit
          • Configuring Trustly
          • Configuring Wire Transfer
          • Common payment sources
          • Common payment objects
    • Supported payment methods
      • Afterpay
      • Alipay (domestic)
      • Alipay+ (cross-border)
      • Amazon Pay
      • Apple Pay
      • Bancontact
      • BLIK
      • Boleto
      • CCAvenue
      • Clearpay
      • Credit Cards
      • FPX Online Banking
      • Google Pay
      • iDEAL
      • Klarna
      • Konbini
      • Korea Bank Transfer (Online Banking)
      • Online Banking (IBP)
      • PayCo
      • PayPal
      • PayPal Billing Agreement
      • PayPal Credit
      • PayPal Pay in 3
      • PayPal Pay in 4
      • PayPal RatenZahlung (Installment Payment)
      • SEPA Direct Debit
      • Trustly
      • Wire Transfer
    • Source basics
      • Managing sources
      • Handling credit card sources
      • Retrieving sources
    • Building payment workflows
      • Flows by payment type
      • Handling redirect payment methods
    • PSD2 and SCA
    • Payment testing scenarios
      • Testing standard payment methods
      • Testing redirect payment methods
      • Testing receiver payment methods
      • Testing the CCAvenue payment method
  • Events
    • Events overview
    • Responding to events
    • Event types
      • Delayed payment event types
        • Delayed payment expired event
          • Boleto
          • Konbini
          • Wire Transfer
        • Delayed payment reminder event
          • Boleto
          • Konbini
          • Wire Transfer
      • Subscription event types
        • Subscription created event
        • Subscription updated event
        • Subscription action processed event
        • Subscription cancelled event
        • Subscription credit card expired event
        • Subscription payment information changed event
        • Subscription renewal reminder event
        • Subscription renewed event
        • Subscription trial converted event
        • Subscription trial renewal reminder event
        • Subscription payment failed event
      • Post-order event types
        • Invoice created event
        • Refund credit memo event
      • Inventory event types
        • Inventory out of stock event
        • Inventory source and management
        • Inventory self-managed updated event
        • Inventory fulfiller-managed updated event
      • Post-order Notification Integration Guide
    • Webhooks
      • Commerce API safelist
      • Searching for a webhook
      • Creating a webhook
      • Using webhooks
      • Editing a webhook
      • Turning webhooks on or off
      • Revealing a webhook's secret
      • Rotating a webhook's secret
      • Viewing the webhook details
      • Deleting a webhook
  • Developer Resources
    • Postman collection
    • Commerce API references
    • Shopper APIs reference
    • Admin APIs reference
    • DigitalRiver.js reference
      • Including DigitalRiver.js
      • Initializing DigitalRiver.js
      • DigitalRiver object
      • Elements
        • Amazon Pay element
        • Apple Pay elements
        • Google Pay elements
        • IBAN element
        • iDEAL element
        • Konbini elements
        • Compliance element
        • Offline refund element
        • Online Banking elements
        • Tax Identifier element
        • Delayed payment instructions element
        • PayPal elements
      • Guidelines for capturing payment details
      • Security
      • Digital River payment objects
      • Error types, codes, and objects
  • General resources
    • Global Commerce
    • Global Commerce
      • Company hierarchy
      • Categories
        • Getting a list of categories
      • Products
        • Product scenarios
        • Individual products
          • Creating an individual product
        • Base product with variants
          • Creating a base product with variants
        • Bundle offers
          • Creating a prorated bundle offer with a subscription
        • Product combination
          • Creating a product combination
        • Gifting
        • Inventory status
      • Customer service
        • Log a shopper's request to remove PII
      • Customers
        • Creating a customer
        • Digital River-maintained customer login
        • Client-maintained customer login
      • Transparent Commerce purchase flow
    • eCompass
    • eCompass documentation
    • Release notes
      • 2024
      • 2024 latest
      • 2023
      • 2022
      • 2021
      • 2020
Powered by GitBook
On this page
  • Offers API capabilities
  • Creating an offer
  • Deploying an offer
  • Getting an offer by identifier
  • Getting an offer by deployment version
  • An offer's status
  • Understanding changes to an offer's status
  • Retiring an offer by identifier

Was this helpful?

  1. Admin APIs

Offer management

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

PreviousDownloading the invoiceNextRefund management

Last updated 4 months ago

Was this helpful?

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:

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

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

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

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

  • : 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 . 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
        }
    ]
}'
{
    "id": "37061020197",
    "status": "Draft",
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOffer",
    "siteId": "paytest2",
    "offerType": "discount",
    "offerTrigger": "promotionalUrlOrExternalTriggered",
    "offerStartDate": "2024-03-22T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",
    "creationDate": "2024-03-22T13:04:58.182Z",
    "modificationDate": "2024-03-22T13:04:58.182Z",
    "localeRestrictions": true,
    "defaultLocale": "en_US",
    "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.

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.

{
    "id": "37061140197",
    "status": "Deployed",
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOffer",
    "siteId": "paytest2",
    "offerStartDate": "2024-03-22T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",
    "creationDate": "2024-03-22T19:26:13.261Z",
    "modificationDate": "2024-03-22T19:26:13.261Z",
    "localeRestrictions": true
}

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.

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.

{
    "id": "37134000197",
    "status": "Draft",
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOfferUnique",
    "siteId": "paytest2",
    "offerType": "discount",
    "offerTrigger": "promotionalUrlOrExternalTriggered",
    "offerStartDate": "2024-04-12T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",
    "creationDate": "2024-04-08T07:41:23.624Z",
    "modificationDate": "2024-04-08T07:44:37.460Z",
    "localeRestrictions": true,
    "defaultLocale": "en_US",
    "supportedLocales": [
        {
            "locale": "en_US"
        },
        {
            "locale": "en_GB"
        },
        {
            "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.00
        }
    ]
}

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.

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.

{
    "id": "37134000197",
    "status": "Deployed",
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOfferUnique",
    "siteId": "paytest2",
    "offerType": "discount",
    "offerTrigger": "promotionalUrlOrExternalTriggered",
    "offerStartDate": "2024-04-12T00:00:00.000Z",
    "offerEndDate": "2024-04-22T00:00:00.000Z",
    "creationDate": "2024-04-08T07:41:23.624Z",
    "modificationDate": "2024-04-08T07:44:37.460Z",
    "localeRestrictions": true,
    "defaultLocale": "en_US",
    "supportedLocales": [
        {
            "locale": "en_US"
        },
        {
            "locale": "en_GB"
        },
        {
            "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.00
        }
    ]
}

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.

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

The response shows the latest Draft version.

The response shows 404 Not Found.

The response shows the latest Deployed version.

The response shows the latest Deployed version.

The response shows the latest Design version.

The response shows the latest Deployed version.

The response shows the latest Deployed version.

The response shows the latest Deployed version.

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.

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.

{
    "id": "37134000197",
    "status": "Retired",
    "name": "DiscountPromotionalOffer",
    "description": "DiscountPromotionalOffer",
    "externalReferenceOfferId": "DiscountPromotionalOfferUnique",
    "siteId": "paytest2",
    "creationDate": "2024-04-08T07:41:23.624Z",
    "modificationDate": "2024-04-08T07:44:37.460Z"
}

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

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

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

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

Global Commerce status: Deployed Shoppers can see the offer in the store.

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

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

Global Commerce status: Retired Shoppers can no longer see the offer in the store.

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

Offers API
Create offers
Deploy offers
Get an offer by an identifier
Get an offer by the deployed version
Retiring offers
Step 1: create an offer
Step 2: deploy an offer
Step 3: modify an offer
deploy the offer
Step 4: deploy an offer
Step 5: Retire an offer
creating an offer
creating an offer
creating an offer
status
creating an offer
POST /v1/offers/{offerID or ERID}
POST /v1/offers/{offerID or ERID}
GET /v1/offers/{offerID or ERID}?version=deployed
POST /v1/offers/{offerId}/retire