This is the documentation for the current release of the Trigg Integrations API.
Current release: 2025-03-03 (v.4.3.0)
This is the documentation for the current release of the Trigg Integrations API.
Current release: 2025-03-03 (v.4.3.0)
Welcome to the Trigg Integrations API documentation, a resource for better understanding of our integration platform.
This documentation is designed to be accessible and informative for both technical and sales professionals, ensuring that you can fully explore the capabilities and benefits of our API.
For technical experts, this documentation provides in-depth insights into the API endpoints, data structures, and integration possibilities. You'll find detailed explanations, code examples, and best practices to help you integrate our API into your applications and systems.
For sales persons and other non-technical stakeholders, this documentation offers a overview of the API's features, use cases, and potential business advantages.
As the configuration of Trigg allows for a flexible request/reponse, only the standard data structures are displayed in this documentation.
If you have a customized configuration and need examples, please contact our support team or your sales person.
The API has two base URL's, one for production and one for testing.
Production: https://api.oculos.no/v4
Staging: https://api.staging.oculos.no/v4
We are excited to announce that our API now has a sandbox environment available! This allows you to test and integrate our features in a safe and controlled setting.
To get your sandbox key, please contact us at hello@triggloyalty.com.
Our API is designed to be secure and efficient, and it requires an API key to authenticate your requests. In this short documentation, we'll guide you on how to use our API with the x-api-key header to ensure successful integration.
x-api-key : <API KEY>
This lets us configure Trigg to only allow access to your API account from those IP's.
The Trigg API returns a standarized detailed error message where it's possible. The structure of the error message looks like this:
{
"code" : "409",
"message" : "Conflict",
"detailedErrorMessage" : {
}
}The detailedErrorMessage is fully dynamic and can contain a simple string aswell as a list of errors'.
By accessing or using our API (the "Service"), you agree to comply with these Terms of Use. Please read them carefully, as they govern your usage of our API.
You are granted a non-exclusive, non-transferable, limited license to access and use our API in accordance with these terms. You may only use the API for its intended purpose and in compliance with our guidelines and documentation.
Access to the API requires an API key. Keep your API key secure and do not share it with unauthorized parties. You are responsible for all actions performed using your API key. Ensure that the API key is not visible in any way in your application.
You may not use the API to engage in any illegal, harmful, or abusive activities. You may not decompile, reverse engineer, or attempt to gain unauthorized access to the API or our systems. You may not use the API in a way that could harm or interfere with our services, infrastructure, or other users.
When using our API, you may have access to user data. Ensure you handle such data in compliance with applicable data protection laws and our privacy policy.
By using our API, you acknowledge that you have read, understood, and agreed to these Terms of Use. Failure to comply with these terms may result in the suspension or termination of your API access.
These methods are provided for early access to new features but may have limited support, and their behavior, parameters, or responses can be modified or deprecated without prior notice.
Use these methods with caution in production environments, as changes may impact integration stability. It is recommended to regularly check the documentation for updates when utilizing preview features.
We reserve the right to update these terms, so it is recommended to review them periodically for any changes.
Trigg API does not have any rate limits, but some external systems integrated with Trigg may have.
Exceeding these limits may result in temporary access restrictions.
We strongly recommend implementing a back-off strategy to handle rate limit exceeded responses. This strategy helps you avoid overloading our/external servers and ensures a smoother user experience.
If you are receving one of the following errors it's an indication of an issue with an external system.
{
"code" : "429",
"message" : "Too Many Requests",
"detailedErrorMessage" : {
}
}{
"code" : "502",
"message" : "Bad Gateway",
"detailedErrorMessage" : {
"gateway" : "Connection to backend system failed. System: [system_name]",
"gatewayMessage" : "Detailed error message here"
}
}A webhook is a way for two different software applications to communicate with each other in real-time. It's like a notification system that triggers actions automatically when certain events occur.
Oculos can configure webhooks on request, please contact our support team for more information.
Available modules:
Endpoints for managing abandoned carts
An abandoned cart function helps businesses track when online shoppers add items to their virtual shopping carts but leave the website or app without completing their purchase.
It captures data about these abandoned carts, including the specific products left behind and, when available, the customer's contact information.
The customers endpoint allows you to create, update or search for customers through various parameters depending on your configuration.
Depending on your configuration, the API may take or return additional fields in the extendedProperties object.
To get an example of your specific integration, please contact our support team.
Endpoints for manually managing different types of loyalty objects.
Methods under this endpoint lets you view current campaigns, manually add bonus points, get balance of a customers loyalty card(s) etc.
Depending on your configuration, the API may take or return additional fields in the extendedProperties object.
To get an example of your specific integration, please contact our support team.
curl -i -X GET \
'https://api.oculos.no/v4/loyalty/bonus/campaigns/{id}' \
-H 'x-api-key: YOUR_API_KEY_HERE'Success
Display name of campign
Points rewarded by purchasing a product included in this campaign. Depending on rewardType, this value is not always set.
URL to an image representing the campaign
[ { "id": "5", "campaignName": "Double bonus on 5 for 300 (covering bark 40 liter)", "campaignType": "F", "rewardType": "double", "points": null, "campaignImageUrl": "https://cdn.oculos.no/images/test.png", "validFrom": "2022-05-29T00:00:00", "validTo": "2022-06-29T00:00:00", "products": [ … ] } ]
Method that allows a third-party to manually import activities and update bonus amount for a member.
Available activites that qualifies for bounus points can be found using the /bonus/rules endpoint.
The request and response can be customer specific and the example below shows only a common type of request body.
The external identifer, most common is the members mobile phone number.
curl -i -X POST \
https://api.oculos.no/v4/loyalty/bonus/import \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"externalId": "+4712345678",
"activity": "20",
"activityDate": "2022-07-01",
"activityValue": 10
}'[ { "status": "1", "statusText": "OK", "points": "38", "totaltPoints": "38", "activityPoints": "8" } ]
curl -i -X POST \
https://api.oculos.no/v4/loyalty/bonus/addRewardPoints \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"points": 1000,
"description": "Extra bonus points due to delayed shipment"
}'{ "externalId": "+4712345678", "activity": "20", "activityDate": "2022-07-01", "activityValue": 10 }
This method allows you to add bonus points to a specific customer based on activity.
The activityId is the identifier of the activity that the customer has performed. The customerId is the identifier of the customer that has performed the activity. The request body is fully dynamic and can contain any number of properties depending on configuration.
The request sample is only an minimum required example and may have to be replaced with the actual request body if the configuration requires it.
An empty payload
curl -i -X POST \
'https://api.oculos.no/v4/loyalty/activity/{activityId}/customerId/{customerId}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{}'The id of the customer that gives away the clips.
The customer that should receive clips. Target identifier can be either id property or mobile phone.
From which loyalty card should the clips be transfered from.
curl -i -X POST \
https://api.oculos.no/v4/loyalty/loyalty-cards/transfer-clips \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"fromCustomerId": "15BE85AB-CD61-4A23-8C22-0981AD35DBD1S2010",
"toCustomerId": "2A9ACDD0-9113-4EF4-8EA9-FD343E040EE9",
"loyaltycardId": "952841C1-4385-40B3-8B30-A65AAC66108E",
"clipCount": 1,
"extendedProperties": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}'curl -i -X GET \
https://api.oculos.no/v4/bonus/rules \
-H 'x-api-key: YOUR_API_KEY_HERE'[ { "bonusRuleId": "2", "name": "Registrering", "bonusRuleType": "REGISTER", "value": "30", "validFrom": "2022-01-01T00:00:00", "validTo": null, "created": "2021-01-01T00:00:00" } ]
curl -i -X GET \
'https://api.oculos.no/v4/loyalty/loyalty-cards/{customerId}' \
-H 'x-api-key: YOUR_API_KEY_HERE'[ { "id": "4", "namn": "Black coffee", "total": 6, "count": 3, "imageUrl": "cdn.oculos.no/coffee_clip3.png", "extendedProperties": { … } } ]
The members unique id.
Depending on your OIP configuration this could be a internal guid (id), mobile phone or other external id.
curl -i -X PUT \
https://api.oculos.no/v4/loyalty/loyalty-cards \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{
"id": "2457B03E-9925-45E9-B551-25F10D7BD4F2",
"memberId": "+4712345678",
"storeId": "STORE-001",
"cashierId": 123,
"itemCount": 1,
"extendedProperties": {
"additionalProp1": {},
"additionalProp2": {},
"additionalProp3": {}
}
}'curl -i -X GET \
https://api.oculos.no/v4/loyalty/loyalty-cards/campaigns \
-H 'x-api-key: YOUR_API_KEY_HERE'[ { "stampCardId": "4", "stampCard": "Black coffee", "stampCardType": "Coffee", "productId": "7049987090935", "extendedProperties": { … } } ]
This method allows you to add bonus points to a specific customer based on activity.
The activityId is the identifier of the activity that the customer has performed. The customerId is the identifier of the customer that has performed the activity. The request body is fully dynamic and can contain any number of properties depending on configuration.
The request sample is only an minimum required example and may have to be replaced with the actual request body if the configuration requires it.
An empty payload
curl -i -X POST \
'https://api.oculos.no/v4/loyalty/transactions/customerId/{customerId}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY_HERE' \
-d '{}'Endpoint that provides method(s) for returning various types of reports. Reports could be either of standard type or could be individually configured for clients.
Examples of reports:
Some reports that have a high volume response, may return the result in pages. This requires the client to iterate through each page to fetch the entire result.
In reports with paging functionality, a metaData object will contain paging information:
{
"metaData": {
"reportType": "customers",
"totalRecords": 12,
"totalPages": 1,
"activePage": 1
}
}totalRecords = Number of records available through all pagestotalPages = How many pages available containing dataactivePage = Which page the client is onTo control wich page to fetch data from and how many records that should be return on each page use querystring parameters.
page = from wich page should the dataset be fetched from (default = 1)rowsPage = how many results per page that should be returned (default = 25)Please contact us for further information on your possiblites.