Loyal Guru Streaming Api (1.0)

All endpoints are classified into one of three tiers based on their computational complexity and usage frequency. The following RPS (requests per second) limits apply to all API keys:

When a limit is exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

For full details on global caps, burst limits, and monthly usage, refer to your service agreement or contact your account manager.

An HTTP Response is composed by a STATUS and a BODY ( among other less important things.. ), keep in mind that should read both to have a complete understanding of what is happening. The STATUS is more important and the BODY will give you extra information.

The common HTTP Response Status Codes are used.

Status summary:

• 200: everything is ok. You may need to check the message with the 200 anyway in some cases to do certain thing.

• 4xx: you are not using our API properly. Check the message in the response body for more detail.

• 5xx: Our fault, Loyal Guru Api is having some error, report it to us please

Response Errors

When a request is not success ( Response Status is not 200 ) the Response Body has this format:

{
  "error": "human readable error message",
  "code": "machine friendly error"
}

When the error is related with API KEY validation the response error has this format:

{
  "message": "Forbidden"
}

Every http's code the error means something different

• 400 Your request is not correct, some parameter is required or is not in the right format.

• 402 When a request is valid but does not complete successfully.

• 403 The api key/secret are not valid.

• 404 When the requested resource does not exist or cannot be found.

• 500 Something when wrong with our server (These are rare.).

We recommend to use HTTP Response Status code and HTTP Response Body code field to handle the errors.

Response Body error code field definitions

Server errors

In case of server_error or unexpected error the Application is responsible for waiting for a period of time before issuing another request. This means that after the first error, there is a minimum back-off interval of 1 second and for each consecutive error, the back-off interval increases exponentially up to 32 seconds.

As this is a http API the "real types" that you can use are the types that allows you to send the http protocol as a parameter, these are number, string, boolean and array. So you'll see this 4 types specified along the docs in the request and response parameters of every method, but please keep in mind that your should follow this format guide.

• (Number) Integer: 123 Length from 1 to 9223372036854775807

• (Number) Float: 123.45 Decimal separator is dot, not coma.

• (String): hello

• (String) Date: 2016-12-31

• (String) DateTime: 2016-12-31T23:59:43Z

• (Boolean): true or false

• (Array): [{"key1":123,"key2":"hello","key3":"2016-12-31T23:59:43Z"}]

• (slug): ( not a proper type but.. ) A short label for something, containing only letters, numbers, underscores or hyphens. sub_family

Important notes:

• Date and DateTime: you MUST ensure that you use ISO-8601 date format in UTC, so it's possible that you'll need to apply some kind of conversion to your date ( and UTC will be returned in the API ) (some documentation related). If you are not able to send UTC you should specify the offset of your DateTime ( 2016-12-31T23:59:43-0500 ), keep in mind that the offset is different depending on your timezone and date.

• Regarding to the Integer type: 0 is not a valid integer

• Regarding to the Integer type: 00X will be converted to X so keep in mind this if you have, for example, in your database situations in which 003 is the id of a certain resource and 3 is the id of another different resource, for us 003 and 3 is the same number.To avoid collisions between the real 001 and the real 1 in your database. For this purpose you could solve the problem by always adding to parameter a 1 prefix so the end result is 1001 and 11 and no collision between 001 converted to 1 and the real 1 will be existing

• Text encoding: utf-8

• Along the documentation we are not specifying DateTime or Float. You'll only see it by the example on the param. If the integer can be float you'll se an example with a float and if the Date should be a DateTime you'll see an example with a DateTime instead of a Date.

An Email header can be provided in the API requests. This email parameter will be used to register the authors of the request for a set of specific endpoints. At this moment the endpoints that register the author are:

• POST /scores/transfer

• POST /scores/trigger

After user authentication you can specify the expected language to our API (as part of the http-headers) in order to force the language in which the system will respond to some of the endpoints regarding multi-language content ( for example: coupons, vouchers, rewards, score transactions, challenges). Please notice that if no language is declared in the header, the system will return the default values. This only applies to companies with multilanguage feature enabled

    Accept-Language: 'en'

if "Accept-Language" in header: if "Accept-Language" language is included as part of the possible options: return text in language of the header else: return text in default language of the company else: return default values for multilanguage fields. Ex: English nameNombre en español

The API supports idempotence for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to subtract scores fails due to a network connection error, you can retry the request with the same idempotence key to guarantee that only a single subtract is done. Note that retrying a request with an idempotence key will not change the outcome of a request. When the API receives a request successfully but returns an error code, retrying it with an idempotence key will simply result in a new response with the same error code.

GET and DELETE requests are idempotent by definition, meaning that the same backend work will occur no matter how many times the same request is issued. You shouldn't send an idempotence key with these verbs because it will have no effect.

To perform an idempotent request, provide an additional Idempotency-Key: header to the request.

How you create unique keys is up to you, but we suggest using V4 UUIDs or another appropriately random string. We'll always send back the same response for requests made with the same key, and keys can't be reused with different request parameters. Keys expire after 24 hours.

    Idempotency-Key: 'QknyRdIN6wECfOb5'

We recommend you Postman in order to freely try this API. It's a great tool, easy to use, and you'll be able to issue every call to our API. Remember to set properly your headers.

Download Postman

The main resources you'll be able to manage with this API are:

• Customers

• Customer events

  • Carts (LEGACY Activities): Purchase tickets with line detail and used vouchers and applied promotions
  • Custom Events
  • Triggers

• Loyalty & Gamification campaigns

  • Discount: Discount campaign that define how to discount a cart
  • Points (LEGACY scores): Point campaigns that define how to accumulate points
  • Rewards: Related to rewards that can by redeemed using scores, etc..
  • Challenges: Related to challenges that can by won by customers, etc..
  • Campaign Coupons: coupons associated to a discount campaign ( or a points, reward campaign )
  • Campaigns Vouchers: Association between a customer and a coupon

• Company Data

  • Products: Your merchandise
  • Product Taxonomies: The different categorization levels of your products
  • Product Features: The different values of a certain categorization level
  • Locations: Your different locations / shops / centers, etc..
  • Location Taxonomies: The different categorization levels of your locations
  • Location Features: The different values of a certain categorization level
  • Promotions LEGACY: Generic discounts

Product taxonomy system

Regarding the product taxonomy system, here you'll see and example of how to represent a categorization of products in our flexible system.

+-- Taxonomy ( Family )
|   +-- Feature ( Meat )
|      +-- Product ( Ham )
|      +-- Product ( Cow )
|      +-- Product ( Horse )
|      +-- ...
|   +-- Feature ( Vegetables )
|      +-- Product ( Tomato )
|      +-- ...
|   +-- Feature ( Drinks )
|      +-- Product ( Coca-cola )
|      +-- ...
|   +-- ...
+-- Taxonomy ( Sub-Family )
|   +-- Feature ( Soda )
|      +-- Product ( Coca-cola )
|      +-- ...
|   +-- ...
+-- Taxonomy ( Section )
+-- ...

Check please the documentation of the method create activity below to have a good understanding of how a purchase activity works ( discounts, cancellations , negative and positive values... )

Some of our top resources have support for bulk fetches via "list" API methods. For instance, you can list score transactions or list of vouchers. These list API methods share a common structure with the parameter parameters: starting_after.

Loyal Guru utilizes cursor-based pagination via the starting_after parameter. You must use the response body parameter next_token_starts_after as starting_after parameter to the next to get the next page. If the current page is the last next_token_starts_after is not present.

The order of the elements in the list could change between endpoints.

If your library doesn't support the use of a PATCH method you can always use a PUT method instead.

We strongly recommend the use of the PATCH method as the standard for this kind of actions, but we provide this alternative for older libraries.

Every call must use these three authentication headers:

    X-Api-Key: api_key
    X-Api-Secret: api_key_secret
    X-Api-Version: 1

Please, keep in mind that you must respect Lower and Uppercase characters in the header variable name.

The api_key and the api_key_secret will be delivered by Loyal Guru, ask for them if you don't have them at info@loyal.guru.

For security reasons our system ignores all duplicated calls (same content and action) to update/delete/create elements within a 5-minutes interval.

We use the ID field of the records to avoid duplication and keep the integrity of the system. When you execute any action over a record the ID will be checked:

• Insert a record with an ID that already exists will raise in real time ( not deferred ) a request error.

• Delete a record with an ID than does not exist will raise in real time ( not deferred ) a request error.

Exceptions:

• Activities: ID will no be checked in "POST Activities" ( it will be checked in "POST Activities/RealTime" ), so if a duplicated activity is sent will raise a deferred error and not a real time one.

• Customers: apart form ID the email will also be checked.

Customers

Tiers, Attributes & Audiences

Associations & Merges