API docs by Redocly

Cosmopoints (v1)

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.

Authentication

Please use the production base url for the endpoints in this section.

OAuth 2.0

Before starting to use the Cosmopoints APIs, you must authenticate yourself using the supplied Client ID and Client Secret.

Request Body schema: application/x-www-form-urlencoded
client_id
required
string

Unique ID of your app
You can find it in the developer section of the portal

client_secret
required
string

Secret key of your app
You can find it in the developer section of the portal

grant_type
required
string
Value: "client_credentials"

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_in": 600,
  • "token_type": "Bearer"
}

Authenticate Deprecated

Before starting to use the Cosmopoints APIs, you must authenticate yourself using the supplied Client ID and Client Secret.

  • This API uses Bearer token for authentication.
  • Every token is valid for 10 minutes.
  • That token must be provided in Authorization header. Please prepend your token with 'Bearer '.
Request Body schema: application/json
clientId
required
string

Unique ID of your app
You can find it in the developer section of the portal

clientSecret
required
string

Secret key of your app
You can find it in the developer section of the portal

Responses

Request samples

Content type
application/json
{
  • "clientId": "string",
  • "clientSecret": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "expiresIn": 600
}

Business Info

Please use the production base url for the endpoints in this section.

Get Profile

Retrieve information about your business profile with Cosmopoints.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "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"
}

Programs

Please make sure to use the appropriate base url (sandbox or production)

Get Programs

Retrieve a list of all your enabled partner programs along with the price per point in USD and in the program currency.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Program Fields

Retrieve the fields for a specific program.

Authorizations:
Bearer
path Parameters
programId
required
string

The program id of the desired partner.

Responses

Response samples

Content type
application/json
{
  • "destinationUserId": "string",
  • "destinationUserEmail": "string"
}

Validate Member

Validate if a user is a valid member of a specific program.

Authorizations:
Bearer
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "destinationUserId": "string",
  • "destinationUserEmail": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get Program Details

Retrieve details like brand name and logo for each program based on the program IDs you provide.

Authorizations:
Bearer
query Parameters
programId[]
required
Array of strings
Example: programId[]=EXAMPLE_PROGRAM

The Program Ids

Responses

Response samples

Content type
application/json
{
  • "EXAMPLE_PROGRAM": {
    }
}

Campaigns

Get All Campaigns

Retrieve all campaigns by programId or status.

Authorizations:
Bearer
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

Currencies

Please make sure to use the appropriate base url (sandbox or production)

Get Currencies

Returns the currencies available for issuing points (POINTS, USD, or your local currency).

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • "AED",
  • "USD",
  • "POINTS"
]

Transactions

Please make sure to use the appropriate base url (sandbox or production)

Issue Points - Preview

Preview the points with a specific partner. This endpoint will compute the value of points to be created with this partner

Authorizations:
Bearer
Request Body schema: application/json
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 USD or your local currency when sending a monetary amount.

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "value": 1.1,
  • "currency": "string"
}

Response samples

Content type
application/json
{
  • "totalPoints": 0
}

Issue Points

Issue points with a specific partner. This endpoint will create a new transaction record in the database.

Authorizations:
Bearer
Request Body schema: application/json
programId
required
string

The program id of the desired partner

value
required
float
  • If sending a monetary amount, provide the value in the chosen currency (USD or local currency).
  • If sending an amount of issued points, provide the number of points.
currency
required
string
  • Use USD or your local currency when sending a monetary amount.
  • Use POINTS when sending an amount of issued points.
required
object (DestinationAccount)

The destination user object. Mandatory and optional fields may vary per partner program. Please use the Get Program Fields endpoint to get the required fields for the desired partner program.

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)

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "value": 1.1,
  • "currency": "string",
  • "destinationAccount": {
    },
  • "referenceNumber": "string",
  • "description": "string",
  • "partnerCode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "totalPoints": 0,
  • "referenceNumber": "string",
  • "date": "string"
}

Get All Transactions

Retrieve all transactions in a specific interval.

Authorizations:
Bearer
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

Get Transaction

Get a single transaction record by Transaction ID or Reference Number.

Authorizations:
Bearer
path Parameters
transactionId
required
string

Either the transaction identifier issued by Cosmopoints, or the transaction reference number provided by the calling application

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "referenceNumber": "string",
  • "sourceValue": 0,
  • "description": "string",
  • "createdAt": "string",
  • "destinationUserId": "string",
  • "pointTransactions": [
    ],
  • "partnership": {
    }
}

Program Connections

Please make sure to use the appropriate base url (sandbox or production)

Get Program Connections

Retrieve program connections for a specific user id.

Authorizations:
Bearer
query Parameters
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)

Responses

Response samples

Content type
application/json
[ ]

Create or Update Program Connection

Create or update a program connection for a specific user id.

Authorizations:
Bearer
Request Body schema: application/json
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 Get Program Fields endpoint to get the required fields for the desired partner program.

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).

Responses

Request samples

Content type
application/json
{
  • "programId": "string",
  • "destinationAccount": {
    },
  • "sourceUserId": "string",
  • "sourceUserEmail": "string",
  • "partnerCode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceUserId": "string",
  • "sourceUserEmail": "string",
  • "programId": "string",
  • "partnerCode": "string",
  • "destinationUserId": "string",
  • "destinationUserEmail": "string",
  • "updatedAt": "string",
  • "createdAt": "string"
}

Get Program Connections History

Retrieve program connections history.

Authorizations:
Bearer
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

Delete Program Connection

Delete a program connection by id.

Authorizations:
Bearer
path Parameters
programConnectionId
required
string

The unique identifier of the program connection to be deleted.

Responses

Multibrand Connections

Please make sure to use the appropriate base url (sandbox or production)

Get Multibrand Connections

Retrieve multibrand connections for a specific user id.

Authorizations:
Bearer
query Parameters
sourceUserId
required
string

The user identifier with your organization - Identifier might be opaque

partnerCode
string

The partner code (for aggregator)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Multibrand Connections

Update multibrand connections for a specific user id. This is a batch operation.

Authorizations:
Bearer
Request Body schema: application/json
sourceUserId
required
string

The user identifier with your organization.

required
Array of objects

List of connections with percentage allocations.

partnerCode
string

The partner code (for aggregator).

Responses

Request samples

Content type
application/json
{
  • "sourceUserId": "string",
  • "connections": [
    ],
  • "partnerCode": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "sourceUserId": "string",
  • "connections": [
    ],
  • "updatedAt": "string",
  • "createdAt": "string"
}

Get Multibrand Connections History

Retrieve multibrand connections history.

Authorizations:
Bearer
query Parameters
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)

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "data": [
    ]
}

Delete Multibrand Connection

Delete a multibrand connection by id.

Authorizations:
Bearer
path Parameters
multibrandConnectionId
required
string

The unique identifier of the multibrand connection to be deleted.

Responses

Partner Codes

Get Partner Codes

Retrieve a list of the available partner codes.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • "EXAMPLE_PARTNER"
]