Document Properties
Kbid296R00
Last Modified23-Feb-2021
Added to KB03-Sep-2020
Public AccessEveryone
StatusOnline
Doc TypeReferences
ProductICM 7.10

Reference - Promotion API 1.0.0


Product Version

7.10

Product To Version


Status

final

Download Specification 

This API specification is available for download as an Open API 3.0 YAML file: 

API Specification

Introduction

OpenAPI Version: 3.0.1
Promotion Version: 1.0.0

The Intershop Promotion REST API contains operations that allow to retrieve promotion information.

General API

The following operations for retrieving general promotion data are available:

/promotions/{promotionID}
GET: Returns details for a promotion

Description

This operation returns details for a promotion. The response contains an object of Type PromotionRO.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.common.capi.resource.PromotionResource.getPromotionByID(java.lang.String)

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathpromotionIDstringRequired | The promotion ID | Example: 10PercentageOffOnAudioEquipment

Response

200 - OK

- The promotion with the given ID.
PromotionRO application/json

401 - Unauthorized

- The user could not be authenticated.

404 - Not Found

- The promotion could not be found.
/promotions{spgid}
GET: Returns a personalized list of promotions

Description

This operation returns a personalized list of available promotions for the store. The response Resource Collection contains objects of Type LinkRO.

By default only promotions assigned to the customer group "Everyone" are returned. To retrieve personalized promotions based on direct customer assignment or customer segment, use the spgid parameter.

Java Method

public javax.ws.rs.core.Response com.intershop.sellside.rest.common.capi.resource.PromotionResource.getPromotions()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathspgidstringThe secure personal group identifier (submitted as matrix parameter ;spgid=<PGID>). | Example: FUOGrzQ_VjORpGaN8DRGmLLE0000

Response

200 - OK

- The available promotions.
LinkROResourceCollectionRO application/json

401 - Unauthorized

- The user could not be authenticated.

Product API

The following operations for retrieving product-specific promotions are available:

/products/{productKey}/promotions{spgid}
GET: Returns applicable promotions for a product

Description

This operation returns a list of all promotions which are applicable for the current product.

By default only promotions assigned to the customer group "Everyone" are returned. To retrieve personalized promotions based on direct customer assignment or customer segment, use the spgid parameter.

Java Method

public com.intershop.component.rest.capi.resourceobject.ResourceCollectionRO com.intershop.sellside.rest.common.capi.resource.promotion.ProductPromotionResource.getProductPromotions()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathspgidstringThe secure personal group identifier (submitted as matrix parameter ;spgid=<PGID>). | Example: FUOGrzQ_VjORpGaN8DRGmLLE0000
in pathproductKeystringRequired | The product ID | Example: 201807231

Response

200 - OK

- The applicable promotions for the given product.
LinkROResourceCollectionRO application/json

401 - Unauthorized

- The user could not be authenticated.

404 - Not Found

- The promotion could not be found.
/categories/{categoriesKey}/products/{productKey}/promotions{spgid}
GET: Returns applicable promotions for a product

Description

This operation returns a list of all promotions which are applicable for the current product.

By default only promotions assigned to the customer group "Everyone" are returned. To retrieve personalized promotions based on direct customer assignment or customer segment, use the spgid parameter.

Java Method

public com.intershop.component.rest.capi.resourceobject.ResourceCollectionRO com.intershop.sellside.rest.common.capi.resource.promotion.ProductPromotionResource.getProductPromotions()

Request Body

--

Request Parameters

LocationNameFormatDescription
in pathspgidstringThe secure personal group identifier (submitted as matrix parameter ;spgid=<PGID>). | Example: FUOGrzQ_VjORpGaN8DRGmLLE0000
in pathcategoriesKeystringRequired | The category ID | Example: 151
in pathproductKeystringRequired | The product ID | Example: 201807231

Response

200 - OK

- The applicable promotions for the given product.
LinkROResourceCollectionRO application/json

401 - Unauthorized

- The user could not be authenticated.

404 - Not Found

- The promotion could not be found.

Request and Response Object Schemata

LinkROResourceCollectionRO application/json{
  • "pageable":
    string
    The pageable ID
  • "total":
    integer
    The pageable amount total | Format: int32
  • "offset":
    integer
    The pageable offset | Format: int32
  • "amount":
    integer
    The pageable amount | Format: int32
  • "elements":
    array
    An array of LinkRO objects. The list of elements
    [
    LinkRO: A Link pointing to a resource
    {
    • "name":
      string
      the name of the returned element
    • "type":
      string
      Readonly | This is a constant: Link | Example: Link
    • "attributes":
      array
      An array of ResourceAttribute objects. the list of attributes
      [
      ResourceAttribute: An attribute
      {
      • "name":
        string
        The attribute's name
      • "type":
        string
        This is a constant: ResourceAttribute | Example: ResourceAttribute
      • "value":
        object
        The attribute's value.
      }
      ]
    • "uri":
      string
      The uri
    • "relation":
      string
      The relation of the link | Documentation: Link Relations (www.iana.org) | Possible Values: aboutalternateappendixarchivesauthorbookmarkcanonicalchaptercollectioncontentscopyrightcreate-formcurrentdescribedbydescribesdisclosureduplicateeditedit-formedit-mediaenclosurefirstglossaryhelphostshubiconindexitemlastlatest-versionlicenselrddmonitormonitor-groupnextnext-archivenofollownoreferrerpaymentpredecessor-versionprefetchprevpreviewpreviousprev-archiveprivacy-policyprofilerelatedrepliessearchsectionselfservicestartstylesheetsubsectionsuccessor-versiontagterms-of-servicetypeupversion-historyviaworking-copyworking-copy-of
    • "title":
      string
      The title of the link
    • "description":
      string
      The description of the link
    • "itemId":
      string
      the Id of the linked item
    • "attribute":
      object
      A ResourceAttribute object. An attribute
      {
      • "name":
        string
        The attribute's name
      • "type":
        string
        This is a constant: ResourceAttribute | Example: ResourceAttribute
      • "value":
        object
        The attribute's value.
      }
    }
    ]
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type.
  • "sortKeys":
    array
    An array of string literals. The keys to sort for
  • "name":
    string
    The name of an element.
}
PromotionRO application/json{
  • "name":
    string
    The name of an element.
  • "type":
    string
    The type of the object. This is normally a constant that can be used to differentiate objects by their type. | Example: Promotion
  • "attributes":
    array
    An array of ResourceAttribute objects. The list of attributes
    [
    ResourceAttribute: An attribute
    {
    • "name":
      string
      The attribute's name
    • "type":
      string
      This is a constant: ResourceAttribute | Example: ResourceAttribute
    • "value":
      object
      The attribute's value.
    }
    ]
  • "icon":
    string
    The icon of the promotion | Example: free shipping!
  • "currency":
    string
    The currency which the promotion is applicable to | Example: USD
  • "promotionID":
    string
    The promotion ID
  • "id":
    string
    The promotion ID | Example: FreeOledTvShipping
  • "description":
    string
    The promotion description | Example: For LED TVs the shipping is free.
  • "promotionType":
    string
    The type of the promotion | Example: ShippingPercentageOffDiscount
  • "longTitle":
    string
    The long title of the promotion | Example: Free shipping on orders with an LED TV.
  • "legalContentMessage":
    string
    The legal content message | Example: Offer valid only while supplies last (...)
  • "ruleDescription":
    string
    The rule for the promotion to apply | Example: Buy any LED TV and the order ships free.
  • "title":
    string
    The short title of the promotion | Example: free shipping!
  • "couponCodeRequired":
    boolean
    Indicates whether a coupon code is required for this promotion (true/false) | Example: false
  • "externalUrl":
    string
    Readonly | External URL | Example: http://www.abc.de
  • "useExternalUrl":
    boolean
    Readonly | If this value is set to 'true', only the external URL is used for promotion details, if set to 'false', the external URL is used in addition to the promotion details. | Example: true
  • "disableMessages":
    boolean
    Readonly | Indicates whether promotion messages are disabled (true/false) | Example: true
  • "attachments":
    array
    An array of AttachmentRO objects.
    [
    AttachmentRO:
    {
    • "name":
      string
      The name of an element.
    • "type":
      string
      Readonly | The type of the object. This is normally a constant that can be used to differentiate objects by their type.
    • "key":
      string
    • "value":
      string
    • "description":
      string
    • "uri":
      boolean
    • "link":
      object
      A LinkRO object. A Link pointing to a resource
      {
      • "name":
        string
        the name of the returned element
      • "type":
        string
        Readonly | This is a constant: Link | Example: Link
      • "attributes":
        array
        An array of ResourceAttribute objects. the list of attributes
        [
        ResourceAttribute: An attribute
        {
        • "name":
          string
          The attribute's name
        • "type":
          string
          This is a constant: ResourceAttribute | Example: ResourceAttribute
        • "value":
          object
          The attribute's value.
        }
        ]
      • "uri":
        string
        The uri
      • "relation":
        string
        The relation of the link | Documentation: Link Relations (www.iana.org) | Possible Values: aboutalternateappendixarchivesauthorbookmarkcanonicalchaptercollectioncontentscopyrightcreate-formcurrentdescribedbydescribesdisclosureduplicateeditedit-formedit-mediaenclosurefirstglossaryhelphostshubiconindexitemlastlatest-versionlicenselrddmonitormonitor-groupnextnext-archivenofollownoreferrerpaymentpredecessor-versionprefetchprevpreviewpreviousprev-archiveprivacy-policyprofilerelatedrepliessearchsectionselfservicestartstylesheetsubsectionsuccessor-versiontagterms-of-servicetypeupversion-historyviaworking-copyworking-copy-of
      • "title":
        string
        The title of the link
      • "description":
        string
        The description of the link
      • "itemId":
        string
        the Id of the linked item
      • "attribute":
        object
        A ResourceAttribute object. An attribute
        {
        • "name":
          string
          The attribute's name
        • "type":
          string
          This is a constant: ResourceAttribute | Example: ResourceAttribute
        • "value":
          object
          The attribute's value.
        }
      }
    }
    ]
  • "attribute":
    object
    A ResourceAttribute object. An attribute
    {
    • "name":
      string
      The attribute's name
    • "type":
      string
      This is a constant: ResourceAttribute | Example: ResourceAttribute
    • "value":
      object
      The attribute's value.
    }
}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets