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 Schema: application/json

access_token	string Access token for subsequent API calls.
expires_in	number Token expiry in seconds.
token_type	string Type of the token.

Response samples

200
400
401

Content type

application/json

{"access_token": "string",
"expires_in": 600,
"token_type": "Bearer"
}

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 Schema: application/json

name	string Name of your business.
programId	string Unique identifier of your business program.
programName	string The business program name.
legalEntity	string Legal entity name of the business.
logo	string URL of the business logo/photo.
logoDarkMode	string URL of the business logo/photo for dark mode.
industry	string Industry name.
country	string Country of the business.
address	string Address of the business.
city	string City of the business.
zipCode	string Postal code / zip code.
localCurrency	string Program currency short code.
technicalContact	string Technical contact person or team.
technicalContactEmail	string <email> Email for technical contact.
billingContact	string Billing contact person or team.
billingContactEmail	string <email> Email for billing contact.
countryCode	string Country calling code.
phone	string Contact phone number.

Response samples

200

Content type

application/json

{"name": "string",
"programId": "string",
"programName": "string",
"legalEntity": "string",
"logo": "string",
"logoDarkMode": "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 Schema: application/json

Array

id

string

Unique identifier of the program.

name

string

Name of the program.

businessName

string

Name of the business associated with the program.

logo

string

URL of the program logo.

logoDarkMode

string

URL of the program logo for dark mode.

industry

string

Industry of the program.

termsAndConditionsUrl

string

URL to the terms and conditions of the program.

brandDescription

string

Description of the brand associated with the program.

programCurrency

string

Custom currency code of the program.

pricePerPointInUsd

string <double>

Price per point in USD.

pricePerPointInLocalCurrency

string <double>

Price per point in your organization's currency.

minAmountOfPoints

number

Deprecated

Deprecated: use partnerMinAllowedPoints. Minimum amount of points that can be issued.

maxAmountOfPoints

number

Deprecated

Deprecated: use partnerMaxAllowedPoints. Maximum amount of points that can be issued.

minValue

number

Deprecated

Deprecated: use minAllowedPoints. Minimum value to issue points.

maxValue

number

Deprecated

Deprecated: use maxAllowedPoints. Maximum value to issue points.

partnerMinAllowedPoints

number

Minimum amount of destination points that can be issued, set by the partner.

partnerMaxAllowedPoints

number

Maximum amount of destination points that can be issued, set by the partner.

minAllowedPoints

number

Minimum amount of destination points that can be issued, set by you.

maxAllowedPoints

number

Maximum amount of destination points that can be issued, set by you.

localCurrency

string

Currency code of your organization.

partnerCode

string

The partner code.

object

destinationUserId	string The ID of the destination user.
destinationUserEmail	string The email of the destination user.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.

Response samples

200

Content type

application/json

[{"id": "string",
"name": "string",
"businessName": "string",
"logo": "string",
"logoDarkMode": "string",
"industry": "string",
"termsAndConditionsUrl": "string",
"brandDescription": "string",
"programCurrency": "string",
"pricePerPointInUsd": "string",
"pricePerPointInLocalCurrency": "string",
"minAmountOfPoints": 0,
"maxAmountOfPoints": 0,
"minValue": 0,
"maxValue": 0,
"partnerMinAllowedPoints": 0,
"partnerMaxAllowedPoints": 0,
"minAllowedPoints": 0,
"maxAllowedPoints": 0,
"localCurrency": "string",
"partnerCode": "string",
"requiredFields": {"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "string"
}
}
]

Get Program Fields Deprecated

Retrieve the fields for a specific program.

Authorizations:

Bearer

path Parameters

programId

required

string

The program id of the desired partner.

Responses

Response Schema: application/json

destinationUserId	string The ID of the destination user.
destinationUserEmail	string The email of the destination user.

Response samples

200

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

Response Schema: application/json

object

isValid

boolean

The member validation result. For partners without a member validation API endpoint, this indicates whether the submitted details satisfy the partner's validation rules; it does not confirm membership existence or eligibility to receive points. See Partner Validation Support and Rules for each partner's validation availability and applicable rules.

Request samples

Payload

Content type

application/json

{"destinationUserId": "string",
"destinationUserEmail": "string"
}

Response samples

200

Content type

application/json

{"data": {"isValid": true
}
}

Get Program Details Deprecated

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 Schema: application/json

object

Response samples

200

Content type

application/json

{"EXAMPLE_PROGRAM": {"businessName": "string",
"programId": "string",
"programName": "string",
"logo": "string",
"logoDarkMode": "string",
"programCurrency": "string",
"brandDescription": "string",
"termsConditionsUrl": "string"
}
}

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: "UPCOMING" "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 Schema: application/json

total

number

Total number of transactions.

Array of objects

Array

id	string Unique identifier of the campaign.
name	string Name of the campaign.
yourCostSharePercentage	number Deprecated Deprecated: use fundedBonusPercentage. Source cost share of the campaign.
extraPointsPercentage	number Deprecated Deprecated: use partnerFundedBonusPercentage. Percentage of the campaign.
fundedBonusPercentage	number Bonus funded by you, as a percentage of the base points (0 for SOLE campaigns). The bonusPoints to send when issuing points is floor(basePoints × fundedBonusPercentage / 100).
partnerFundedBonusPercentage	number Bonus funded by the partner, as a percentage of the base points. The total bonus percentage is fundedBonusPercentage + partnerFundedBonusPercentage.
startDate	string Start date of the campaign.
endDate	string End date of the campaign.
status	string Status of the campaign.
partnerCode	string The partner code.
type	string Enum: "CO-FUNDED" "SOLE" Type of the campaign.
programId	string Destination program id of the campaign.

Response samples

200

Content type

application/json

{"total": 0,
"data": [{"id": "string",
"name": "string",
"yourCostSharePercentage": 0,
"extraPointsPercentage": 0,
"fundedBonusPercentage": 0,
"partnerFundedBonusPercentage": 0,
"startDate": "string",
"endDate": "string",
"status": "string",
"partnerCode": "string",
"type": "CO-FUNDED",
"programId": "string"
}
]
}

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 Schema: application/json

arrays

Response samples

200

Content type

application/json

["AED",
"USD",
"POINTS"
]

Transactions

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

Issue Points - Preview Deprecated

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

Response Schema: application/json

totalPoints

number

Total number of points to be issued.

Request samples

Payload

Content type

application/json

{"programId": "string",
"value": 1.1,
"currency": "string"
}

Response samples

200

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.

The request is de-duplicated on referenceNumber, which must be unique per calling application. Retrying with the same referenceNumber and the same transfer details returns the original transaction with a 200; reusing it for different transfer details is rejected with a 409. A reference number is consumed by the first request that reaches a partner program, whatever its outcome: once it belongs to a failed transaction, resending it returns a 409 with errorCode TRANSACTION_FAILED.

Timeouts and retries. Cosmo keeps the request open for up to 30 seconds while the partner program is called, so set your HTTP client timeout above that (31 seconds or more) and do not abort a slow call early. If the call times out, the connection drops, or you receive a 504, the outcome is unknown: the points may already have been issued. Do not treat it as a failure and do not reverse anything on your side. Once the original call has ended, resend the exact same request (same referenceNumber, same transfer details) and repeat, with a short delay between attempts, until you receive a definitive answer. A resend never issues points twice: if the original went through, it is returned with a 200. A resend that times out again is still unresolved; keep resending.

Which responses are definitive. 200 and 201 mean the points were issued. Every 4xx, and every 5xx other than 504, means the transfer failed and no points were issued, so it is safe to release whatever you reserved on your side. Only a 504 or no response at all leaves the outcome unknown. Every transaction you can retrieve is either COMPLETED or FAILED.

In very rare occurrences, we might provide you with some transactions as failed that were previously considered as success, due to partner discrepancies.

Authorizations:

Bearer

Request Body schema: application/json

programId

required

string

The program id of the desired partner

required

object

The destination user object. Mandatory and optional fields may vary per partner program. Please use the requiredFields from the the Get Programs endpoint for the desired partner program.

destinationUserId	string User ID with your partner organization.
destinationUserEmail	string <email> User email with your partner organization.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.

referenceNumber

required

string <= 255 characters

The transaction reference number provided by the calling application. Required, at most 255 characters, and must be unique across all of your transactions — it is the de-duplication key for this endpoint. Re-sending the same referenceNumber will not create a second transaction.

basePoints

integer

The number of base points to issue. Preferred over value/currency. Provide either basePoints (optionally with bonusPoints), or value and currency.

bonusPoints

integer

Additional bonus points to issue on top of basePoints (for example, co-funded campaign bonuses). Optional; defaults to 0.

value

float

Deprecated

Deprecated — use basePoints instead.

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

string

Deprecated

Deprecated — use basePoints instead.

Use USD or your local currency when sending a monetary amount.
Use POINTS when sending an amount of issued points.

description

string

Short description to attach to the transaction

partnerCode

string

The partner code (required for aggregator)

Responses

Response Schema: application/json

id	string Unique identifier of the original transaction.
totalPoints	number Total number of points issued by the original transaction.
referenceNumber	string Reference number of the transaction.
partnerTransactionId	string Deprecated Deprecated: reconcile on `id` and `referenceNumber` instead. The id the partner program assigned to the credit when it reported one; otherwise equal to `id`.
date	string Date and time the original transaction was created.

Request samples

Payload

Content type

application/json

{"programId": "string",
"basePoints": 100,
"bonusPoints": 20,
"value": 1.1,
"currency": "string",
"destinationAccount": {"destinationUserId": "string",
"destinationUserEmail": "user@example.com",
"destinationUserFirstName": "string",
"destinationUserLastName": "string"
},
"referenceNumber": "string",
"description": "string",
"partnerCode": "string"
}

Response samples

200
201
400

Content type

application/json

{"id": "string",
"totalPoints": 0,
"referenceNumber": "string",
"partnerTransactionId": "string",
"date": "string"
}

Get All Transactions

Retrieve all transactions in a specific interval, whatever their outcome. Every transaction is listed with its status, so filter on it rather than assuming each listed transaction succeeded.

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 Schema: application/json

total

number

Total number of transactions.

Array of objects

Array

id	string Unique identifier of the transaction.
referenceNumber	string Reference number of the transaction.
localCurrencyValue	string <double> Value of the transaction in your organization's currency.
description	string Description of the transaction.
createdAt	string Date and time of the transaction creation.
status	string Enum: "COMPLETED" "FAILED" `COMPLETED`: points were issued. `FAILED`: the transaction could not be delivered to the partner, or the partner rejected the request; the Cosmo team informs you when a previously successful transaction is marked failed.
	Array of objects Empty unless `status` is `COMPLETED`.
	object

Response samples

200

Content type

application/json

{"total": 0,
"data": [{"id": "string",
"referenceNumber": "string",
"localCurrencyValue": "string",
"description": "string",
"createdAt": "string",
"status": "COMPLETED",
"pointTransactions": [{"destinationNumberOfPoints": 0,
"type": "BASE"
}
],
"partnership": {"destinationProgramId": "string"
}
}
]
}

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 Schema: application/json

id

string

Unique identifier of the transaction.

referenceNumber

string

Reference number of the transaction.

localCurrencyValue

string <double>

Value of the transaction in your organization's currency.

description

string

Description of the transaction.

createdAt

string

Date and time of the transaction creation.

status

string

Enum: "COMPLETED" "FAILED"

COMPLETED: points were issued. FAILED: the transaction could not be delivered to the partner, or the partner rejected the request; the Cosmo team informs you when a previously successful transaction is marked failed.

destinationUserId

string

User ID associated with the transaction.

Array of objects

Empty unless status is COMPLETED.

Array

destinationNumberOfPoints	number Number of points issued to the destination.
type	string Enum: "BASE" "PARTNER_CAMPAIGN" "CLIENT_CAMPAIGN" Type of point transaction.

object

destinationProgramId

string

Unique identifier of the destination program.

Response samples

200

Content type

application/json

{"id": "string",
"referenceNumber": "string",
"localCurrencyValue": "string",
"description": "string",
"createdAt": "string",
"status": "COMPLETED",
"destinationUserId": "string",
"pointTransactions": [{"destinationNumberOfPoints": 0,
"type": "BASE"
}
],
"partnership": {"destinationProgramId": "string"
}
}

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 Schema: application/json

One of

Array

id	string Unique identifier of the program connection.
destinationUserId	string User ID with the partner program. Can be null if not required.
destinationUserEmail	string User email with the partner program. Can be null if not required.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.
programId	string Unique identifier of the program.
updatedAt	string Date and time of the last update.
createdAt	string Date and time of creation.

Response samples

200

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.

sourceUserId

required

string

The user identifier with your organization.

required

object

The destination user object. Mandatory and optional fields may vary per partner program. Please use the requiredFields from the the Get Programs endpoint for the desired partner program.

destinationUserId	string User ID with your partner organization.
destinationUserEmail	string <email> User email with your partner organization.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.

sourceUserEmail

string

The user email with your organization.

partnerCode

string

The partner code (required for aggregator).

Responses

Request samples

Payload

Content type

application/json

{"programId": "string",
"destinationAccount": {"destinationUserId": "string",
"destinationUserEmail": "user@example.com",
"destinationUserFirstName": "string",
"destinationUserLastName": "string"
},
"sourceUserId": "string",
"sourceUserEmail": "string",
"partnerCode": "string"
}

Response samples

201

Content type

application/json

{"id": "string",
"sourceUserId": "string",
"sourceUserEmail": "string",
"programId": "string",
"partnerCode": "string",
"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "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 Schema: application/json

total

number

Total number of records.

Array of objects or Array of objects

One of

Array

id	string Unique identifier of the history record.
event	string The event that occured (`LINKED` or `DELINKED`).
programId	string The program id.
	object
destinationUserEmail	string The destination user email.
destinationUserId	string The destination user id.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.
timestamp	string Date and time of the history.

Response samples

200

Content type

application/json

{"total": 0,
"data": [{"id": "string",
"event": "string",
"programId": "string",
"sourceProgramUser": {"sourceUserEmail": "string",
"sourceUserId": "string"
},
"destinationUserEmail": "string",
"destinationUserId": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "string",
"timestamp": "string"
}
]
}

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

Partner Codes

Get Partner Codes

Retrieve a list of the available partner codes.

Authorizations:

Bearer

Responses

Response Schema: application/json

arrays

Response samples

200

Content type

application/json

["EXAMPLE_PARTNER"
]

Programs

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 Schema: application/json

Array

id

string

Unique identifier of the program.

name

string

Name of the program.

businessName

string

Name of the business associated with the program.

logo

string

URL of the program logo.

logoDarkMode

string

URL of the program logo for dark mode.

industry

string

Industry of the program.

termsAndConditionsUrl

string

URL to the terms and conditions of the program.

brandDescription

string

Description of the brand associated with the program.

programCurrency

string

Custom currency code of the program.

pricePerPointInUsd

string <double>

Price per point in USD.

pricePerPointInLocalCurrency

string <double>

Price per point in your organization's currency.

localCurrency

string

Currency code of your organization.

partnerCode

string

The partner code.

object

destinationUserId	string The ID of the destination user.
destinationUserEmail	string The email of the destination user.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.

Response samples

200

Content type

application/json

[{"id": "string",
"name": "string",
"businessName": "string",
"logo": "string",
"logoDarkMode": "string",
"industry": "string",
"termsAndConditionsUrl": "string",
"brandDescription": "string",
"programCurrency": "string",
"pricePerPointInUsd": "string",
"pricePerPointInLocalCurrency": "string",
"localCurrency": "string",
"partnerCode": "string",
"requiredFields": {"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "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

Response Schema: application/json

object

isValid

boolean

The member validation result. For partners without a member validation API endpoint, this indicates whether the submitted details satisfy the partner's validation rules; it does not confirm membership existence or eligibility to receive points. See Partner Validation Support and Rules for each partner's validation availability and applicable rules.

Request samples

Payload

Content type

application/json

{"destinationUserId": "string",
"destinationUserEmail": "string"
}

Response samples

200

Content type

application/json

{"data": {"isValid": true
}
}

Currencies

Get Currencies

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

Authorizations:

Bearer

Responses

Response Schema: application/json

arrays

Response samples

200

Content type

application/json

["AED",
"USD"
]

Transactions

Credit Points

Credit points to a specific user. The point distribution will be provided using the program connections endpoint.

The request is de-duplicated on referenceNumber, which must be unique per calling application. Retrying with the same referenceNumber and the same transfer details returns the original transaction with a 200; reusing it for different transfer details is rejected with a 409.

/multibrand/credit and /multibrand/debit share a single referenceNumber namespace, so a reference number already used on one endpoint cannot be reused on the other.

Authorizations:

Bearer

Request Body schema: application/json

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 `USD` or your local currency when sending a monetary amount.
executionDate required	string The execution date of the transaction
referenceNumber required	string <= 255 characters The transaction reference number provided by the calling application. Required, at most 255 characters, and must be unique across all of your transactions — it is the de-duplication key for this endpoint, and it shares one namespace with `/multibrand/debit`. Re-sending the same `referenceNumber` will not create a second transaction. A reference number is never released, even after the transaction has been executed.

Responses

Response Schema: application/json

sourceUserId	string Your organization's user id.
sourceProgramId	string Your organization's program id.
valueInSourceLocalCurrency	string Accumulated amount in your organization's local currency.
valueInUsd	string Accumulated amount in usd.
localCurrency	string Your organization's local currency.
status	string Enum: "PENDING" "MATURED" "EXECUTED" Current status of the original transaction.
createdAt	string Date and time the original transaction was created.
executionDate	string Date of the transaction execution.

Request samples

Payload

Content type

application/json

{"userId": "string",
"value": 1.1,
"currency": "string",
"executionDate": "string",
"referenceNumber": "string"
}

Response samples

200
201

Content type

application/json

{"sourceUserId": "string",
"sourceProgramId": "string",
"valueInSourceLocalCurrency": "string",
"valueInUsd": "string",
"localCurrency": "string",
"status": "PENDING",
"createdAt": "string",
"executionDate": "string"
}

Get Executed Transactions

Retrieve all executed transactions in a specific interval.

Authorizations:

Bearer

query Parameters

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)

Responses

Response Schema: application/json

total

number

Total number of executed transactions.

Array of objects

Array

id	string Unique identifier of the transaction.
valueInSourceLocalCurrency	number Value of the transaction in your organization currency.
createdAt	string Date and time of the transaction creation.
	Array of objects
	object

Response samples

200

Content type

application/json

{"total": 0,
"data": [{"id": "string",
"valueInSourceLocalCurrency": 0,
"createdAt": "string",
"pointTransactions": [{"numberOfPoints": "string",
"type": "string"
}
],
"partnership": {"destinationProgramId": "string"
}
}
]
}

Debit Points

Debit points from a specific user. The point distribution will be provided using the program connections endpoint.

The request is de-duplicated on referenceNumber, which must be unique per calling application. Retrying with the same referenceNumber and the same transfer details returns the original transaction with a 200; reusing it for different transfer details is rejected with a 409.

/multibrand/debit and /multibrand/credit share a single referenceNumber namespace, so a reference number already used on one endpoint cannot be reused on the other.

Authorizations:

Bearer

Request Body schema: application/json

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 `USD` or your local currency when sending a monetary amount.
referenceNumber required	string <= 255 characters The transaction reference number provided by the calling application. Required, at most 255 characters, and must be unique across all of your transactions — it is the de-duplication key for this endpoint, and it shares one namespace with `/multibrand/credit`. Re-sending the same `referenceNumber` will not create a second transaction. A reference number is never released, even after the transaction has been executed.

Responses

Response Schema: application/json

sourceUserId	string Your organization's user id.
sourceProgramId	string Your organization's program id.
valueInSourceLocalCurrency	string Accumulated amount in your organization's local currency.
valueInUsd	string Accumulated amount in usd.
localCurrency	string Your organization's local currency.
status	string Enum: "PENDING" "MATURED" "EXECUTED" Current status of the original transaction.
createdAt	string Date and time the original transaction was created.
executionDate	string Date of the transaction execution.

Request samples

Payload

Content type

application/json

{"userId": "string",
"value": 1.1,
"currency": "string",
"referenceNumber": "string"
}

Response samples

200
201

Content type

application/json

{"sourceUserId": "string",
"sourceProgramId": "string",
"valueInSourceLocalCurrency": "string",
"valueInUsd": "string",
"localCurrency": "string",
"status": "PENDING",
"createdAt": "string",
"executionDate": "string"
}

Get Balance

Retrieve estimated balance in currencies.

Authorizations:

Bearer

query Parameters

userId required	string Your organization's user id
status required	string Enum: "PENDING" "MATURED"

Responses

Response Schema: application/json

estimatedValueInUsd	string
estimatedValueInSourceLocalCurrency	string

Response samples

200

Content type

application/json

{"estimatedValueInUsd": "string",
"estimatedValueInSourceLocalCurrency": "string"
}

Get Pending Points

Retrieve estimated balance in points.

Authorizations:

Bearer

query Parameters

userId

required

string

Your organization's user id

Responses

Response Schema: application/json

Array

programId	string Your partner's program id
estimatedPoints	number

Response samples

200

Content type

application/json

[{"programId": "string",
"estimatedPoints": 0
}
]

Get Statistics

Retrieve annual statistics of point distribution.

Authorizations:

Bearer

query Parameters

sourceUserId required	string Your organization's user id
programId required	string
year required	string

Responses

Response Schema: application/json

Array

month	number number of the month (1-12)
totalPoints	number total points accumulated in the month

Response samples

200

Content type

application/json

[{"month": 0,
"totalPoints": 0
}
]

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

Responses

Response Schema: application/json

Array

id	string Unique identifier of the program connection.
destinationUserId	string The user identifier with the partner.
destinationUserEmail	string The user identifier with the partner.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.
percentage	number Distribution percentage
destinationProgramId	string Your partner's program id.
updatedAt	string Date and time of the last update.
createdAt	string Date and time of creation.

Response samples

200

Content type

application/json

[{"id": "string",
"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "string",
"percentage": 0,
"destinationProgramId": "string",
"updatedAt": "string",
"createdAt": "string"
}
]

Update Program Connections

Update program 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.

Array

percentage required	number Enum: 0 25 50 75 100 Percentage allocation (must be one of 0, 25, 50, 75, 100)
destinationProgramId required	string The destination program id.
required	object The destination user object. Mandatory and optional fields may vary per partner program. Please use the `requiredFields` from the the Get Programs endpoint for the desired partner program.

Responses

Response Schema: application/json

Array

id	string Unique identifier of the program connection.
destinationUserId	string The user identifier with the partner.
destinationUserEmail	string The user identifier with the partner.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.
percentage	number Distribution percentage
destinationProgramId	string Your partner's program id.
updatedAt	string Date and time of the last update.
createdAt	string Date and time of creation.

Request samples

Payload

Content type

application/json

{"sourceUserId": "string",
"connections": [{"percentage": 0,
"destinationProgramId": "string",
"destinationAccount": {"destinationUserId": "string",
"destinationUserEmail": "user@example.com",
"destinationUserFirstName": "string",
"destinationUserLastName": "string"
}
}
]
}

Response samples

200

Content type

application/json

[{"id": "string",
"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "string",
"percentage": 0,
"destinationProgramId": "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)

Responses

Response Schema: application/json

total

number

Total number of records.

Array of objects

Array

id	string Unique identifier of the history record.
event	string The event that occured (`LINKED` or `DELINKED`).
destinationProgramId	string Your partner's program id.
timestamp	string Date and time of the history.
	object
destinationUserId	string The user identifier with the partner.
destinationUserEmail	string The user identifier with the partner.
destinationUserFirstName	string First name of the destination user.
destinationUserLastName	string Last name of the destination user.

Response samples

200

Content type

application/json

{"total": 0,
"data": [{"id": "string",
"event": "string",
"destinationProgramId": "string",
"timestamp": "string",
"sourceProgramUser": {"sourceUserId": "string"
},
"destinationUserId": "string",
"destinationUserEmail": "string",
"destinationUserFirstName": "string",
"destinationUserLastName": "string"
}
]
}

Delete Program Connection

Delete a program connection by id.

Authorizations:

Bearer

path Parameters

id

required

string

The unique identifier of the program connection to be deleted.