Trigg Integrations API (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)

Overview

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.

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.

Authentication

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.

Step 1: Obtain Your API Key

Before you can start using our API, you'll need to obtain an API key. This key acts as your access pass and is typically provided to you by your contact person. If you haven't received your API key, please reach out to our support team or your sales person.

Step 2: Include the x-api-key Header

To make authenticated requests to our API, you must include the API key in the header of your HTTP requests. Specifically, you should add the "x-api-key" header with your API key as its value.

x-api-key : <API KEY>

Step 3 [OPTIONAL]: White list your IP address(es) for your production environment

Although this step is optional, we strongly encourage you to send us an list of your IP addresses that are in use in your production environment.

This lets us configure Trigg to only allow access to your API account from those IP's.

Error Messages

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

Terms Of Use

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.

API Usage

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.

API Key

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.

Prohibited Actions

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.

Data Privacy

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.

Functionality in preview

Methods marked with Preview in this API documentation are subject to change.

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.

Troubleshooting & Tips

Coming soon

Rate Limits

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"
  }
}

Tutorials

Coming soon.

Webhooks

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.

Change Log

March 2025

2025-03-03

  • Added support for multi branding. This means that you can now run multiple brands on one account.
  • Added 422 quarantine status for the create customers method. This status is used when a customer is quarantined for a period of time.
  • Enable/disable promotions endpoints are now out of preview.
  • The property 'promotionDefinitionId' is now available on the promotion object. This property contains the id of the promotion definition that the promotion is based on.
  • New endpoint for listing all promotion definitions. [PREVIEW] (https://dev.triggloyalty.com/openapi/promotions/getpromotionsdefinitions)
  • New endpoint for listing of all active promotions thare are available to customers. [PREVIEW] (https://dev.triggloyalty.com/openapi/promotions/getpromotionscampaigns)
  • Added a module endpoint. This endpoint collects minor endpoints that are not directly related to the main endpoints.

Available modules:

  • /modules/vehicles - endpoint for fetching and adding vehicles [PREVIEW] (https://dev.triggloyalty.com/openapi/modules/getvehiclesbycustomeridd)

November 2024

2024-11-19

  • Added endpoints for enabling/disabling of promotions (in preview)
  • Added endpoint for transfering clips on loyalty cards between two existing customers (in preview)
  • Minor bugfixes
  • Minor bugfixes in documentation

June 2024

2024-06-18

  • Added endpoint for deleting a customer by external id
  • Minor bugfixes in documentation

May 2024

2024-05-22

  • Added an endpoint for returning all transactions resulting in a bonus reward (https://dev.triggloyalty.com/openapi/loyalty/getbonustransactions)
  • Added a list of promotions on the customer object when applicable. Please note that this list only will contain active promotions.
  • Added information to the documentation on how to mark a transaction as a return (https://dev.triggloyalty.com/openapi/transactions/addtransactions)
  • Minor bugfixes
  • Improved performance

2024-05-14

Added new methods
  • Get customer by externalId
  • Update customer by externalId
  • Minor bugfixes
  • Improved performance

April 2024

2024-04-17

Introduced dynamic methods on the customers and promotions endpoints

March 2024

2024-03-19

Release of v4
Download OpenAPI description
Languages
Servers
Production
https://api.oculos.no/v4/
Staging
https://api.staging.oculos.no/v4/

Abandoned carts

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.

Operations

Customers

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.

Operations

Consents

Endpoint that lists all available consents for a client.

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.

Operations

Data Enrichment

Endpoint that lets you enrich member data .

Operations

Health

Endpoint for checking the Trigg API health status.

With these endpoint(s) you can make a request to Trigg to get a quick system status.

Operations

Import

Endpoint that provides methods for importing data, typically in batches into Trigg.

In this endpoint we can receive many formats and types, such as JSON and XML requests.

To get an example of your specific integration, please contact our support team.

Operations

Loyalty

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.

Operations

Messaging

Endpoint that lets yoy send different types of messages and manually trigger automations that send SMS.

In this endpoint you will also find a complete set of methods to create a 2F verfication solution by SMS.

Operations

Modules

Endpoints for managing minor features that are not directly related to the main endpoints.

Available modules:

  • Wishlist - Endpoints for managing wishlists
  • Vehicles - Endpoints for managing vehicles [PREVIEW]
Operations

Payment Cards

TODO

Operations

Plugins

TODO

Operations

Promotions

This API provides various methods for managing promotions.

Clients can retrieve available promotions id or phone number, redeem promotions, and view redeemed ones.

Operations

Get promotions

Request

Returns a list of all available promotions for a member.

Path
customerIdstringrequired

Id of member.

The type of id parameter is configurable where the most common types are id, mobile phone or an external id.

curl -i -X GET \
  'https://api.oculos.no/v4/promotions/customerId/{customerId}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/jsonArray [
idstring

Generated unique promotion id

Example: "2457B03E-9925-45E9-B551-25F10D7BD4F2"
typestring

Type of promotion

Example: "Promotion"
namestring

Name of promotion

Example: "Welcome coupon"
availableboolean

Boolean that shows the promotions availabilty status

Example: true
descriptionstring
Example: "This is a coupon that gives the customer 10% discount on any product"
urlLinkstring
Example: "Link to the promotion"
urlImagestring

Link to promotion image

Example: "https://cdn.oculos.no/img01.png"
validFromstring
Example: "2024-04-03T07:38:32.495Z"
validTostring
Example: "2024-04-03T07:38:32.495Z"
unlimitedRedemptionboolean

Can the promotion be redeemed unlimited times

Example: false
redemptionLimitinteger

How many times can the promotion be redeemed?

Example: 5
redemptionCountinteger

How many times has the promotion been redeem until now

Example: 1
productsIncludedArray of objects
productsExcludedArray of objects
storesIncludedArray of objects
redemptionChannelsArray of objects
redemptionHistoryArray of objects
]
Response
application/json
[ { "id": "2457B03E-9925-45E9-B551-25F10D7BD4F2", "type": "Promotion", "name": "Welcome coupon", "available": true, "description": "This is a coupon that gives the customer 10% discount on any product", "urlLink": "Link to the promotion", "urlImage": "https://cdn.oculos.no/img01.png", "validFrom": "2024-04-03T07:38:32.495Z", "validTo": "2024-04-03T07:38:32.495Z", "unlimitedRedemption": false, "redemptionLimit": 5, "redemptionCount": 1, "productsIncluded": [ … ], "productsExcluded": [ … ], "storesIncluded": [ … ], "redemptionChannels": [ … ], "redemptionHistory": [ … ] } ]

Get promotions by phone number

Request

Returns a list of all available promotions for a member by using the mobile phone number

Query
mobilePhonestringrequired

Customers mobile phone number

The type of id parameter is configurable where the most common types are id, mobile phone or an external id.

curl -i -X GET \
  'https://api.oculos.no/v4/promotions/mobilePhone?mobilePhone=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Success

Bodyapplication/jsonArray [
idstring

Generated unique promotion id

Example: "2457B03E-9925-45E9-B551-25F10D7BD4F2"
typestring

Type of promotion

Example: "Promotion"
namestring

Name of promotion

Example: "Welcome coupon"
availableboolean

Boolean that shows the promotions availabilty status

Example: true
descriptionstring
Example: "This is a coupon that gives the customer 10% discount on any product"
urlLinkstring
Example: "Link to the promotion"
urlImagestring

Link to promotion image

Example: "https://cdn.oculos.no/img01.png"
validFromstring
Example: "2024-04-03T07:38:32.495Z"
validTostring
Example: "2024-04-03T07:38:32.495Z"
unlimitedRedemptionboolean

Can the promotion be redeemed unlimited times

Example: false
redemptionLimitinteger

How many times can the promotion be redeemed?

Example: 5
redemptionCountinteger

How many times has the promotion been redeem until now

Example: 1
productsIncludedArray of objects
productsExcludedArray of objects
storesIncludedArray of objects
redemptionChannelsArray of objects
redemptionHistoryArray of objects
]
Response
application/json
[ { "id": "2457B03E-9925-45E9-B551-25F10D7BD4F2", "type": "Promotion", "name": "Welcome coupon", "available": true, "description": "This is a coupon that gives the customer 10% discount on any product", "urlLink": "Link to the promotion", "urlImage": "https://cdn.oculos.no/img01.png", "validFrom": "2024-04-03T07:38:32.495Z", "validTo": "2024-04-03T07:38:32.495Z", "unlimitedRedemption": false, "redemptionLimit": 5, "redemptionCount": 1, "productsIncluded": [ … ], "productsExcluded": [ … ], "storesIncluded": [ … ], "redemptionChannels": [ … ], "redemptionHistory": [ … ] } ]

Redeem promotion

Request

Method that redeems a promotion for a customer.

Bodyapplication/json
idstringrequired

Unique identifier of promotion

Example: "71E8AC01-152D-4B2E-956A-3656CD3396AE"
storeIdstringrequired

Id of store that makes the redeem

Example: "STORE-001"
cashRegisterIdstring

Id of cash register in store that makes the redeem

Example: "POS-001"
cashierIdstring

Id of casher/employee that makes the redeem

Example: "123"
customerIdstring

Id of customer to validate the promotion against. Depending on configuration in OIP, this can be a internalId, mobile phone, externalId etc.

Example: "3477B4C3-5E2E-4007-9C26-41E60FECB016"
receiptIdstring

Id of reciept that the promotion i applied to. Should be the same Id as the receipt sent to OIP after the purchase.

Example: "RECEIPT_001"
extendedPropertiesobject

Additional properties depending on configuration

curl -i -X POST \
  https://api.oculos.no/v4/promotions/redeem \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "id": "71E8AC01-152D-4B2E-956A-3656CD3396AE",
    "storeId": "STORE-001",
    "cashRegisterId": "POS-001",
    "cashierId": "123",
    "customerId": "3477B4C3-5E2E-4007-9C26-41E60FECB016",
    "receiptId": "RECEIPT_001",
    "extendedProperties": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }'

Responses

OK

Get Redeemed Promotions

Request

Method that returns a list of redeemed promotions for a customer.

Example of usage; ??

Path
customerIdstringrequired

Id of customer

Bodyapplication/jsonArray [
couponIdstring

Unique id of coupon

Example: "0D23E714-E09C-457E-8D4D-CC3DCCCC8698"
descriptionstring

Short description of coupon

Example: "20% member discount"
]
curl -i -X GET \
  'https://api.oculos.no/v4/promotions/redeem/history/customerId/{customerId}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '[
    {
      "couponId": "0D23E714-E09C-457E-8D4D-CC3DCCCC8698",
      "description": "20% member discount"
    }
  ]'

Responses

OK

Get promotions by cart

Request

Return promotions based on shopping cart

Bodyapplication/json
customerIdstringrequired

customer id

Example: "15BE85AB-CD61-4A23-8C22-0981AD35DBD1S2010"
storeIdstring

Id of store that sends the cart

Example: "STORE001"
receiptIdstring

Unique id of receipt

Example: "08580DEE-C3B8-4808-8A9A-1CE9F8096B52"
articlesArray of objectsrequired
articles[].​articleIdstring
articles[].​pricenumber
articles[].​quantitynumber
curl -i -X POST \
  https://api.oculos.no/v4/promotions/cart \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "customerId": "15BE85AB-CD61-4A23-8C22-0981AD35DBD1S2010",
    "storeId": "STORE001",
    "receiptId": "08580DEE-C3B8-4808-8A9A-1CE9F8096B52",
    "articles": [
      {
        "articleId": "string",
        "price": 0,
        "quantity": 0
      }
    ]
  }'

Responses

OK

Bodyapplication/json
field1string
Example: "This is a string"
field2number
Example: 123
field3string
Example: "Another string"
Response
application/json
{ "field1": "This is a string", "field2": 123, "field3": "Another string" }

Get campaigns

Request

This method allows the client to get a list of all active promotions.

curl -i -X GET \
  https://api.oculos.no/v4/promotions/campaigns \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/jsonArray [
idstring

Id of the promotion campaign

Example: "5A623177-9E15-4568-AC7F-851D36DB70A1"
namestring

Name of the promotion campaign

Example: "Velkomstkupong 10%"
descriptionstring

Description of the promotion campaign

Example: "Velkomstkupong 10%"
redemptionChannelstring

Redemption channel of the promotion campaign

Example: "ALL"
typestring

Type of the promotion campaign

Example: "Promotion"
imageUrlstring

Image URL of the promotion campaign

Example: null
linkUrlstring

Link URL of the promotion campaign

Example: null
validFromstring(date-time)

Start date and time of the promotion campaign

Example: "2025-03-01T00:00:00"
validTostring(date-time)

End date and time of the promotion campaign

Example: null
]
Response
application/json
[ { "id": "5A623177-9E15-4568-AC7F-851D36DB70A1", "name": "Velkomstkupong 10%", "description": "Velkomstkupong 10%", "redemptionChannel": "ALL", "type": "Promotion", "imageUrl": null, "linkUrl": null, "validFrom": "2025-03-01T00:00:00", "validTo": null } ]

Get definitions [PREVIEW]

Request

This method allows the client to list all promotion definitions

curl -i -X GET \
  https://api.oculos.no/v4/promotions/definitions \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring
Example: "8F96A471-05F4-4A9B-8156-97BD35F6F29D"
activeboolean
Example: true
namestring
Example: "Voucher kr 100,-"
descriptionstring
Example: "This is your welcome offer. Use it to get a discount on your next purchase."
linkUrlstring
Example: "https://cdn.oculos.no/8F96A471-05F4-4A9B-8156-97BD35F6F29D"
imageUrlstring
Example: "https://cdn.oculos.no/8F96A471-05F4-4A9B-8156-97BD35F6F29D.png"
typestring
Example: "Promotion"
subTypestring
Example: null
validFromstring(date-time)
Example: "2025-03-01T00:00:00"
validTostring(date-time)
Example: null
redemptionLimitinteger
Example: 1
unlimitedRedemptionboolean
Example: false
redemptionChannelsArray of objects
productsIncludedArray of strings
Example: []
productsExcludedArray of strings
Example: []
storesIncludedArray of strings
Example: []
tiersIncludedArray of strings
Example: []
clientIdstring
Example: null
createdstring(date-time)
Example: "2025-03-06T13:11:25.233"
createdBystring
Example: "no-reply@oculos.no"
updatedstring(date-time)
Example: "2025-03-06T13:11:25.233"
updatedBystring
Example: "no-reply@oculos.no"
Response
application/json
{ "id": "8F96A471-05F4-4A9B-8156-97BD35F6F29D", "active": true, "name": "Voucher kr 100,-", "description": "This is your welcome offer. Use it to get a discount on your next purchase.", "linkUrl": "https://cdn.oculos.no/8F96A471-05F4-4A9B-8156-97BD35F6F29D", "imageUrl": "https://cdn.oculos.no/8F96A471-05F4-4A9B-8156-97BD35F6F29D.png", "type": "Promotion", "subType": null, "validFrom": "2025-03-01T00:00:00", "validTo": null, "redemptionLimit": 1, "unlimitedRedemption": false, "redemptionChannels": [ { … } ], "productsIncluded": [], "productsExcluded": [], "storesIncluded": [], "tiersIncluded": [], "clientId": null, "created": "2025-03-06T13:11:25.233", "createdBy": "no-reply@oculos.no", "updated": "2025-03-06T13:11:25.233", "updatedBy": "no-reply@oculos.no" }

Dynamic method

Request

This method is fully dynamic both in request/response and is available for specific client customizations on the promotions endpoint.

Path
functionstringrequired

Your custom function name provided by Oculos

curl -i -X POST \
  'https://api.oculos.no/v4/promotions/dynamic/{function}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
field1string
Example: "This is a string"
field2number
Example: 123
field3string
Example: "Another string"
Response
application/json
{ "field1": "This is a string", "field2": 123, "field3": "Another string" }

Enable promotion use

Request

This method allows a specific promotion to be used (redeemed) by a specific customer again, if it previously has been disabled using the disableUse method.

As default, promotions are set to available/enabled for use when assigned to a customer.

Path
promotionIdstringrequired

Promotion identifier. (id property found on promotion object).

customerIdstringrequired

Customer identifier (id property on customer).

curl -i -X POST \
  'https://api.oculos.no/v4/promotions/{promotionId}/enableUse/{customerId}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Disable promotion use

Request

Disable the possiblity for a specific promotion to be used (redeemed) by a specific customer.

Path
promotionIdstringrequired

Promotion identifier. (id property found on promotion object).

customerIdstringrequired

Customer identifier (id property on customer).

curl -i -X POST \
  'https://api.oculos.no/v4/promotions/{promotionId}/disableUse/{customerId}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Reports

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:

  • New customers last 24 hours
  • Deleted customers last 24 hours
  • Bonus transactions made by customer
  • +++

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 pages
  • totalPages = How many pages available containing data
  • activePage = Which page the client is on

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

Operations

Stores

Endpoint for Stores

Operations

Transactions

Endpoint for transactions

Operations

Triggers

Endpoints that enables triggering automations through the API.

Automations is a feature that simplifies and speeds up repetitive tasks. It helps marketers send emails, post on social media, and manage customer data more efficiently

Operations

Vipps

Endpoint for Vipps integration

Operations