Offer Sumission API

Introduction

The Offer Submission API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

This API gives users the ability to submit new offers for approval and assign offers to customers.

This API uses the oAuth2 client credentials grant type to secure all the communications. For more information, check the Authentication/Authorization guide.

Use Cases

A faster and error-proof way of creating offers

Offers Submission API gives to the CRM Ops Team a process to create offers with an UI simplified and smart, to increase the speed of offer synchronisation across the landscape while reducing failure rates, so that end users ability and trust increases to fully leverage the full capabilities of offers.

Benefits

Focus on improving the experience of creating offers for CRM Ops Team, the benefits of this new platform and API includes:

• New digital experience for offers creators

  The CRM Ops Team should have a new digital experience when creation offers, with a simple and intuitive user interface, and preview options, for a real time demonstration of how the offer would look both on the website or the app in the mobile devices.

• Real time offer creation

  A new capability of real time offer creation will be added to enable creating and updating offers in real time, across all systems involved in creating, managing and publish new offers. These offers can take seconds to create!

• Reduce reengineering on offers creation process

  During the creation of the new platform for offers creation, users were engaged in the process, having the opportunity to give feedback to improve the process, examine ways of working to achieve a streamline and simple process, and creating awareness in all functionalities in offers creation process.

  It was also enabled the option to publish the offer to PROD from UAT, with appropriate approvals (reducing the need to recreate offers in PROD).

• Real time error feedback

  The new platform aims powering real time validation of the inserted values, previewing the offer during creation by simulating the different views and enabling end to end testing by assigning to test users in realtime, achieving minimum failure rates with near realtime error status report. The feedback provided to users enables editing failed offers rapidly, by letting them know what went wrong and how to fix the issues.

• Reduce time-to-live of offers to the client

  It was possible to create an ecosystem to synchronise the offers seamlessly across the landscape with minimum failure rate, since APIs creation could become the bedrock of automated processes, which increases the speed of creation of offers (eg. by reusing templates as base).

  Time to create and publish offers was reduce from 10 days to 30 minutes, in some cases.

• Increase clients trust on offers

  Creating offers without errors and within minimum time to create and publish, and enabling end to end offers testing will result in tailored offers, more aligned with clients needs, increasing the level of trust that clients are having in the offers presented.

  Marketing teams could react in-real-time to world changes, resulting in a well designed Offer Decision Engine and an improved match process between assigned offers to client according to each clients needs.

• Multi Language Approach

  Offer creators can now add details (eg. Offer title, description, messages, etc) in multiple languages based on the allowed languages of a market.

  To help Reporting and Analytics teams, english details can be passed along also too, for non-English markets.

Quick Start Guide for Offer Submission API

This API is secured by OAuth 2.0. It uses the 'Client Credentials' Grant Type to allow the API consumer to access data. The process is details with the diagram below.

Base URLs

Auth API

Offer Submission API

1. Request a Client ID and a Client Secret

To use the Offer Submission API, you first need to request a Client ID and a Client Secret using Shell ServiceNow service.

Select the SIMAAS - Self-Service Application Onboarding (Production/Non-Production). First, you need to ask for non-Production access. When asked about an Application CI, select RTL_MOB_MICRO_OFFERS_MGMT PBS00719857.

2. Generate and provide Client ID and Client Secret

They will generate the credentials and send you by email.

3. Request an Access Token

Once you received the client credentials, just make a POST request to /auth/v1/token endpoint.

Request body parameters

Sample Request

curl --location 'https://azmsauthqa.azurewebsites.net/auth/v1/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "grant_type": "client_credentials",
  "client_id": "***",
  "client_secret": "***"
}'

Response

On success, the response will have a 200 OK status and the following JSON data in the response body: | KEY | VALUE TYPE | VALUE DESCRIPTION | | --- | --- | --- | | expires_at | string | The number of seconds since the epoch when this token will expire. | | token | string | The access_token in JWT format. | | token_type | string | The type of the token: Bearer. |

Note: This endpoint doesn't return a refresh token. Hence in case the bearer token expires the same endpoint should be called again to retrieve a new bearer token.

Sample Response

{
  "expires_at": "1665767738",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer"
}

4. Initiate request to Offer Submission API with the Access Token from previous step

Every request you make to the Offer Submission API should include the Authorization header:

Header Parameters

Troubleshooting Authentication

The following table lists common authentication errors and potential causes:

Fundamentals

Requests

The Offer Submission API provides a set of endpoints, each with its unique path. It is based on REST principles. Data resources are accessed via standard HTTPS requests in UTF-8 format. List of verbs in Offer Submission API:

• POST - Performs an action.

Responses

The responses always include a JSON object. Check the API documentation to find descriptions of common responses for each endpoint.

Response Status Codes

The Offer Submission API uses the following response status codes defined in RFC 2616 and RFC 6585.

• 200 - The request has succeeded. The Partner application can read the result of the request in the body and the headers of the response.
• 400 - Bad request. Due to malformed syntax, the server could not understand the request. The body will contain more information.
• 401 - Unauthorized. The request requires user authentication, and it has been refused for those credentials.
• 403 - Forbidden. The server understood the request but is refusing to fulfill it.
• 404 - Not Found - The requested resource could not be found. This error can be due to a temporary or permanent condition.
• 422 - Unprocessable content. The server understood the request but is unable to process it.
• 500 - Internal Server Error. This error should not happen but if you receive it, something went wrong, please report it to us.

Response Error Schemas

All error scenarios are returned with the same response body structure:

{
  "error": {
    "Developer": {
      "appErrorCode": "string",
      "message": "string",
      "reason": "string"
    },
    "User": {
      "appErrorCode": "string",
      "message": "string",
      "reason": "string"
    }
  },
  "errorCode": 0,
  "message": "string"
}

Versioning

Your API version controls the API behavior you see (what properties you see in responses, what parameters you're allowed to send in requests, and so on). Your version is set in the URL. When a breaking change is introduced to the Offer Submission API, an updated version is released. The current version is v1. This is the only version available at this moment.

Backwards-compatible changes

We consider the following changes to be backward-compatible:

• Adding new API resources.
• Adding new optional request parameters to existing API endpoints.
• Adding new properties to existing API responses.
• Changing the order of properties in existing API responses.
• Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.

Security

The Offer Submission API forces HTTPS for all services using TLS (SSL).

The Offer Submission API uses IP Whitelisting to help prevent attacks against the API. Only trusted IP addresses will be able to submit requests to the API.

List endpoints and resource name

• Request an Access Token
• Retrieve information about the version and environment
• Create and submit an offer
• Assign an offer to a customer

Request an Access Token

This endpoint of the Auth API https://azmsauthqa.azurewebsites.net/auth/v1/token uses the HTTP POST method.

Request body parameters

Sample Request

curl --location 'https://azmsauthqa.azurewebsites.net/auth/v1/token' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "grant_type": "client_credentials",
  "client_id": "***",
  "client_secret": "***"
}'

When you request an Access Token, the Auth microservice will contact the Identity Provider System to get an Access Token using the client credentials provided. After getting one, the Auth microservice will ensure the user exists on our database and generate a new JWT token with the user roles, the email, and the UUID of the user. This will be returned to you alongside the token type and the expiration date of the Access Token.

Response

On success the response will have a 200 OK status and the body of the response will contain a simple JSON object with:

Sample Response

{
  "expires_at": "1665767738",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section. For this endpoint, this is the list of errors:

Retrieve information about the version and environment

This endpoint of the Offer Submission API https://offermanagementapis-qa.azurewebsites.net/api/v1/about uses the HTTP GET method.

Headers parameters

Sample Request

curl --location 'https://offermanagementapis-qa.azurewebsites.net/api/v1/about' \
--header 'Authorization: Bearer ***' \
--header 'countryCode: GB' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Response

On success the response will have a 200 OK status and the body of the response will contain a simple JSON object with the following fields:

Sample Response

{
    "version": "1.3.0-03bc15a6f29f8b4bfb55148c6d877e37ec5fe4f5",
    "environment": "qa"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section. For this endpoint, this is the list of errors:

Create and submit an offer

This endpoint of the Offer Submission API https://offermanagementapis-qa.azurewebsites.net/api/v1/offers/submit uses the HTTP POST method.

Headers parameters

Request body parameters

Availability of reward rule types by each offer type

Sample request

curl --location 'https://offermanagementapis-qa.azurewebsites.net/api/v1/offers/submit' \
--header 'Authorization: Bearer ***' \
--header 'countryCode: GB' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "acceptanceRequired": true,
  "accumulative": false,
  "assignableFrom": "2023-12-01",
  "assignableTo": "2023-12-02",
  "costOfReward": 12.25,
  "customText": [
    {
      "language": "en",
      "text": "Fill min 1L of any fuel and get 200 pts."
    }
  ],
  "deactivationAllowed": true,
  "displayOrder": 20,
  "expirationDays": 30,
  "expirationDaysAchievement": 30,
  "gameDetails": {
    "campaignOverviewImage": "82dc5ab1-1ceb-5cfe-b100-8cdfa4b306a6",
    "gameDescription": [
      {
        "language": "en",
        "text": "Play every day and get 200 points."
      }
    ],
    "gameIcon": "1234567890",
    "gameTANDCURL": "http://www.example.com/terms",
    "gameType": "Luck Game",
    "gameURL": "http://www.example.com",
    "inviteDurationDays": 100,
    "prizeDescription": [
      {
        "language": "en",
        "text": "This a prize description."
      }
    ]
  },
  "initiallyActive": true,
  "isDefault": false,
  "numberOfAssign": 3,
  "numberOfUsage": 0,
  "offerAchievementRule": [
    {
      "achievementRuleType": "PRODUCT_PURCHASE",
      "excludeProducts": [
        "CG0000000163"
      ],
      "includeProducts": [
        "CG0000000123"
      ],
      "label": "Rule 1",
      "progressIncrement": 100,
      "requiredQuantity": 50,
      "requiredTransactions": 10
    }
  ],
  "offerBackground": "82dc5ab1-1ceb-5cfe-b100-8cdfa4b306a6",
  "offerCode": "1234567890",
  "offerDescription": [
    {
      "language": "en",
      "text": "Fill min 1L of any fuel and get 200 pts."
    }
  ],
  "offerName": "New offer",
  "offerReceiptMessage": [
    {
      "language": "en",
      "text": "Fill min 1L of any fuel and get 200 pts"
    }
  ],
  "offerResetDay": 12,
  "offerRewardConditionRule": [
    {
      "conditionRuleType": "SPENT_AMOUNT",
      "productCode": "CG0000000163",
      "requiredValue": 12.5
    }
  ],
  "offerRewardRule": {
    "productCode": "CG0000000163",
    "rewardIncrement": 1000,
    "rewardLimit": 1000.5,
    "rewardValue": 100.5,
    "rounding": "UP",
    "ruleType": "FREE_PRODUCT"
  },
  "offerSubType": "GIVEAWAY",
  "offerTitle": [
    {
      "language": "en",
      "text": "10% discount on Shell Helix"
    }
  ],
  "offerType": "BASIC_MASS",
  "partialRewardOffer": false,
  "partnerCode": "RAC",
  "partnerFundingPercentage": 12.5,
  "partnerPointsValue": 10.5,
  "qualifyingVisitTarget": 10,
  "replacedOfferCode": 100,
  "requiredStamp": 10,
  "retailSite": "82dc5ab1-1ceb-5cfe-b100-8cdfa4b306a6",
  "rewardEngineExcluded": true,
  "validityLimitation": "Every Friday",
  "validityStartOffset": 15,
  "visibleFrom": "2023-12-01"
}'

After creating the offer, the offer will be sent to LOD. When LOD has processed it, the offer will be sent to Adobe.

Response

On success the response will have a 201 Created status and the body of the response will contain a simple JSON object with:

Sample Response

{
  "offerCode": "test",
  "offerId": 12,
  "status": "Draft"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section. For this endpoint, this is the list of possible errors:

Assign an offer to a customer

This endpoint of the Offer Submission API https://offermanagementapis-qa.azurewebsites.net/api/v1/offers/{offerId}/assign uses the HTTP POST method.

Headers parameters

Path parameters

Request body parameters

Sample Request

curl --location 'https://offermanagementapis-qa.azurewebsites.net/api/v1/offers/123/assign' \
--header 'Authorization: Bearer ***' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "consumerUUID": "942a1fb4-d487-454c-9c1c-aee920c420fb",
  "validFrom": "2023-08-24T14:15:22Z",
  "validTo": "2023-12-24T14:15:22Z",
  "validityPeriod": 31
}'

Response

On success the response will have a 200 OK status and the body of the response will contain a simple JSON object with:

Sample Response

{
  "consumerUUID": "01bbf258-04f1-4ffc-be07-09a5ad5849de",
  "description": "",
  "offerID": 123,
  "referenceID": "85f09c39-8a5b-4f22-9a1e-d89656e6017c",
  "responseCode": 200,
  "title": "Offer",
  "validFrom": "2019-08-24T14:15:22Z",
  "validTo": "2019-08-24T14:15:22Z"
}

Exception Handling

The format of errors is always the same and specified in the Fundamentals section. For this endpoint, this is the list of errors: