NAV Navbar
shell

Overview

This page outlines the parts of Convious pricing API solution and describes the various resources that you will be interacting with to deliver the best prices for your products.

API Structure

In order to price your products we need to receive and process data from different sources at different times. Specifically, we need to know:

Authentication

To authorize, append HTTP Authorization header to your request:

curl "<api_endpoint_here>"
  -H "Authorization: Bearer <access_token_here>"

You will have to authenticate in order to make almost any request to our API. Regardless of the API used, the authentication mechanism is always the same. If you do not provide credentials or provide incorrect ones, a HTTP status code 401 will be returned.

Obtaining access token

curl -X POST \
    -d 'grant_type=client_credentials' \
    -d 'client_id=<client_id>' \
    -d 'client_secret=<client_secret>' \
    https://identity.convious.com/oauth/token/

The request will return a JSON response of the following format:

{
    "token_type": "Bearer",
    "access_token": "<access_token>"
}

Access tokens are issued by our OAUTH2 server. To get a token, use OAUTH2 client_credentials flow.

HTTP Request

POST https://identity.convious.com/oauth/token/

Post Data

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

The data is posted using application/x-www-form-urlencoded content type.

Response

Field Type Description
token_type string Always 'Bearer'
access_token string Token that you should use in your HTTP Authorization header

Versioning

curl "<api_endpoint_here>"
  -H "Accept-Version: <version_here>"

Convious Pricing API is explicitly versioned. This means that with each request you must specify which version of the API you would like to access. This is done by appending Accept-Version HTTP header with the version you need (currently, 1.0.0). If you do not specify the version, a HTTP status code 400 will be returned.

Inventory Management API

Inventory management API is event based. Whenever something changes in your inventory, you should post the relevant events to this API to notify us of the changes. In order for our API to return the most accurate prices, the notifications should be as close to real time as possible, however inventory API does support event batching.

Posting Events

curl https://inventory.convious.com/events \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -H "Accept-Version: <version>" \
    -d @- << EOF
    [
        {
            "type": "ProductCreated",
            "payload": {
                "productReference": "<product_id>",
                "name": "<product_name>",
                "availability": 3,
                "pricing": {
                    "minAcceptedPrice": "12.50",
                    "maxAcceptedPrice": "18.00",
                    "averageTargetPrice": "16.50",
                    "boxOfficePrice": "19.99"
                }
            }
        },
        {
            "type": "ProductRemoved",
            "payload": {
                "productReference": "<product_id>"
            }
        }
    ]
    EOF

HTTP Request

POST https://inventory.convious.com/events

POST Data

A JSON array of events. Event has the following fields:

Field Type Required Description
type string yes An event type that is being published. See below for possible events
payload object yes Event body to be published. Structure of this field depends on event type. See below for possible events

Response

A HTTP 200 status code with no content.

Event Types

Product Created

{
    "type": "ProductCreated",
    "payload": {
        "productReference": "<product_id>",
        "name": "<product_name>",
        "availability": 3,
        "pricing": {
            "minAcceptedPrice": "12.50",
            "maxAcceptedPrice": "18.00",
            "averageTargetPrice": "16.50",
            "boxOfficePrice": "19.99"
        }
    }
}

Notifies that a new product has been created.

Field Type Required Description
type string yes always 'ProductCreated'
payload.productReference string yes The ID of the product in your system
payload.name string yes The name of the product
payload.availability int no The availability of the product (for example, if a product is an event, how many seats are available). For unlimited availability, set to null.
payload.pricing.minAcceptedPrice decimal (string) no The minimum price that the product can be sold for. For no minimum price, set to null.
payload.pricing.maxAcceptedPrice decimal (string) yes The maximum price that the product can be sold for.
payload.pricing.averageTargetPrice decimal (string) no The target sold product price that the pricing API should aim for if product prices are averaged over a long period of time. For no target, set to null.
payload.pricing.boxOfficePrice decimal (string) no The price that the product is sold offline.

Product Pricing Changed

{
    "type": "ProductPricingChanged",
    "payload": {
        "productReference": "<product_id>",
        "pricing": {
            "minAcceptedPrice": "12.50",
            "maxAcceptedPrice": "18.00",
            "averageTargetPrice": "16.50",
            "boxOfficePrice": "19.99"
        }
    }
}

Notifies that the pricing of a product has changed.

Field Type Required Description
type string yes always 'ProductPricingChanged'
payload.productReference string yes The ID of the product in your system
payload.pricing.minAcceptedPrice decimal (string) no The minimum price that the product can be sold for. For no minimum price, set to null.
payload.pricing.maxAcceptedPrice decimal (string) yes The maximum price that the product can be sold for.
payload.pricing.averageTargetPrice decimal (string) no The target sold product price that the pricing API should aim for if product prices are averaged over a long period of time. For no target, set to null.
payload.pricing.boxOfficePrice decimal (string) no The price that the product is sold offline.

Product Removed

{
    "type": "ProductRemoved",
    "payload": {
        "productReference": "<product_id>",
    }
}

Notifies that the product has been removed.

Field Type Required Description
type string yes always 'ProductRemoved'
payload.productReference string yes The ID of the product in your system

Product Availability Changed

{
    "type": "ProductAvailabilityChanged",
    "payload": {
        "productReference": "<product_id>",
        "eventdate": "2018-03-03",
        "startTime": "10:00:00",
        "availability": 4
    }
}

Notifies that availability of a product has changed

Field Type Required Description
type string yes always 'ProductAvailabilityChanged'
payload.productReference string yes The ID of the product in your system.
payload.eventDate date (string) yes ISO 8601 formatted date of the day when the availability has changed.
payload.startTime time (string) no ISO 8601 formatted time of the time when the availability has changed. If the availability should be applied to a full day, set to null.
payload.availability int yes The availability of the product.

Convious Analytics

This is a JavaScript library, similar to Google Analytics, that should be added to your website. It allows registering events that are needed for pricing API to function.

Installing

By adding a script tag

<script type="text/javascript" src="https://scripts.convious.com/analytics.js"></script>

You can add our script to the head element of your website. In order to function properly, this script must be present on every page.

Using NPM

npm install @convious/convious-analytics

You can also bundle the script in your JavaScript using npm/yarn.

Initializing

If installed by adding a script tag:

conviousPricing.init(accountId, cookieId);

If installed using npm/yarn:

import * as conviousPricing from '@convious/convious-analytics'
conviousPricing.init(accountId, cookieId);

In order to function, the library must first be initialized with the ID of your Convious account and the cookie ID of the user.

Parameters:

Name Type Required Description
accountId string yes Account ID of your Convious account
cookieId string yes Cookie ID of the user browsing the website

Sending events

Once initialized, events can be sent using the library.

Page viewed event

conviousPricing.logPageView(refererUrl, currentUrl);

This event notifies that the user has visited a page in the website. In conventional websites the page visits are logged automatically and this does not need to be called directly. However, if your website is a single-page application, it must be called on each application route change.

Parameters:

Name Type Required Description
refererUrl string yes The URL the user is coming from
currentUrl string yes The URL the user has arrived in

User entered checkout event

conviousPricing.logUserEnteredCheckout();

This event notifies that the user has opened a page where he can buy products or opened a html widget within a page that allows him to buy products.

User selected date event

conviousPricing.logUserSelectedDate();

This event notifies that the user has selected event date when buying a product.

User viewed products event

conviousPricing.logUserViewedProducts();

This event notifies that the user has seen a list of available products he can buy.

User viewed prices event

conviousPricing.logUserViewedPrices();

This event notifies that the user has seen prices for the products.

User added an item to cart event

conviousPricing.logUserAddedAnItemToCart();

This event notifies that the user has added a product to cart.

Order created event

conviousPricing.logOrderCreated({
    orderId: '<order_id>',
    items: [{
        productId: '<product_id>',
        amount: 2,
        price: 12.99,
        eventDate: new Date(2018, 4, 1),
        location: 'Almere',
    }, {
        productId: '<product_id>',
        amount: 1,
        price: 11.99,
        eventDate: new Date(2018, 4, 1),
        location: 'Almere',
    }]
});

This event notifies that the user has created an order.

Parameters:

Name Type Required Description
orderId string yes The ID of the order being made
items.productId string yes The ID of a product in the order
items.amount number yes The number of items of a product in the order
items.price number yes The item price of a product in the order
items.eventDate Date no The date when the event is taking place in case the product is time based
items.location string no The location id where the product is being sold (in case of multiple venues at different locations)

Transaction event

conviousPricing.logTransaction(orderId, totalAmount);

This event notifies that the user has made a purchase.

Parameters:

Name Type Required Description
orderId string yes The ID of the order that was paid
totalAmount number yes The total sum of the order

Pricing API

This API returns the actual prices of the products.

Get Prices

curl https://pricer.convious.com/api/price/rtp \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -H "Accept-Version: <version>" \
    -d @- << EOF
    {
        "cookieId": "<cookie_id>",
        "ip": "244.245.246.247",
        "dateFrom": "2018-04-01",
        "dateTo": "2018-04-30",
        "timezone": "Europe/Amsterdam",
        "products": [{
            "productReference": "<product_id>",
            "numberOfItems": 2
        }, {
            "productReference": "<product_id>",
            "numberOfItems": 1
        }],
        "times": ["10:00:00", "10:30:00", "12:30:00"]
    }
    EOF

The request will return a JSON response of the following format:

{
    "prices": [{
        "priceDate": "2018-04-01",
        "priceTime": "10:00:00",
        "products": [{
            "productReference": "<product_id>",
            "numberOfItems": 2,
            "price": "14.89",
        }, {
            "productReference": "<product_id>",
            "numberOfItems": 1,
            "price": "11.89",
        }]
    }, {
        "priceDate": "2018-04-01",
        "priceTime": "10:30:00",
        "products": [{
            "productReference": "<product_id>",
            "numberOfItems": 2,
            "price": "14.49",
        }, {
            "productReference": "<product_id>",
            "numberOfItems": 1,
            "price": "12.99",
        }]
    }]
}

HTTP Request

POST https://pricer.convious.com/api/price/rtp

POST Data

Field Type Required Description
cookieId string yes Cookie ID of the user for whom the price should be returned. Must be the same cookie ID as the one logged using Convious Analytics.
ip string no IP address of the user for whom the price should be returned.
dateFrom date (string) yes An ISO 8601 date marking the start of the date interval for the prices. This day will be the first day that is included in the response.
dateTo date (string) yes An ISO 8601 date marking the end of the date interval for the prices. This day will be the last day that is included in the response.
timezone string yes The timezone to be used for the sale. Must be one of the values in the tz database
products array (Product) yes The list of products that should be priced.
times array (string) no The list of ISO 8601 times for each day that the price should be returned. If you need a single price per day, set to null

Product structure:

Field Type Required Description
productReference string yes The ID of the product in your system.
numberOfItems int yes The number of items of that product that the user has added to his cart

Response

Field Type Description
prices array (TimedPrice) An array of prices for each day and each start time requested

TimedPrice structure:

Field Type Description
priceDate date (string) An ISO8601 date representing the day that the price is for.
priceTime time (string) An ISO8601 time representing the start time that the price is for. If price is for the whole day, this is set to null
products array (Product) An array of products priced for that day and time

Product structure:

Field Type Description
productReference string The ID of the product in your system.
numberOfItems int The number of items of that product that the user has added to his cart
price decimal (string) The price of that product (per item).