Cohort Configuration API

The Cohort Configuration API enables you to create and manage customer cohorts with custom brand-specific discount configurations. This API provides full control over discount percentages for different brands within your cohorts, allowing you to tailor pricing strategies for different customer segments.

Base URLs

Environment	Base URL
Staging	`https://api.dev.myhubble.money`
Production	`https://api.myhubble.money`

All endpoints are prefixed with /v1/partners/cohort-config

Authentication

All API requests require authentication using a Bearer token obtained from the login API.

Required Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Endpoints

1. Create Cohort

Create a new customer cohort with brand-specific discount configurations.

POST/v1/partners/cohort-config

Request Body:

{
  "cohortName": "premium-customers",
  "brandDiscounts": [
    {
      "brandKey": "amazon",
      "discountPercentage": 5.0
    },
    {
      "brandKey": "flipkart",
      "discountPercentage": 3.5
    },
    {
      "brandKey": "swiggy",
      "discountPercentage": 4.0
    }
  ]
}

Request Fields:

Field	Type	Required	Description
`cohortName`	string	Yes	Unique identifier for the cohort. Must not already exist.
`brandDiscounts`	array	Yes	List of brand discount configurations.
`brandDiscounts[].brandKey`	string	Yes	Brand identifier (e.g., "amazon", "flipkart"). Must be a valid brand available to your account.
`brandDiscounts[].discountPercentage`	number	Yes	Discount percentage for this brand. Must correspond to an available discount tier.

Response (200 OK):

{
  "cohortName": "premium-customers",
  "brandDiscounts": [
    {
      "brandKey": "amazon",
      "discountPercentage": 5.0
    },
    {
      "brandKey": "flipkart",
      "discountPercentage": 3.5
    },
    {
      "brandKey": "swiggy",
      "discountPercentage": 4.0
    }
  ]
}

Example Request:

curl -X POST 'https://api.myhubble.money/v1/partners/cohort-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "cohortName": "premium-customers",
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 5.0
      },
      {
        "brandKey": "flipkart",
        "discountPercentage": 3.5
      }
    ]
  }'

2. Get All Cohorts

Retrieve all cohorts configured for your account.

GET/v1/partners/cohort-config

Response (200 OK):

[
  {
    "cohortName": "premium-customers",
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 5.0
      },
      {
        "brandKey": "flipkart",
        "discountPercentage": 3.5
      }
    ]
  },
  {
    "cohortName": "standard-customers",
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 3.0
      },
      {
        "brandKey": "myntra",
        "discountPercentage": 2.5
      }
    ]
  }
]

Example Request:

curl -X GET 'https://api.myhubble.money/v1/partners/cohort-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

3. Get Single Cohort

Retrieve a specific cohort by its name.

GET/v1/partners/cohort-config/{cohortName}

Path Parameters:

Parameter	Type	Required	Description
`cohortName`	string	Yes	Name of the cohort to retrieve

Response (200 OK):

{
  "cohortName": "premium-customers",
  "brandDiscounts": [
    {
      "brandKey": "amazon",
      "discountPercentage": 5.0
    },
    {
      "brandKey": "flipkart",
      "discountPercentage": 3.5
    }
  ]
}

Example Request:

curl -X GET 'https://api.myhubble.money/v1/partners/cohort-config/premium-customers' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

4. Update Cohort

Update an existing cohort's brand discount configuration.

Important

This operation performs a full replacement of all brand discounts. Any brands not included in the update request will be removed from the cohort.

PUT/v1/partners/cohort-config/{cohortName}

Path Parameters:

Parameter	Type	Required	Description
`cohortName`	string	Yes	Name of the cohort to update

Request Body:

{
  "brandDiscounts": [
    {
      "brandKey": "amazon",
      "discountPercentage": 7.0
    },
    {
      "brandKey": "ajio",
      "discountPercentage": 4.0
    }
  ]
}

Request Fields:

Field	Type	Required	Description
`brandDiscounts`	array	Yes	Complete list of brand discount configurations. This replaces all existing brand discounts.
`brandDiscounts[].brandKey`	string	Yes	Brand identifier. Must be a valid brand available to your account.
`brandDiscounts[].discountPercentage`	number	Yes	Discount percentage for this brand. Must correspond to an available discount tier.

Response (200 OK):

{
  "cohortName": "premium-customers",
  "brandDiscounts": [
    {
      "brandKey": "amazon",
      "discountPercentage": 7.0
    },
    {
      "brandKey": "ajio",
      "discountPercentage": 4.0
    }
  ]
}

Example Request:

curl -X PUT 'https://api.myhubble.money/v1/partners/cohort-config/premium-customers' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 7.0
      },
      {
        "brandKey": "ajio",
        "discountPercentage": 4.0
      }
    ]
  }'

Important Notes

Discount Percentages

Discount percentages must correspond to available discount tiers in the Hubble system
The system validates that the specified discount percentage maps to an existing tier (e.g., 5.0% maps to "DISCOUNT_5_PERC")
Contact your Hubble integration team for a list of available discount tiers

Brand Keys

Brand keys must be valid brand identifiers available to your client account
Only brands that are active in your account configuration can be used
Contact your Hubble integration team for a list of available brand keys

Update Behavior

The PUT endpoint performs a complete replacement of brand discounts
If you have 5 brands configured and send an update with only 2 brands, the other 3 will be removed
To add a brand without removing existing ones, include all existing brands plus the new one in your update request

Common Use Cases

Use Case 1: Creating a VIP Customer Cohort

Create a cohort for VIP customers with higher discounts across premium brands:

curl -X POST 'https://api.myhubble.money/v1/partners/cohort-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "cohortName": "vip-customers",
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 7.0
      },
      {
        "brandKey": "flipkart",
        "discountPercentage": 6.5
      },
      {
        "brandKey": "myntra",
        "discountPercentage": 6.0
      }
    ]
  }'

Use Case 2: Adjusting Discounts for a Promotion

Update an existing cohort to increase discounts during a promotional period:

curl -X PUT 'https://api.myhubble.money/v1/partners/cohort-config/standard-customers' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "brandDiscounts": [
      {
        "brandKey": "amazon",
        "discountPercentage": 5.0
      },
      {
        "brandKey": "swiggy",
        "discountPercentage": 4.5
      }
    ]
  }'

Use Case 3: Auditing Current Configurations

Retrieve all cohorts to audit your current discount configurations:

curl -X GET 'https://api.myhubble.money/v1/partners/cohort-config' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Troubleshooting

Error: "Cohort with name 'X' already exists"

Problem: You're trying to create a cohort with a name that already exists.

Solution: Use the GET endpoint to check existing cohorts, or use the PUT endpoint to update the existing cohort instead.

Error: "The following brand keys were not found: [...]"

Problem: One or more brand keys in your request are invalid or not available to your account.

Solution: Verify the brand keys with your Hubble integration team and ensure you're using the correct identifiers.

Error: "The following discount tiers were not found: [...]"

Problem: The discount percentage you specified doesn't map to an available discount tier.

Solution: Contact your Hubble integration team for the list of valid discount percentages/tiers available in your environment.

Error: "Client X does not have permission to update cohort 'Y'"

Problem: You're trying to update a cohort that doesn't belong to your client account.

Solution: Verify the cohort name and ensure it belongs to your account using the GET endpoint.

Base URLs​

Authentication​

Endpoints​

1. Create Cohort​

2. Get All Cohorts​

3. Get Single Cohort​

4. Update Cohort​

Important Notes​

Discount Percentages​

Brand Keys​

Update Behavior​

Common Use Cases​

Use Case 1: Creating a VIP Customer Cohort​

Use Case 2: Adjusting Discounts for a Promotion​

Use Case 3: Auditing Current Configurations​

Troubleshooting​

Error: "Cohort with name 'X' already exists"​

Error: "The following brand keys were not found: [...]"​

Error: "The following discount tiers were not found: [...]"​

Error: "Client X does not have permission to update cohort 'Y'"​

Base URLs

Authentication

Endpoints

1. Create Cohort

2. Get All Cohorts

3. Get Single Cohort

4. Update Cohort

Important Notes

Discount Percentages

Brand Keys

Update Behavior

Common Use Cases

Use Case 1: Creating a VIP Customer Cohort

Use Case 2: Adjusting Discounts for a Promotion

Use Case 3: Auditing Current Configurations

Troubleshooting

Error: "Cohort with name 'X' already exists"

Error: "The following brand keys were not found: [...]"

Error: "The following discount tiers were not found: [...]"

Error: "Client X does not have permission to update cohort 'Y'"