Loyalty Context Adapter

Overview

The Loyalty Context Adapter service provides a REST interface to store data related to loyalty members. This service enables adding a loyalty identity for a loyalty member along with loyalty-relevant activities in SAP Hybris Profile.

An activity score is calculated for the loyalty member based on loyalty-relevant activities such as order, redeem, rating, review in the recent past.

The Loyalty Context Adapter stores data in context/loyalty/loyaltymember and context/loyalty/loyaltyactivity schemas based on the following event types:

Details about these event types including example JSON structures are provided in the subsequent sections of this document.

The Loyalty Context Adapter service supports the application/json content type.

API Reference

/{tenant}/events

/{tenant}/events

post

Processes given event

Processes given event

URI Parameters

  • tenant: required (string)

Headers

  • consent-reference: required (string - pattern: ^[a-zA-Z0-9_-]*$)

    The identifier of the caller's consents. Single consent reference is some abstract identifier which is attached to the requests incoming the Profile. This identifier represents the consents which were voluntarily agreed by the user. It represents several different aspects of user interaction with storefront to be collected and upon which some conclusion can be issued to improve user's experience.

  • Authorization: required (string)

    Used to send a valid OAuth2 access token.

    Example:

    Bearer access_token

Body

Type: application/json

Example:

{
    "action_name": "MemberEvent",
    "eventType": "MEMBER_EVENT",
    "loyaltyMemberId": "3f2b688af5afd5beca63c45e13cd53a1",
    "emailId": "bruce.wayne@hybristest.com",
    "customerId": "C9753154",
    "balanceLoyaltyPoints": "10",
    "qualifyingLoyaltyPoints": "5",
    "tierId": "9c89e302b8e74e9db901645be7cfb90e",
    "tierName": "Gold",
    "tierOrder": "1",
    "tierStatus": "ACTIVE",
    "activityType": "REGISTRATION",
    "transactionPoints": "5",
    "activityTimeStamp": "2016-07-08 14:59:30.252",
    "tenant": "saployhfx",
    "referredBy": "4e046a0411433e10ad9ac14091379045"
}

HTTP status code 201

The request has been fulfilled and resulted in a new resource being created.

Headers

  • Location: (string)

    URI of created resource.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "title": "Resource Location",
    "description": "Schema for showing location of the new resource.",
    "properties": {
        "id": {
            "description": "The identifier of the created resource",
            "type": "string"
        },
        "link": {
            "description": "The link to the created resource",
            "type": "string",
            "format": "uri"
        }
    },
    "required": [
        "id",
        "link"
    ]
}

HTTP status code 401

Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 401,
    "message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
    "type": "insufficient_credentials",
    "moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}

HTTP status code 403

Evaluated request scopes in access token are not sufficient and do not match required scopes.

Body

Type: application/json

Schema:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "error",
    "description": "Schema for API specified errors.",
    "type": "object",
    "properties": {
        "status": {
            "type": "integer",
            "description": "original HTTP error code, should be consistent with the response HTTP code",
            "minimum": 100,
            "maximum": 599
        },
        "type": {
            "type": "string",
            "description": "classification of the error type, lower case with underscore eg validation_failure",
            "pattern": "[a-z]+[a-z_]*[a-z]+"
        },
        "message": {
            "type": "string",
            "description": "descriptive error message for debugging"
        },
        "moreInfo": {
            "type": "string",
            "format": "uri",
            "description": "link to documentation to investigate further and finding support"
        },
        "details": {
            "type": "array",
            "description": "list of problems causing this error",
            "items": {
                "$schema": "http://json-schema.org/draft-04/schema#",
                "title": "errorDetail",
                "description": "schema for specific error cause",
                "type": "object",
                "properties": {
                    "field": {
                        "type": "string",
                        "description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
                    },
                    "type": {
                        "type": "string",
                        "description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
                        "pattern": "[a-z]+[a-z_]*[a-z]+"
                    },
                    "message": {
                        "type": "string",
                        "description": "descriptive error detail message for debugging"
                    },
                    "moreInfo": {
                        "type": "string",
                        "format": "uri",
                        "description": "link to documentation to investigate further and finding support for error detail"
                    }
                },
                "required": [
                    "type"
                ]
            }
        }
    },
    "required": [
        "status",
        "type"
    ]
}

Example:

{
    "status": 403,
    "message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
    "type": "insufficient_permissions"
}

Scopes

Scopes are strings that allow you to specify the type of access you need to resources and operations in the Loyalty Context Adapter service.

You must provide a scope that allows users to perform operations. Grant the scopes in an access token from the OAuth2 service. For more information about the authorization and authentication used in SAP Hybris services, and also about the scopes in general, see:

- Authorization
- Scopes

The table shows all the scopes that the Loyalty Context Adapter service accepts:

ScopeDescription
sap.loyadapter_manageUse this scope to post data in the Loyalty Context Adapter.

Metamodel

This interactive graphic displays the schemas that invoke this enricher and the schemas the enricher can affect in the graph, as defined in a current snapshot of the metamodel.

Registration

This example shows the structure of the JSON that the Loyalty Context Adapter accepts to register a new member.


{
   "action_name":"MemberEvent",
   "eventType":"MEMBER_EVENT",
   "loyaltyMemberId":"3f2b688af5afd5beca63c45e13cd53a1",
   "emailId":"bruce.wayne@hybristest.com",
   "customerId":"C9753154",
   "balanceLoyaltyPoints":"10",
   "qualifyingLoyaltyPoints":"5",
   "tierId":"9c89e302b8e74e9db901645be7cfb90e",
   "tierName":"Gold",
   "tierOrder":"1",
   "tierStatus":"ACTIVE",
   "activityType":"REGISTRATION",
   "transactionPoints":"5",
   "activityTimeStamp":"2016-07-08 14:59:30.252",
   "tenant":"saployhfx",
   "referredBy":"4e046a0411433e10ad9ac14091379045"
}

Activity

This example shows the structure of the JSON that the Loyalty Context Adapter accepts for a new ORDER activity type.


{
   "action_name":"ActivityEvent",
   "eventType":"ACTIVITY_EVENT",
   "loyaltyMemberId":"3f2b688af5afd5beca63c45e13cd53a1",
   "emailId":"bruce.wayne@hybristest.com",
   "customerId":"C9753154",
   "balanceLoyaltyPoints":"10",
   "qualifyingLoyaltyPoints":"5",
   "tierId":"9c89e302b8e74e9db901645be7cfb90e",
   "activityType":"ORDER",
   "transactionPoints":"5",
   "activityTimeStamp":"2016-07-08 14:59:30.252",
   "tenant":"saployhfx"
}

Tier Details Update

This example shows the structure of the JSON that the the Loyalty Context Adapter accepts to update loyalty program Tier details.


{
   "action_name":"MemberEvent",
   "eventType":"TIER_EVENT",
   "tierId":"9c89e302b8e74e9db901645be7cfb90e",
   "tierName":"Gold",
   "tierOrder":"1",
   "tierStatus":"ACTIVE",
   "activityType":"TIER_DETAILS_UPDATE",
   "activityTimeStamp":"2016-07-08 14:59:30.252",
   "tenant":"saployhfx"
}

Glossary

TermDescription
Activity ScoreActivity scores are calculated for each loyalty member based on a formula that depends on the number of loyalty points accrued in the last six months. The formula for the activity score is `1.0*(Points from Month "N") + 0.8*(Points from Month "N-1") + 0.6*(Points from Month "N-2") + 0.4*(Points from Month "N-3") + 0.2*(Points from Month "N-4") + 0.1*(Points from Month "N-5")`, where `N` is the current month.
Context AdapterA microservice that receives data and, optionally, adapts it for entry into the graph. For example, a context adapter can adapt address data by adding a ZIP code and normalizing the street labels (for example, changing "St" to "Street"). The context adapter then passes the data through the Context service, which caches it so that enrichers can subsequently persist the data in the graph.
Loyalty IdentityA loyalty identity is comprised of member loyalty points, member tier, loyalty points history, activity score and activity scores history, which are stored in SAP Hybris Profile.
TierMerchants define loyalty tiers, which are levels that consumers can achieve in a loyalty program. Example tiers are Gold, Silver, and Bronze.

  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.