Download OpenAPI specification:
Welcome to the Cosmopoints API documentation. The service simplifies transactions with loyalty programs by aggregating different APIs into a single, consistent interface.
Before starting to use the Cosmopoints APIs, you must authenticate yourself using the supplied Client ID and Client Secret.
| client_id required | string Unique ID of your app |
| client_secret required | string Secret key of your app |
| grant_type required | string Value: "client_credentials" |
{- "access_token": "string",
- "expires_in": 600,
- "token_type": "Bearer"
}Before starting to use the Cosmopoints APIs, you must authenticate yourself using the supplied Client ID and Client Secret.
| clientId required | string Unique ID of your app |
| clientSecret required | string Secret key of your app |
{- "clientId": "string",
- "clientSecret": "string"
}{- "accessToken": "string",
- "expiresIn": 600
}Retrieve information about your business profile with Cosmopoints.
{- "name": "string",
- "programId": "string",
- "programName": "string",
- "legalEntity": "string",
- "logo": "string",
- "industry": "string",
- "country": "string",
- "address": "string",
- "city": "string",
- "zipCode": "string",
- "localCurrency": "string",
- "technicalContact": "string",
- "technicalContactEmail": "user@example.com",
- "billingContact": "string",
- "billingContactEmail": "user@example.com",
- "countryCode": "string",
- "phone": "string"
}Retrieve a list of all your enabled partner programs along with the price per point in USD and in the program currency.
[- {
- "id": "string",
- "name": "string",
- "businessName": "string",
- "logo": "string",
- "industry": "string",
- "termsAndConditionsUrl": "string",
- "brandDescription": "string",
- "programCurrency": "string",
- "pricePerPointInUsd": "string",
- "pricePerPointInLocalCurrency": "string",
- "pricePerPoint": "string",
- "minAmountOfPoints": 0,
- "maxAmountOfPoints": 0,
- "minValue": 0,
- "maxValue": 0,
- "localCurrency": "string",
- "currency": "string",
- "requiredFields": {
- "destinationUserId": "string",
- "destinationUserEmail": "string"
}
}
]Validate if a user is a valid member of a specific program.
| destinationUserId | string This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required |
| destinationUserEmail | string This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required |
{- "destinationUserId": "string",
- "destinationUserEmail": "string"
}{- "data": {
- "isValid": true
}
}Retrieve details like brand name and logo for each program based on the program IDs you provide.
| programId[] required | Array of strings Example: programId[]=EXAMPLE_PROGRAM The Program Ids |
{- "EXAMPLE_PROGRAM": {
- "businessName": "string",
- "programId": "string",
- "programName": "string",
- "logo": "string",
- "programCurrency": "string",
- "brandDescription": "string",
- "termsConditionsUrl": "string"
}
}Retrieve all campaigns by programId or status.
| programId | string The program id of the desired partner |
| status | string Enum: "IDLE" "RUNNING" "STOPPED" "EXPIRED" The status of the campaign |
| page | number The number of the page to retrieve |
| pageSize | number The number of items per page (default 25, max 5000) |
{- "total": 0,
- "data": [
- {
- "id": "string",
- "name": "string",
- "yourCostSharePercentage": 0,
- "extraPointsPercentage": 0,
- "startDate": "string",
- "endDate": "string",
- "status": "string",
- "type": "CO-FUNDED",
- "programId": "string"
}
]
}Preview the points with a specific partner. This endpoint will compute the value of points to be created with this partner
| programId required | string The program id of the desired partner |
| value required | float Provide the value in the chosen currency (USD or local currency). |
| currency required | string Use |
{- "programId": "string",
- "value": 1.1,
- "currency": "string"
}{- "totalPoints": 0
}Issue points with a specific partner. This endpoint will create a new transaction record in the database.
| programId required | string The program id of the desired partner |
| value required | float
|
| currency required | string
|
required | object (DestinationAccount) The destination user object. Mandatory and optional fields may vary per partner program. Please use the |
| referenceNumber required | string The transaction reference number provided by the calling application |
| description | string Short description to attach to the transaction |
| partnerCode | string The partner code (required for aggregator) |
{- "programId": "string",
- "value": 1.1,
- "currency": "string",
- "destinationAccount": {
- "destinationUserId": "string",
- "destinationUserEmail": "user@example.com"
}, - "referenceNumber": "string",
- "description": "string",
- "partnerCode": "string"
}{- "id": "string",
- "totalPoints": 0,
- "referenceNumber": "string",
- "date": "string"
}Retrieve all transactions in a specific interval.
| startDate required | string Any valid date representation |
| endDate required | string Any valid date representation |
| programId | string The program id of the desired partner |
| page | number The number of the page to retrieve |
| pageSize | number The number of items per page (default 25, max 5000) |
{- "total": 0,
- "data": [
- {
- "id": "string",
- "referenceNumber": "string",
- "sourceValue": 0,
- "description": "string",
- "createdAt": "string",
- "pointTransactions": [
- {
- "destinationNumberOfPoints": "string",
- "type": "string"
}
], - "partnership": {
- "name": "string",
- "programId": "string"
}
}
]
}Get a single transaction record by Transaction ID or Reference Number.
| transactionId required | string Either the transaction identifier issued by Cosmopoints, or the transaction reference number provided by the calling application |
{- "id": "string",
- "referenceNumber": "string",
- "sourceValue": 0,
- "description": "string",
- "createdAt": "string",
- "destinationUserId": "string",
- "pointTransactions": [
- {
- "destinationNumberOfPoints": "string",
- "type": "string"
}
], - "partnership": {
- "destination": {
- "name": "string",
- "programId": "string"
}
}
}Retrieve program connections for a specific user id.
| sourceUserId required | string The user identifier with your organization - Identifier might be opaque |
| programId | string The program id of the desired partner |
| partnerCode | string The partner code (for aggregator) |
[ ]Create or update a program connection for a specific user id.
| programId required | string The program id of the desired partner. |
required | object (DestinationAccount) The destination user object. Mandatory and optional fields may vary per partner program. Please use the |
| sourceUserId required | string The user identifier with your organization. |
| sourceUserEmail | string The user email with your organization. |
| partnerCode | string The partner code (required for aggregator). |
{- "programId": "string",
- "destinationAccount": {
- "destinationUserId": "string",
- "destinationUserEmail": "user@example.com"
}, - "sourceUserId": "string",
- "sourceUserEmail": "string",
- "partnerCode": "string"
}{- "id": "string",
- "sourceUserId": "string",
- "sourceUserEmail": "string",
- "programId": "string",
- "partnerCode": "string",
- "destinationUserId": "string",
- "destinationUserEmail": "string",
- "updatedAt": "string",
- "createdAt": "string"
}Retrieve program connections history.
| startDate | string Any valid date representation |
| endDate | string Any valid date representation |
| page | number The number of the page to retrieve |
| pageSize | number The number of items per page (default 25, max 5000) |
| partnerCode | string The partner code (for aggregator) |
{- "total": 0,
- "data": [
- {
- "id": "string",
- "event": "string",
- "programId": "string",
- "sourceProgramUser": {
- "sourceUserEmail": "string",
- "sourceUserId": "string"
}, - "destinationUserEmail": "string",
- "destinationUserId": "string",
- "timestamp": "string"
}
]
}Retrieve a list of all your enabled partner programs along with the price per point in USD and in the program currency.
[- {
- "id": "string",
- "name": "string",
- "businessName": "string",
- "logo": "string",
- "industry": "string",
- "termsAndConditionsUrl": "string",
- "brandDescription": "string",
- "programCurrency": "string",
- "pricePerPointInUsd": "string",
- "pricePerPointInLocalCurrency": "string",
- "localCurrency": "string",
- "requiredFields": {
- "destinationUserId": "string",
- "destinationUserEmail": "string"
}
}
]Validate if a user is a valid member of a specific program.
| destinationUserId | string This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required |
| destinationUserEmail | string This field may be optional or mandatory depending on the partner program. Please use the Get Program Fields endpoint to check if it is required |
{- "destinationUserId": "string",
- "destinationUserEmail": "string"
}{- "data": {
- "isValid": true
}
}Credit points to a specific user. The point distribution will be provided using the program connections endpoint.
| userId required | string The user id of your organization |
| value required | float The value in the chosen currency (USD or local currency). |
| currency required | string Use |
| executionDate required | string The execution date of the transaction |
{- "userId": "string",
- "value": 1.1,
- "currency": "string",
- "executionDate": "string"
}{- "sourceUserId": "string",
- "sourceProgramId": "string",
- "valueInSourceLocalCurrency": "string",
- "valueInUsd": "string",
- "localCurrency": "string",
- "status": "PENDING",
- "createdAt": "string",
- "executionDate": "string"
}Retrieve all executed transactions in a specific interval.
| startDate | string Any valid date representation |
| endDate | string Any valid date representation |
| programId | string The program id of the desired partner |
| page | number The number of the page to retrieve |
| pageSize | number The number of items per page (default 25, max 5000) |
{- "total": 0,
- "data": [
- {
- "id": "string",
- "valueInSourceLocalCurrency": 0,
- "createdAt": "string",
- "pointTransactions": [
- {
- "numberOfPoints": "string",
- "type": "string"
}
], - "partnership": {
- "destinationProgramId": "string"
}
}
]
}Debit points from a specific user. The point distribution will be provided using the program connections endpoint.
| userId required | string The user id of your organization |
| value required | float The value in the chosen currency (USD or local currency). |
| currency required | string Use |
{- "userId": "string",
- "value": 1.1,
- "currency": "string"
}{- "sourceUserId": "string",
- "sourceProgramId": "string",
- "valueInSourceLocalCurrency": "string",
- "valueInUsd": "string",
- "localCurrency": "string",
- "status": "EXECUTED",
- "createdAt": "string",
- "executionDate": "string"
}Retrieve estimated balance in currencies.
| userId required | string Your organization's user id |
| status required | string Enum: "PENDING" "MATURED" |
{- "estimatedValueInUsd": "string",
- "estimatedValueInSourceLocalCurrency": "string"
}Retrieve program connections for a specific user id.
| sourceUserId required | string The user identifier with your organization - Identifier might be opaque |
[- {
- "id": "string",
- "destinationUserId": "string",
- "destinationUserEmail": "string",
- "percentage": 0,
- "destinationProgramId": "string",
- "updatedAt": "string",
- "createdAt": "string"
}
]Update program connections for a specific user id. This is a batch operation.
| sourceUserId required | string The user identifier with your organization. |
required | Array of objects List of connections with percentage allocations. |
{- "sourceUserId": "string",
- "connections": [
- {
- "percentage": 0,
- "destinationProgramId": "string",
- "destinationAccount": {
- "destinationUserId": "string",
- "destinationUserEmail": "user@example.com"
}
}
]
}[- {
- "id": "string",
- "destinationUserId": "string",
- "destinationUserEmail": "string",
- "percentage": 0,
- "destinationProgramId": "string",
- "updatedAt": "string",
- "createdAt": "string"
}
]Retrieve program connections history.
| startDate | string Any valid date representation |
| endDate | string Any valid date representation |
| page | number The number of the page to retrieve |
| pageSize | number The number of items per page (default 25, max 5000) |
{- "total": 0,
- "data": [
- {
- "id": "string",
- "event": "string",
- "destinationProgramId": "string",
- "timestamp": "string",
- "sourceProgramUser": {
- "sourceUserId": "string"
}, - "destinationUserId": "string",
- "destinationUserEmail": "string"
}
]
}