Skip to main content

Retail Services Platform Callbacks

Overview

This page is intended for informing Retail Services platform partners about callbacks that we can enable upon their request.

A callback is a function that allows informing a partner when a certain event happens. It is individually set up for an application and is triggered for an account in the following cases:

  1. Subscription(s) is activated.

  2. Credentials are generated.

  3. Subscriber status is set.

  4. Subscription expires in a certain period.

  5. Subscription has been terminated.

  6. Support engineer transitions an account to pro.

  7. Support engineer suspends data access for a user account.

Callbacks are optional, we enable them upon your request on the integration stage.

Callback specifications

A POST request is sent to the URL specified for each partner with the following parameters:

  • Header:

    • Content-Type: application/json

    • Custom headers may be included as key-value pairs. These headers are partner-specific and follow the general format of <Custom-Header-Name>: <value>

  • Request body: Defined for each callback, as detailed in the table below

Event

Use case

Request body

Subscription activation

  1. Partner has sent the Activate subscription request and the subscription(s) from the request have been successfully activated for an account.

  2. The request containing the list of activated subscriptions and their expiration datetimes is sent to a partner.

{
    "accountId": "<AccountId>",
    "subscriptions": [
    {
        "feedName": "<FeedName1>",
        "endDate": <timestamp>
    },
    ...
    {
        "feedName": "<FeedNameN>",
        "endDate": <timestamp>
    }
    ]
}

Generation of credentials

Note

This callback is available for applications with credentials generation enabled.

  1. First subscription has been activated for an account.

  2. Credentials have been generated for an account.

  3. The request containing an account identifier, login and password for the account is sent to a partner.

{
     "accountId": "<AccountId>",
     "login": "<GeneratedLogin>",
     "password": "<GeneratedPassword>"
 } 

Setting subscriber status

  1. User has defined their subscriber status (Non-Professional or Professional) on the personal data form and submitted it.

  2. The system associates the specified subscriber status with the user account.

  3. The request containing an account identifier and account subscriber status is sent to a partner.

{
     "accountId": "<AccountId>",
     "subscriberStatus": "<SubscriberStatus>"
 } 

Subscription expiration

  1. Subscription has been activated for an account.

  2. One of the following actions occurs:

    1. Test account is deleted and subscription cancelation is requested.

    2. List of feeds is updated in the Feed group.

    3. Feed group is deleted.

    4. Subscription is canceled via API or the back office.

    5. Account has been blocked automatically as a result of the blacklist validation.

    6. Account has been blocked by a support engineer in the admin panel.

    7. Account has been transitioned from non-pro to pro by a support engineer in the admin panel.

  3. The request containing an account identifier and the list of activated subscriptions and their expiration datetimes is sent to a partner.

{
     "accountId": "<AccountId>",
     "subscriptions": [
     {         "feedName": "<FeedName1>",
         "endDate": <timestamp>
     },
     ...
     {
         "feedName": "<FeedNameN>",
         "endDate": <timestamp>
     }
     ]
 } 

Subscription termination

  1. Subscription has been activated for an account.

  2. One of the following actions occurs:

    1. Account has been blocked by a support engineer in the admin panel.

    2. Account has been blocked automatially as a result of the blacklist validation.

    3. Account has been transitioned from non-pro to pro by a support engineer in the admin panel.

  3. The request containing an account identifier and the list of terminated subscriptions and their expiration datetimes is sent to a partner.

{
    "accountId": "<AccountId>",
    "subscriptions": [
    {
        "feedName": "<FeedName1>",
        "endDate": <timestamp>
    },
    ...
    {
        "feedName": "<FeedNameN>",
        "endDate": <timestamp>
    }
    ]
 }

Transitioning non-professional user to professional

  1. User has defined themselves as non-professional and this subscriber status is set for a user account.

  2. Support engineer transitions a user to professional.

  3. The request containing an account identifier and account subscriber status is sent to a partner.

{
     "accountId": "<AccountId>",
     "subscriberStatus": "<SubscriberStatus>"
 } 

Data access suspension

  1. Support engineer suspends data access for a user account.

  2. The request containing an account identifier is sent to a partner.

{
     "accountId": "<AccountId>"
 } 

Responses

Expected response

Other responses

200 OK

If a partner's application is not available or an internal error occurs, the responses with the following statuses may be expected.

  1. 404 Entity is not found and other 4xx errors

  2. 500 Not expected error on partner's side and other 5xx errors

In such a case, the system resends the request 4 additional times at 10-second intervals until receiving 200 OK response is received or the request limit is reached.

In this section: