Cohort Configuration API

Create and manage customer cohorts with custom brand-specific discount configurations.

Overview

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

See the API Reference overview for details on obtaining your access token.

API Endpoints

1. Create Cohort

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

HTTP Method: POST

Endpoint: /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 Parameters:

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.

Success Response:

Status Code: 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.

HTTP Method: GET

Endpoint: /v1/partners/cohort-config

Request Parameters: None

Success Response:

Status Code: 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.

HTTP Method: GET

Endpoint: /v1/partners/cohort-config/{cohortName}

Path Parameters:

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

Success Response:

Status Code: 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.

HTTP Method: PUT

Endpoint: /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 Parameters:

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.

Success Response:

Status Code: 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.