Page tree

 

 

 

 

 

 

 

 

 

 

 

 

 

Loyalty Management API
Conformance Profile

 

Document Number TMF658B

May 2017

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Release: Frameworx Release 17.0

Status: Member Evaluation

Version: 1.0.0

IPR Mode: RAND


NOTICE

 

Copyright © TM Forum 2017. All Rights Reserved.

 

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

4 Century Drive
Suite 100
Parsippany, NJ 07054, USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org





API DESCRIPTION

 

Enables comprehensive definition of multiple loyalty programs to drive customer centricity and loyalty. The operations below are considered mandatory.

 

Minimum requirements required for the loyalty program definition:

 

  • Create new event types (POST)
  • Get an event type (GET)
  • Create new conditions (POST)
  • Get a condition by ID (GET)
  • Create new actions (POST)
  • Get an action by ID (GET)
  • Create new loyalty program product specifications (POST)
  • Get a loyalty program product specification by ID (GET)
  • Create new loyalty rules (POST)
  • List all loyalty rules for a program specification (GET)
  • Link event types to the loyalty rule (POST)
  • Get all linked event types for a loyalty rule (GET)
  • Link conditions to the loyalty rule (POST)
  • Get all linked conditions for a loyalty rule (GET)
  • Link event types to the actions (POST)
  • Get all linked actions for a loyalty rule (GET)

 

Minimum requirements required for the loyalty member loyalty events:

 

  • Create new loyalty program members (POST)
  • Get a loyalty program member with a specific ID (GET)
  • Create new loyalty loyalty product for a member (which includes a loyalty account and balance creation) (POST)
  • List all a loyalty program member’s products (GET)
  • Create a new loyalty event (a notification of an event that is to be considered for loyalty processing) (POST)
  • Get a member’s account balances (GET)
  • Earn loyalty points (POST)
  • Burn loyalty points (POST)
  • Get loyalty execution points (a record of loyalty actions applied) (GET)

 

This document identifies the parameters that must be included in a request related to the operations above as well as the parameters expected in the response.



Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

eventType

M

The name of the event type.

 

 

  Loyalty Condition MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

attribute

M

The name of the attribute that must be evaluated.

operator

M

Must be one of the following values: >,>=,<,<=,=,!=


value

M

The value of the attribute to be compared.

 

 

  Loyalty Action MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

actionAttributes

O

Attributes that may be used in action processing calculation. These values may be used as replacement tokens in the action endpoint and body.

headers

O

Headers that is sent with the action execution request.

body

O

The request body that is sent. It may contain tokens (denoted with {}) that will be replaced from a combination of the loyalty program member profile, the actionAttributes and event attributes.

commonName

O

An optional name to describe the action.

description

O

A description of the action.

action

M

The HTTP verb that is used for the action request. Must be POST, PUT, PATCH,


 

 

GET or DELETE.

endpoint

M

The URL that is called if all the loyalty conditions are met. May contain tokens denoted with {}, which will be replaced the same way as described in the ‘body’ comments.

version

O

The version of the action definition. 1.0 by default.

 

 

  Loyalty Program Product Spec MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

name

M

A name to describe the loyalty program product spec.

description

O

A description of the specification.

productNumber

M

An identification number assigned to uniquely identify the specification.

brand

O

 

needsLoyaltyAccount

O

True of false. The default is true.


lifeCycleStatus

O

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

 

 

 

 

  Loyalty Rule MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

commonName

O

A name to describe the loyalty program product spec.

description

O

A description of the specification.

isCNF

O

True or false. True means that all rule conditions should be true (use AND operator). False means only one condition must be true (uses OR operator). The default is true.

hasSubRules

O

True or false. The default is false.


isMandatoryEvaluation

O

True or false. True signifies atomic rule evaluation and false signifies a best-effort approach. The default is true.

usage

O

 

keywords

O

 

policyName

O

 

 

In the LoyaltyRule LoyaltyEventType sub-resource, global EventTypes are linked to LoyaltyRules.

 

Attribute Name

Mandatory or Optional

Comments

id

M

The ID of the LoyaltyEventType to be linked.

quantity

M (in response messages)

 

O (otherwise)

Value in response must be the same as the link to the LoyaltyEventType.

 

In the LoyaltyRule LoyaltyCondition sub-resource, global LoyaltyCondition are linked to LoyaltyRules.

 

Attribute Name

Mandatory or Optional

Comments

id

M

The ID of the LoyaltyCondition to be linked.

quantity

M (in response messages)

 

O (otherwise)

Value in response must be the same as the link to the LoyaltyCondition.

 

In the LoyaltyRule LoyaltyAction sub-resource, global LoyaltyAction are linked to LoyaltyRules.

 

Attribute Name

Mandatory or

Comments


 

Optional

 

id

M

The ID of the LoyaltyAction to be linked.

quantity

M (in response messages)

 

O (otherwise)

Value in response must be the same as the link to the LoyaltyAction.

 

 

  Loyalty Program Member MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

name

O

 

status

O

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

 

 

  Loyalty Program Product MANDATORY AND OPTIONAL ATTRIBUTES


For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

name

O

 

description

O

 

productStatus

O

 

productSpecId

M

The ID of the LoyaltyProgramProductSpec that describes this product.

accountId

M (if the product spec needsLoyaltyAccount is true and if an existing account is reused)

Either accountId or loyaltyAccount should be present if LoyaltyProgramProductSpec that the product uses dictates that the product must be true (needsLoyaltyAccount=true).

characteristics

O

Name value pairs with free text product characteristics.

loyaltyAccount

M

 

 

id

O

 

 

loyaltyBalance

M

A loyaltyAccount should have at least one loyaltyBalance.The loyaltyBalance may be a single loyaltyBalance in an object


 

 

 

container, or a list of loyaltyBalances (loyaltyBalance [*])

 

id

O

 

 

quantity

M

 

 

unit

M

The balance unit is mandatory.

 

balance

O

 

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

 

 

  Loyalty Balance MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

Value in response must be the same as the one set in Location header provided upon entity creation


 

O (otherwise)

 

quantity

O

 

 

unit

O

 

 

balance

 

 

validFor

O

 

 

startDateTime

O

 

 

endDateTime

O

 

 

 

 

 

  Loyalty Earn MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

quantity

M

The quantity of loyalty rewards to earn.

openingBalance

O (in response messages only)

The loyalty balance before the loyalty points were earned.


closingBalance

O (in response messages only)

The loyalty balance after the loyalty points was earned.

dateTime

O (in response messages only)

The time stamp that the loyalty earn was applied.

description

O

 

 

 

  Loyalty Burn MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

quantity

M

The quantity of loyalty rewards to burn.

openingBalance

O (in response messages only)

The loyalty balance before the loyalty points were burned.

closingBalance

O (in response messages only)

The loyalty balance after the loyalty points was burned.

dateTime

O (in response messages only)

The time stamp that the loyalty burn was applied.

description

O

 


  Loyalty Event MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

 

 

 

 

 

 

Attribute Name

Mandatory or Optional

Comments

eventId

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

memberId

M

The ID of the member associated with the event.

eventTime

O

The time the event was triggered.

eventType

M

The event type. This value is matched against all the rules linked to this event type definition.

event

M

An object, containing the event type name, with attributes, e.g.

"event":{

"productOrder":{ "id":"42",

"href":"http://serverlocation:port/ orderManagement/productOrder/42", "externalId":"NiceNameForTheConsumer_42",

}


 

 

}

 

The attribute name (“productOrder”, in this example) inside the event object must be the same as the eventType attribute.

 

 

 

 

  Loyalty Execution Point MANDATORY AND OPTIONAL ATTRIBUTES

 

For the resource managed by the API, please refer to the following table indicating which attributes are mandatory and which ones are optional.

 

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

 

O (otherwise)

Generated by the server and provided in the response upon resource creation.

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

href

M (in response messages)

 

O (otherwise)

Value in response must be the same as the one set in Location header provided upon entity creation

actionAttributes

O

Attributes that may be used in action processing calculation. These values may be used as replacement tokens in the action endpoint and body.

headers

O

Headers that is sent with the action execution request.

body

O

The request body that is sent. It may contain tokens (denoted with {}) that will be replaced from a combination of the loyalty program member profile, the actionAttributes and event attributes.

commonName

O

An optional name to describe the action.

description

O

A description of the action.


action

M

The HTTP verb that is used for the action request. Must be POST, PUT, PATCH, GET or DELETE.

endpoint

M

The URL that is called if all the loyalty conditions are met. May contain tokens denoted with {}, which will be replaced the same way as described in the ‘body’ comments.

version

O

The version of the action definition. 1.0 by default.

dateTime

O

 


API  OPERATIONS CONFORMANCE

 

For every single resource use the following templates and define what operations are optional and what operations are mandatory.

 

  Loyalty Event Type MANDATORY AND OPTIONAL OPERATIONS

 

 

 

 

Uniform API Operation

Mandatory/Optional

Comments

GET (Retrieve)

M

GET must be used to retrieve a representation of a resource

POST

M

POST must be used to create a new resource

GET (List)

O

GET must be used to retrieve a representation of a resource

PATCH

O

PUT must be used to completely update a resource identified by its resource URI

DELETE

O

DELETE must be used to remove a resource

 

 

  Loyalty Condition MANDATORY AND OPTIONAL OPERATIONS

 

Uniform API Operation

Mandatory/Optional

Comments

GET (Retrieve)

M

GET must be used to retrieve a representation of a resource

POST

M

POST must be used to










 

 

resource URI

DELETE

O

DELETE must be used to remove a resource


API  GET  FILTERING OPERATION CONFORMANCE

 

Definitions

 

Filtered Search: A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search.

 

Filtered Data (Attribute selection): In order to apply a filter and limit the number of attributes included in the response, the GET request can include the “?fields=” query parameter.

 

 

  Filtering in LoyaltyEventType resource

 

Attribute name

Filtered search

First Level

Filtered search

N Level

Attribute Selection First Level

Attribute Selection N Level

id

M

NA

M

NA

href

NA

NA

M

NA

eventType

M

NA

M

NA

 

 

  Filtering in LoyaltyCondition resource

 

Attribute name

Filtered search

First Level

Filtered search

N Level

Attribute Selection First Level

Attribute Selection N Level

id

M

NA

M

NA

href

NA

NA

M

NA

attribute

M

NA

M

NA

operator

O

NA

M

NA








API  POST OPERATION CONFORMANCE

 

  POST to /loyaltyEventType

 

This operation is used to create a loyalty event type resource on the server.

 

The response to this operation must include a Location header set to /loyaltyEventType/{ID} where {ID} indicates the identifier assigned by the server to the new event type created.

 

POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when an event type with the same ID or event type field already exists

Unprocessable Entity Code 422

M

Used when the event type resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when creating a new event type resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

eventType

M

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyCondition

 

This operation is used to create a loyalty condition resource on the server.

 

The response to this operation must include a Location header set to /loyaltyCondition/{ID} where

{ID} indicates the identifier assigned by the server to the new condition resource created.


POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when a condition with the same ID

Unprocessable Entity Code 422

M

Used when the condition resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when creating a new condition resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

attribute

M

 

 

operator

M

 

 

value

M

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyAction

 

This operation is used to create a loyalty action resource on the server.

 

The response to this operation must include a Location header set to /loyaltyAction/{ID} where

{ID} indicates the identifier assigned by the server to the new action resource created.

 

POST

M

 

Response Status Code 201

M

 


Conflict Status Code 409

M

Used when an action with the same ID

Unprocessable Entity Code 422

M

Used when the action resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when creating a new action resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

type

M

 

 

actionAttributes

N

 

 

headers

N

 

 

body

N

 

 

version

N

1.0

 

commonName

N

 

 

description

N

 

 

action

M

 

 

endpoint

M

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramProductSpec


This operation is used to create a loyalty program product specification resource on the server.

 

The response to this operation must include a Location header set to

/loyaltyProgramProductSpec/{ID} where {ID} indicates the identifier assigned by the server to the new program spec resource created.

 

POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when a program with the same ID

Unprocessable Entity Code 422

M

Used when the program resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when creating a new program resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

name

M

 

 

description

N

 

 

productNumber

M

 

 

brand

N

 

 

needsLoyaltyAccount

N

true

 

lifeCycleStatus

N

 

 

validFor

N

 

 


The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramSpec/{specId}/loyaltyRule

 

This operation is used to create a loyalty rule resource on the server.

 

The response to this operation must include a Location header set to

/loyaltyProgramProductSpec/{specID}/loyaltyRule/{ID} where {ID} indicates the identifier assigned by the server to the new rule resource created.

 

POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The product specification does not exist.

Conflict Status Code 409

M

Used when a rule with the same ID

Unprocessable Entity Code 422

M

Used when the rule resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when creating a new rule resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

N

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

commonName

N

 

 

description

N

 

 

isCNF

M

true

 

hasSubRules

N

false

 


isMandatoryEvaluation

N

true

 

usage

N

 

 

keywords

N

 

 

policyName

N

 

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramSpec/{specId}/loyaltyRule/{ruleId}/loyaltyEventType

 

This operation is used to link an existing event type to an existing loyalty rule.

 

The response to this operation must include a Location header set to

/loyaltyProgramProductSpec/{specID}/loyaltyRule/{ruleId}/loyaltyEventType/{ID} where {ID} indicates the identifier of the global event type resource ID.

 

POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The product specification or rule does not exist.

Conflict Status Code 409

M

Used when the event type is already linked to the rule.

 

 

The following table indicates attributes that are required to be sent when linking the event type to the rule.

 

Attribute name

Mandatory

Default

Rule

id

M

 

The ID of the existing event type.


The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramSpec/{specId}/loyaltyRule/{ruleId}/loyaltyCondition

 

This operation is used to link an existing condition to an existing loyalty rule.

 

The response to this operation must include a Location header set to

/loyaltyProgramProductSpec/{specID}/loyaltyRule/{ruleId}/loyaltyCondition/{ID} where {ID} indicates the identifier of the global condition resource ID.

 

POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The product specification or rule does not exist.

Conflict Status Code 409

M

Used when the condition is already linked to the rule.

 

 

The following table indicates attributes that are required to be sent when linking the condition to the rule.

 

Attribute name

Mandatory

Default

Rule

id

M

 

The ID of the existing condition.

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramSpec/{specId}/loyaltyRule/{ruleId}/loyaltyAction

 

This operation is used to link an existing action to an existing loyalty rule.

 

The response to this operation must include a Location header set to

/loyaltyProgramProductSpec/{specID}/loyaltyRule/{ruleId}/loyaltyAction/{ID} where {ID} indicates the identifier of the global action resource ID.


POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The product specification or rule does not exist.

Conflict Status Code 409

M

Used when the condition is already linked to the rule.

 

 

The following table indicates attributes that are required to be sent when creating a new action resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

M

 

The ID of the existing condition.

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

 

 

  POST to /loyaltyProgramMember

 

This operation is used to create a new loyalty program member.

 

The response to this operation must include a Location header set to

/loyaltyProgramMember/{ID} where {ID} indicates the identifier assigned by the server to the new member resource created.

 

POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when the member already exists.

Unprocessable Entity Code 422

M

Used when the member resource does not conform to field rules.


The following table indicates attributes that are required to be sent when creating a new member resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

O

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

name

O

 

 

status

O

 

 

validFor

O

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyProgramMember/{memberId}/loyaltyProgramProduct

 

This operation is used to create a new loyalty program product for a loyalty member.

 

The response to this operation must include a Location header set to

/loyaltyProgramMember/{memberId}/loyaltyProgramProduct/{ID} where {ID} indicates the identifier assigned by the server to the new product resource created.

 

POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when the member product already exists.

Not Found 404

M

The member does not exist.

Unprocessable Entity Code 422

M

Used when the member product resource does not conform to field rules.


The following table indicates attributes that are required to be sent when creating a loyalty member program product resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

O

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

name

O

 

 

description

O

 

 

productStatus

O

 

 

productSpecId

M

 

 

characteristics

O

 

 

accountId

M

 

Either accountId or loyaltyAccount must be present if the loyalty program spec definition needsLoyaltyAccount attribute is true.

loyaltyAccount

M

 

Either accountId or loyaltyAccount must be present if the loyalty program spec definition needsLoyaltyAccount attribute is true.

validFor

O

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.


  POST to /loyaltyEvent

 

This operation is used to trigger the loyalty evaluation.

 

The response to this operation must include a Location header set to /loyaltyEvent where {ID} indicates the identifier assigned by the server to the new loyalty event resource created.

 

POST

M

 

Response Status Code 201

M

 

Conflict Status Code 409

M

Used when the loyalty event ID already exists.

Unprocessable Entity Code 422

M

Used when the loyalty event does not conform to field rules.

 

The following table indicates attributes that are required to be sent when creating a loyalty member program product resource as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

eventId

O

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

eventType

M

 

The event type. This value is matched against all the rules linked to this event type definition.

eventTime

O

 

 

memberId

M

 

 

event

M

 

 


The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyAccount/{accountId} /loyaltyBalance/{balanceId}/loyaltyEarn

 

This operation is used to create loyalty earnings on a loyalty account.

 

The response to this operation must include a Location header set to

/loyaltyAccount/{accountId}/loyaltyBalance/{balanceId}/loyaltyEarn/{ID} where {ID} indicates the identifier assigned by the server to the new member resource created.

 

POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The account or balance does not exist.

Conflict Status Code 409

M

Used when the loyalty earn transaction ID already exists.

Unprocessable Entity Code 422

M

Used when the earn resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when earning loyalty as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

O

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

quantity

M

 

 

openingBalance

O

 

 

closingBalance

O

 

 

dateTime

O

 

 


description

O

 

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.

 

  POST to /loyaltyAccount/{accountId} /loyaltyBalance/{balanceId}/loyaltyBurn

 

This operation is used to create loyalty burn on a loyalty account.

 

The response to this operation must include a Location header set to

/loyaltyAccount/{accountId}/loyaltyBalance/{balanceId}/loyaltyBurn/{ID} where {ID} indicates the identifier assigned by the server to the new member resource created.

 

POST

M

 

Response Status Code 201

M

 

Not Found 404

M

The account or balance does not exist.

Conflict Status Code 409

M

Used when the loyalty burn transaction ID already exists.

Unprocessable Entity Code 422

M

Used when the burn resource does not conform to field rules.

 

 

The following table indicates attributes that are required to be sent when burning loyalty as well as attributes with special considerations. All other attributes defining the resource are not required to be sent as part of the body of the POST request message:

 

Attribute name

Mandatory

Default

Rule

id

O

 

Accepted in entity-creation requests if the server supports the incoming identifier as the reference to create new resources

quantity

M

 

 

openingBalance

O

 

 


closingBalance

O

 

 

dateTime

O

 

 

description

O

 

 

 

 

The response from the server must include a body with the contents of the new resource created. The BODY of the response from the server must include attribute “href” set to the same value as the one in the Location header.


API  PATCH OPERATION CONFORMANCE

 

This section defines which attributes are patchable.

 

Since PATCH operation is optional and not included in the basic certification this is not applicable in this conformance document.


API  DELETE OPERATION CONFORMANCE

 

This section defines what operations can be used to delete a resource.

 

Since DELETE operation is optional and not included in the basic certification this is not applicable in this conformance document.


API  CONFORMANCE TEST SCENARIOS

 

This section describes the test scenarios required for the basic CONNECT certification of loyalty management API.

Test Cases must be executed in order because the result from one of the scenarios will be input for the next one.

Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/loyaltyManagement , being {serverRoot} defines the certification endpoint

 

  Loyalty Event Type resource TEST CASES

 

Nominal Scenarios

 

TC_EventType_N1 – Create a new event type

 

  • Send a POST message to {apiRoot}/loyaltyEventType with the following contents in the BODY

 

{

"eventType":"customerEnrollment"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyEventType/{IDEventType1} where {IDEventType1} indicates the identifier assigned by the server to the event type resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/loyaltyEventType/{IDEventType1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one event type resource with ID set to

{IDEventType1}, the same identifier as assigned by the server to the new resource created


-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDEventType1} matches the values set in the original request

 

 

 

TC_ EventType_N2 – Search for event type with event type name

 

  • Send a GET message to /{apiRoot}/loyaltyEventType?event_type= customerEnrollment

 

  • Wait for a response from the server with the following characteristics

-           Response Code 200-OK

 

-           The body of the response includes one event type

 

-           The body of the response for the resource with each identifier matches the values in the corresponding original request

 

 

 

  Loyalty Condition resource TEST CASES

 

Nominal Scenarios

 

TC_Condition_N1 – Create a condition

 

  • Send a POST message to {apiRoot}/loyaltyCondition with the following contents in the BODY

 

{

"attribute":"productCode", "operator":"=",

"value":"23323"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyCondition/{IDCondition1} where {IDCondition1} indicates the identifier assigned by the server to the event type resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request


  • Send a GET message to /{apiRoot}/loyaltyCondition/{IDCondition1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one condition resource with ID set to

{IDCondition1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDCondition1} matches the values set in the original request

 

  Loyalty Action resource TEST CASES

 

Nominal Scenarios

 

TC_Action_N1 – Create action

 

  • Send a POST message to {apiRoot}/loyaltyAction with the following contents in the BODY

 

{

"type": "LoyaltyEarn", "actionAttributes": {

"quantity": 50

},

"body": {}, "headers": {

"Authorization": "bearer adakdj3478578934"

},

"action": "POST", "endpoint":

"http://server:port/loyaltyManagement/loyaltyProgramMember/{memberId}/loyaltyBalance/{b alanceId}/loyaltyEarn"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyAction/{IDAction1} where {IDAction1} indicates the identifier assigned by the server to the event type resource

 

-           The response message includes all mandatory parameters


-           The body of the response matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/loyaltyAction/{IDAction1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one action resource with ID set to

{IDAction1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDAction1} matches the values set in the original request

 

  Loyalty Program Product Specification resource TEST CASES

 

Nominal Scenarios

 

TC_ProgramSpec_N1 – Create loyalty program specification

 

  • Send a POST message to {apiRoot}/loyaltyAction with the following contents in the BODY

 

{

"name":"UpComingProfessionalsProgram", "productNumber":"121"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1} where {IDloyaltyProgramProductSpec1} indicates the identifier assigned by the server to the program spec resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1}


  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one program specification resource with ID set to {IDloyaltyProgramProductSpec1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier

{IDLoyaltyProgramProductSpec1} matches the values set in the original request

 

  Loyalty Rule resource TEST CASES

 

Nominal Scenarios

 

TC_Rule_N1 – Create a rule for the loyalty program specification

 

  • Send a POST message to {apiRoot}/loyaltyAction with the following contents in the BODY (there are no required attributes)

{

 

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1} where { IDloyaltyRule1} indicates the identifier assigned by the server to the program spec resource

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1}/loyaltyRul e

 

  • Wait for a response from the server with the following characteristics

-           Response Code 200-OK

 

-           The body of the response includes one rule resource with ID set to

{IDloyaltyRule1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDloyaltyRule1} matches the values set in the original request

 

  Loyalty Rule Event Types resource TEST CASES

 

Nominal Scenarios

 

TC_RuleEventType_N1 – Link an event type to an existing rule.

 

  • Send a POST message to {apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyEventType with the following contents in the BODY:

 

{

"id": {IDEventType1}

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyEventType/

{IDEventType1}.

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1}/loyaltyRul e/{IDloyaltyRule1}/loyaltyEventType

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK


-           The body of the response includes an action resources, at least one being a resource with ID {IDEventType1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDEventType1} matches the values set in the original request

 

 

 

  Loyalty Rule Condition resource TEST CASES

 

Nominal Scenarios

 

TC_RuleCondition_N1 – Link a condition to an existing rule.

 

  • Send a POST message to {apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyCondition with the following contents in the BODY:

 

{

"id": {IDCondition1}

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyCondition/{ IDCondition1}

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1}/loyaltyRul e/{IDloyaltyRule1}/loyaltyCondition

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK


-           The body of the response includes an action resources, at least one being a resource with ID {IDCondition1}, the same identifier as assigned by the server to the new resource created.

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDCondition1} matches the values set in the original request

 

  Loyalty Rule Action resource TEST CASES

 

Nominal Scenarios

 

TC_RuleAction_N1 – Link an action to an existing rule.

 

  • Send a POST message to {apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyAction with the following contents in the BODY:

 

{

"id": {IDAction1}

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramProductSpec/{ID loyaltyProgramProductSpec1}/loyaltyRule/{IDloyaltyRule1}/loyaltyAction /{ IDAction1}.

 

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to

/{apiRoot}/loyaltyProgramProductSpec/{IDloyaltyProgramProductSpec1}/loyaltyRul e/{IDloyaltyRule1}/loyaltyAction

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes an action resources, at least one being a resource with ID set to {IDAction1}, the same identifier as assigned by the server to the new resource created


-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDAction1} matches the values set in the original request

 

  Loyalty Program Member resource TEST CASES

 

Nominal Scenarios

 

TC_Member_N1 – Create a new loyalty member

 

  • Send a POST message to {apiRoot}/loyaltyProgramMember with the following contents in the BODY (there are no required attributes)

{

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramMember/{IDMember1}

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/loyaltyProgramMember/{IDMember1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes includes the member details, containing { IDMember1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDMember1} matches the values set in the original request

 

  Loyalty Program Product resource TEST CASES

 

Nominal Scenarios

 

TC_Product_N1 – Create a new loyalty program product for a loyalty program member


  • Send a POST message to

{apiRoot}/loyaltyProgramMember/{IDMember1}/loyaltyProgramProduct with the following contents in the BODY:

 

{

"productSpecId": {IDloyaltyProgramProductSpec1}, "loyaltyAccount": {

"loyaltyBalance": { "quantity": {

"unit": "points"

}

}

}

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

/{apiRoot}/loyaltyProgramMember/{IDMember1}/loyaltyProgramProduct/{IDP roduct1}

-           The response message includes all mandatory parameters

 

-           The body of the response matches the values set in the original request

 

-           Send a GET message to

/{apiRoot}/loyaltyProgramMember/{IDMember1}/loyaltyProgramProduct

 

-           A loyaltyAccount was created and the ID is present in the response, e.g.

{IDAccount1}

 

-           A loyaltyBalance was created and the ID is present in the response, e.g.

{IDBalance1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes includes a product, containing

{IDProduct1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDProduct1} matches the values set in the original request


  Loyalty Event resource TEST CASES

 

Nominal Scenarios

 

TC_Event_N1 – Trigger a new loyalty event.

 

  • Send a POST message to {apiRoot}/loyaltyEvent with the following contents in the BODY:

 

{

"eventType": "CustomerOrder", "memberId": "43243243", "event": {

"CustomerOrder": { "orderId": "9654-343",

"productCode": "23323"

}

}

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           The response body will be the content of the Loyalty Action that was applied, if any.

 

 

 

  Loyalty Earn resource TEST CASES

 

Nominal Scenarios

 

TC_Earn_N1 – Earn loyalty on a member account balance.

 

  • Send a POST message to

{apiRoot}/loyaltyAccount/{IDAccount1}/loyaltyBalance/{IDBalance1}/loyaltyEarn with the following contents in the BODY:

 

{

"quantity": "344"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

{apiRoot}/loyaltyAccount/{IDAccount1}/loyaltyBalance/{IDBalance1}/loyaltyE arn/{IDEvent1}. The response message includes all mandatory parameters


-           The body of the response matches the values set in the original request

 

 

  Loyalty Burn resource TEST CASES

 

Nominal Scenarios

 

TC_Earn_N1 – Burn loyalty on a member account balance.

 

  • Send a POST message to

{apiRoot}/loyaltyAccount/{IDAccount1}/loyaltyBalance/{IDBalance1}/loyaltyBurn with the following contents in the BODY:

 

{

"quantity": "32"

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to

{apiRoot}/loyaltyAccount/{IDAccount1}/loyaltyBalance/{IDBalance1}/loyaltyB urn/{IDBurn1}. The response message includes all mandatory parameters.

 

-           The body of the response matches the values set in the original request

 

 

  Loyalty Execution Point resource TEST CASES

 

Nominal Scenarios

 

TC_ExecutionPoint_N1 – Get loyalty execution points.

 

  • Send a GET message to

{apiRoot}/loyaltyProgramMemeber/{IDMember1}/loyaltyProgramProduct/{IDProduct 1}/loyaltyExecutionPoint:

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response matches the loyalty action values that were applied during the loyalty event.