Corals Loyalty 🎁 Rewards API

Corals Loyalty 🎁 Rewards API Documentation

Overview and Purpose of the API

The Corals Loyalty 🎁 Rewards API is designed to manage and interact with the Corals Loyalty Rewards On-Premise System. This API enables businesses to manage loyalty program members, rewards, and transactions efficiently. It provides endpoints to create, retrieve, update, and list members, rewards, and transactions. The API is ideal for businesses looking to enhance customer engagement through loyalty programs by offering rewards and tracking transactions.

Authentication Requirements and Security Details

The API is secured using MuleSoft Client ID Enforcement Policy. This policy requires a valid client_id and client_secret to be included in the request headers for authentication.

Authentication Headers

Error Responses for Authentication

• 401 Unauthorized: Returned when invalid or missing credentials are provided.
  • Example Response:

    {
      "error": "Invalid Client"
    }

Base URL and Environments

Base URL

The API is hosted on the following base URL:
https://acme-managed-flex-gateway-9sqczt.ff5vu7.deu-c1.cloudhub.io/basepath2

Environment

• Production: The API is deployed in a production environment.

Detailed Endpoint Documentation

1. Members

GET /members

Retrieve a list of all members in the loyalty program.

• Query Parameters:| Parameter | Type | Description | Example Value ||-------------------|--------|-------------------------------------------------------------------------------------------------|----------------|| membershipLevel | string | Optional. Filters members by their membership level. Accepted values: Platinum Elite, Gold, Silver, Standard. | Gold |

• Response:

  • 200 OK: Returns an array of member objects.
    • Example:

      [
        {
          "id": "10001",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "joinDate": "2023-01-01",
          "points": 2200,
          "membershipLevel": "Platinum Elite"
        },
        {
          "id": "10013",
          "name": "Kyle Gray",
          "email": "kyle.gray@example.com",
          "joinDate": "2024-01-30",
          "points": 560,
          "membershipLevel": "Gold"
        }
      ]

  • 400 Bad Request: General error response.
  • 401 Unauthorized: Invalid client credentials.
  • 500 Internal Server Error: Server error.

POST /members

Create a new loyalty program member.

• Request Body:

  • Example:

    {
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "joinDate": "2023-02-01",
      "points": 1500,
      "membershipLevel": "Gold"
    }

• Response:

  • 201 Created: Member successfully created.
  • 400 Bad Request: General error response.
  • 401 Unauthorized: Invalid client credentials.

GET /members/{memberId}

Retrieve a specific member by their ID.

• Path Parameters:| Parameter | Type | Description | Example Value ||-------------|--------|---------------------------------|---------------|| memberId | string | The unique ID of the member. | 10001 |

• Response:

  • 200 OK: Returns the member object.
    • Example:

      {
        "id": "10001",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "joinDate": "2023-01-01",
        "points": 2200,
        "membershipLevel": "Platinum Elite"
      }

  • 404 Not Found: Member not found.
  • 401 Unauthorized: Invalid client credentials.

PUT /members/{memberId}

Update a specific member's information.

• Path Parameters:| Parameter | Type | Description | Example Value ||-------------|--------|---------------------------------|---------------|| memberId | string | The unique ID of the member. | 10001 |

• Request Body:

  • Example:

    {
      "name": "John Smith",
      "email": "john.smith@example.com",
      "points": 2500,
      "membershipLevel": "Gold"
    }

• Response:

  • 200 OK: Member successfully updated.
  • 404 Not Found: Member not found.
  • 401 Unauthorized: Invalid client credentials.

2. Rewards

GET /rewards

Retrieve a list of all available rewards.

• Response:
  • 200 OK: Returns an array of reward objects.
    • Example:

      [
        {
          "id": "r001",
          "name": "Free Night Stay",
          "description": "One free night stay at any of our resorts",
          "pointsRequired": 500
        },
        {
          "id": "r002",
          "name": "Spa Day",
          "description": "A relaxing day at the spa",
          "pointsRequired": 300
        }
      ]

  • 401 Unauthorized: Invalid client credentials.

POST /rewards

Create a new reward.

• Request Body:

  • Example:

    {
      "name": "Dinner for Two",
      "description": "A special dinner for two at our restaurant",
      "pointsRequired": 400
    }

• Response:

  • 201 Created: Reward successfully created.
  • 401 Unauthorized: Invalid client credentials.

GET /rewards/{rewardId}

Retrieve a specific reward by its ID.

• Path Parameters:| Parameter | Type | Description | Example Value ||-------------|--------|---------------------------------|---------------|| rewardId | string | The unique ID of the reward. | r001 |

• Response:

  • 200 OK: Returns the reward object.
    • Example:

      {
        "id": "r001",
        "name": "Free Night Stay",
        "description": "One free night stay at any of our resorts",
        "pointsRequired": 500
      }

  • 404 Not Found: Reward not found.
  • 401 Unauthorized: Invalid client credentials.

PUT /rewards/{rewardId}

Update a specific reward's information.

• Path Parameters:| Parameter | Type | Description | Example Value ||-------------|--------|---------------------------------|---------------|| rewardId | string | The unique ID of the reward. | r001 |

• Request Body:

  • Example:

    {
      "name": "Luxury Spa Day",
      "description": "A luxurious spa day experience",
      "pointsRequired": 600
    }

• Response:

  • 200 OK: Reward successfully updated.
  • 404 Not Found: Reward not found.
  • 401 Unauthorized: Invalid client credentials.

3. Transactions

GET /transactions

Retrieve a list of all transactions.

• Response:
  • 200 OK: Returns an array of transaction objects.
    • Example:

      [
        {
          "id": 1,
          "date": "2025-01-23T00:00:00",
          "type": "earn",
          "memberId": "10001",
          "points": 50
        },
        {
          "id": 2,
          "date": "2025-01-24T00:00:00",
          "type": "redeem",
          "memberId": "10002",
          "points": 20
        }
      ]

  • 401 Unauthorized: Invalid client credentials.

POST /transactions

Create a new transaction.

• Request Body:

  • Example:

    {
      "type": "earn",
      "memberId": "10001",
      "points": 100
    }

• Response:

  • 201 Created: Transaction successfully created.
    • Example:

      {
        "id": 178
      }

  • 401 Unauthorized: Invalid client credentials.

GET /transactions/{transactionId}

Retrieve a specific transaction by its ID.

• Path Parameters:| Parameter | Type | Description | Example Value ||------------------|---------|---------------------------------|---------------|| transactionId | integer | The unique ID of the transaction. | 1 |

• Response:

  • 200 OK: Returns the transaction object.
    • Example:

      {
        "id": 1,
        "date": "2025-01-23T00:00:00",
        "type": "earn",
        "memberId": "10001",
        "points": 50
      }

  • 404 Not Found: Transaction not found.
  • 401 Unauthorized: Invalid client credentials.

Error Handling and Status Codes

Best Practices for Implementation

1. Authentication: Always include valid client_id and client_secret in the headers.
2. Error Handling: Implement robust error handling to manage responses like 400, 401, and 500.
3. Data Validation: Validate input data before making API requests to avoid 400 Bad Request errors.
4. Pagination: For large datasets, consider implementing pagination for endpoints like /members and /transactions.

Sample Code Snippets

Example: Retrieve All Members

const axios = require('axios');

const getMembers = async () => {
  try {
    const response = await axios.get('https://acme-managed-flex-gateway-9sqczt.ff5vu7.deu-c1.cloudhub.io/basepath2/members', {
      headers: {
        client_id: '4740a2ab613d493cac320b223846c009',
        client_secret: '1110EA60D7bD40F48036DF3c8b70F1c6'
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error.response.data);
  }
};

getMembers();

Example: Create a New Reward

const axios = require('axios');

const createReward = async () => {
  try {
    const reward = {
      name: "Dinner for Two",
      description: "A special dinner for two at our restaurant",
      pointsRequired: 400
    };

    const response = await axios.post('https://acme-managed-flex-gateway-9sqczt.ff5vu7.deu-c1.cloudhub.io/basepath2/rewards', reward, {
      headers: {
        client_id: '4740a2ab613d493cac320b223846c009',
        client_secret: '1110EA60D7bD40F48036DF3c8b70F1c6'
      }
    });
    console.log('Reward created successfully');
  } catch (error) {
    console.error(error.response.data);
  }
};

createReward();

This concludes the documentation for the Corals Loyalty 🎁 Rewards API. For further assistance, please refer to the official API documentation or contact support.

API Endpoints

Members

Endpoints for managing loyalty program members.

Get a List of Members

• Endpoint: GET /members
• Description: Retrieves a list of all members in the loyalty program.
• Optional query parameter to restrict list by Membership Level
• Response:200 OK: Returns an array of Member objects.

Create a New Member

• Endpoint: POST /members
• Description: Adds a new member to the loyalty program.
• Request Body:Required: YesContent Type: application/json
• Schema: Member
• Response:201 Created: Returns the newly created Member object.

Get Member by ID

• Endpoint: GET /members/{memberId}
• Description: Retrieves details of a specific member by ID.
• Path Parameter: memberId (string) - Required.
• Response:200 OK: Returns the Member object.404 Not Found: Member with specified ID was not found.

Update Member Information

• Endpoint: PUT /members/{memberId}
• Description: Updates information for a specific member.
• Path Parameter: memberId (string) - Required.
• Request Body:Required: YesContent Type: application/json
• Schema: Member
• Response:200 OK: Returns the updated Member object.404 Not Found: Member with specified ID was not found.

Rewards

• Endpoints for managing rewards available in the loyalty program.
• Get a List of Rewards
• Endpoint: GET /rewards
• Description: Retrieves a list of all available rewards.
• Response:200 OK: Returns an array of Reward objects.

Create a New Reward

• Endpoint: POST /rewards
• Description: Adds a new reward to the loyalty program.
• Request Body:Required: YesContent Type: application/json
• Schema: Reward
• Response:201 Created: Returns the newly created Reward object.

Get Reward by ID

• Endpoint: GET /rewards/{rewardId}
• Description: Retrieves details of a specific reward by ID.
• Path Parameter: rewardId (integer) - Required.
• Response:200 OK: Returns the Reward object.404 Not Found: Reward with specified ID was not found.

Update Reward Information

• Endpoint: PUT /rewards/{rewardId}
• Description: Updates information for a specific reward.
• Path Parameter: rewardId (string) - Required.
• Request Body:Required: YesContent Type: application/json
• Schema: Reward
• Response:200 OK: Returns the updated Reward object.404 Not Found: Reward with specified ID was not found.

Transactions

Endpoints for managing member transactions in the loyalty program.

Get a List of Transactions

• Endpoint: GET /transactions
• Description: Retrieves a list of all transactions.
• Response:200 OK: Returns an array of Transaction objects.

Create a New Transaction

• Endpoint: POST /transactions
• Description: Adds a new transaction for a member, such as earning or redeeming points.
• Request Body:Required: YesContent Type: application/json
• Schema: Transaction
• Response:201 Created: Returns the newly created Transaction object.

Get Transaction by ID

• Endpoint: GET /transactions/{transactionId}
• Description: Retrieves details of a specific transaction by ID.
• Path Parameter: transactionId (string) - Required.
• Response:200 OK: Returns the Transaction object.404 Not Found: Transaction with specified ID was not found.