Reference - Promotion REST API 1.2.0 (ICM 7.10)

Document View

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

icm-b2b-promotion-1x2x0.yaml

References

The following page lists available REST APIs for ICM 7.10 and their version dependencies:

Reference - Intershop Commerce Management 7.10 REST API

API Specification

Introduction

OpenAPI Version: 3.0.1

Promotion Version: 1.2.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{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(java.lang.Boolean)

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	spgid	string		`FUOGrzQ_VjORpGaN8DRGmLLE0000`	The secure personalization group identifier, submitted as matrix parameter `;spgid=<PGID>`. Required if you want to work with customer-specific content.
in query	includeCodePromotions	boolean	`false`	`true`	Determines whether code-based promotions are returned. If set to `true`, the complete list of promotions is returned. If set to `false`, only promotions that do not require a promotion code are returned (default).

Response

200 - OK - The available promotions.

LinkROResourceCollectionRO application/json

401 - Unauthorized - The user could not be authenticated.

/promotions{spgid}/{promotionID}

GET: Returns details for a promotion

Description

This operation returns details for a promotion. The response contains an object of Type PromotionRO.
By default, only information about a promotion assigned to the customer group "Everyone" can be returned. To retrieve information about a personalized promotion based on a direct customer assignment or a customer segment, use the spgid parameter.

Java Method

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

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	spgid	string		`FUOGrzQ_VjORpGaN8DRGmLLE0000`	The secure personalization group identifier, submitted as matrix parameter `;spgid=<PGID>`. Required if you want to work with customer-specific content.
in path	promotionID	string		`10PercentageOffOnAudioEquipment`	Required \| The promotion ID

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.

Product API

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

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

Java Method

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

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	spgid	string		`FUOGrzQ_VjORpGaN8DRGmLLE0000`	The secure personalization group identifier, submitted as matrix parameter `;spgid=<PGID>`. Required if you want to work with customer-specific content.
in path	categoriesKey	string		`151`	Required \| The category ID
in path	productKey	string		`201807231`	Required \| The product ID
in query	includeCodePromotions	boolean	`false`	`true`	Determines whether code-based promotions are returned. If set to `true`, the complete list of promotions is returned. If set to `false`, only promotions that do not require a promotion code are returned (default).

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.

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

Java Method

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

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in path	spgid	string		`FUOGrzQ_VjORpGaN8DRGmLLE0000`	The secure personalization group identifier, submitted as matrix parameter `;spgid=<PGID>`. Required if you want to work with customer-specific content.
in path	productKey	string		`201807231`	Required \| The product ID
in query	includeCodePromotions	boolean	`false`	`true`	Determines whether code-based promotions are returned. If set to `true`, the complete list of promotions is returned. If set to `false`, only promotions that do not require a promotion code are returned (default).

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 element. This is normally a constant that can be used to differentiate elements 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 element. This is normally a constant that can be used to differentiate elements 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:
"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 element. This is normally a constant that can be used to differentiate elements by their type.
- "key":
  string
- "value":
  string
- "description":
  string
- "uri":
  boolean
  Indicates whether the attachment is an external link (true) or an internal file (false)
- "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.