Introduction
Welcome to Revi API, an API REST to interact with Revi’s reviews platform. It contains resource-oriented URLs, accepts JSON-encoded requests and uses standard HTTP response codes and authentication.
This API will allow you to integrate your custom development to work with Revi. Revi needs some data to manage the review emails and all the next procedures.
Integration workflow
This is the Revi API integration workflow:
- Revi sends review emails to every user that places an order. For this reason the first step should be to sync your orders with Revi in order to send the email to the customers. Check the orders section for more info.
- Next you can link order products to the orders created in the previous step. This is necessary if you want your customers to review not only their shopping experience but the products too. Check the products and link products to orders sections for more info.
- The platform allows you to synchronize orders even when they are not ready to sent yet. The next step would be to update orders as soon as they are ready so that Revi can send the review email. Check the update orders section for more info.
- Finally, you can get your reviews filtered with an API call. Check the get reviews section for more info.
Authentication
To authorize, use the X-API-KEY header with your API KEY. You can get it in Revi Dashboard > Configuration > Integration (direct link).
curl "https://api.revi.io/api/v1/api_endpoint_here"
-H "X-API-KEY: XXXXXXXXXXXXX"
Make sure to replace
XXXXXXXXXXXXX
with your API key.
Knowledge
This section explains some considerations about using the Revi API.
Response structure
API calls may return a JSON object included in this setting:
Calls that send info to Revi
These calls will return a success parameter that confirms the action has been made correctly.
{
"success": true
}
Calls that get info from Revi
These calls will return the success parameter altogether with a data parameter, containing the information requested.
{
"success": true,
"data": {
"orders": [ ... ] // The resource that has been requested
}
}
Decimal format
The API expects float numbers to be with 2 fixed decimals.
30.51 <!-- Correct -->
30.5 <!-- Incorrect - Missing one decimal -->
30.50 <!-- Correct -->
30 <!-- Incorrect - Missing both decimals -->
30.00 <!-- Correct -->
30.153 <!-- Incorrect - Too much decimals -->
30. <!-- Incorrect - Invalid format -->
Date format
The API expects dates in MYSQL format YYYY-MM-DD HH:MM:SS.
2019-03-05 15:12:03 <!-- Correct -->
05-03-2019 15:12 <!-- Incorrect -->
Optional parameters
Most of the API calls include optional parameters. This means that the calls will process the parameter only if it’s included in the payload data even if it has an empty value. All parameters not specifying the “optional” label will be mandatory.
Quickstart
In order to test if the connection is successful, Revi API provides the hello_world call. It consists of an easy call to test if your environment is connecting with the Revi API successfully.
HTTP Request
POST https://api.revi.io/api/v1/hello_world
Request Parameters
Parameter | Description |
---|---|
test | A string of your choice |
Sample JSON request
{
"test": "Hello Revi, I'm connecting with you!"
}
Sample response.
{
"success": true,
"data": "Hello shop MyShopName, your request was succesful. The content of the test parameter is 'Hello Revi, I'm connecting with you!'"
}
Orders
The order object
{
"id_store": "s01",
"id_order": "xx1",
"lang": "en",
"customer_name": "Carlos",
"customer_lastname": "García",
"email": "example@example.es",
"currency": "EUR",
"shipping_cost": "6.00",
"total_discount": "0.00",
"taxes": "10.50",
"vat": "21",
"total_products": "50",
"total_paid": "66.50",
"status": "pending",
"order_date": "2019-03-05 16:35:12",
"date_status_upd": "2019-03-08 12:03:54"
}
Field | Description |
---|---|
id_store string (optional) |
ID of the store. If you’re not a marketplace leave this empty |
id_order string |
ID of the order. |
email string |
Customer’s email. |
status string |
The order status. One of the following: - pending: Don’t send the review email yet. - ready: Ready to send the review email. - cancelled Order cancelled, don’t ever send email for this order. |
order_date datetime |
The order date. Check date format |
lang string (optional) |
ISO 639, 2 characters language code. |
customer_name string (optional) |
Customer’s name. |
customer_lastname string (optional) |
Customer’s lastname. |
currency string (optional) |
The currency in which the order was placed. Expects ISO 4217 Codes. |
shipping_cost float (optional) |
The shipping amount. Check decimal format |
total_discount float (optional) |
The discount amount. Check decimal format |
taxes float (optional) |
The taxes amount. Check decimal format |
vat string (optional) |
The VAT number without the percentage symbol. |
total_paid float (optional) |
Total order amount. Check decimal format |
date_status_upd datetime (optional) |
The last modified date of the order. This is useful to know when the order changes its status. Check date format |
delete int (optional) |
If you need to delete a previuosly inserted order. |
Create orders
Method to create orders at Revi. This is the first integration step. Once you have synchronized your shop orders with Revi, the platform will start sending emails and obtaining reviews.
HTTP Request
POST https://api.revi.io/api/v1/orders
Request Parameters
Parameter | Description |
---|---|
orders | Array of order objects. |
Sample JSON request
{
"orders": [
{
"id_order": "xx1",
"lang": "en",
"customer_name": "John",
"customer_lastname": "Doe",
"email": "example@example.es",
"currency": "EUR",
"shipping_cost": "6.00",
"total_discount": "0.00",
"taxes": "10.50",
"vat": "21",
"total_products": "50",
"total_paid": "66.50",
"status": "pending",
"order_date": "2019-03-05 16:35:12",
"date_status_upd": "2019-03-08 12:03:54"
},
{
"id_order": "xx2",
"lang": "en",
"customer_name": "Jane",
"customer_lastname": "Doe",
"email": "test@test.es",
"currency": "EUR",
"shipping_cost": "6.00",
"total_discount": "0.00",
"taxes": "10.50",
"vat": "21",
"total_products": "50",
"total_paid": "66.50",
"status": "pending",
"order_date": "2019-03-03 13:12:00",
"date_status_upd": "2019-03-05 12:00:05"
}
]
}
Sample response
{
"success": true,
"order_count": 2
}
Update Status of Orders
Once the orders are synchronized with Revi, the API provides methods to update its status. This is useful if an order was synchronized with pending status and now is ready, permitting Revi to send its review email.
HTTP Request
POST https://api.revi.io/api/v1/orders_status
Request Parameters
This call is a bit different compared to the last, as it needs less order information: id_order, status and date_status_upd.
Parameter | Description |
---|---|
orders | Array of order objects but only including: - id_store string (only marketplaces) - id_order string - status string [‘pending’,’ready’,’cancelled’] - date_status_upd datetime |
Sample JSON request
{
"orders": [
{
"id_store": "s01",
"id_order": "xx1",
"status": "ready",
"date_status_upd": "2019-03-08 12:03:54"
}
]
}
Sample response
{
"success": true,
"order_count": 1
}
Products
The product object
{
"id_product": "p01",
"price": 22.15,
"ean": "000000000",
"sku": "000000000",
"upc": "000000000",
"jan": "000000000",
"isbn": "000000000",
"mpn": "000000000",
"brand": "ExampleBrand",
"stock": "20",
"locale": [
{
"lang": "en",
"name": "Awesome Computer",
"description": "This super computer will blow your mind!",
"url": "http://testshop.com/products/awesome-computer",
"photo_url": "http://testshop.com/img/awesome-computer-p01.jpg"
},
{
"lang": "es",
"name": "Asombroso ordenador",
"description": "Este súper ordenador te dejará flipado!",
"url": "http://testshop.com/productos/asombroso-ordenador",
"photo_url": "http://testshop.com/img/asombroso-ordenador-p01.jpg"
}
],
"combinations": [
{
"id_shop_product_combination": "p01a",
"photo_url": "http://testshop.com/img/p01a.jpg"
},
{
"id_shop_product_combination": "p01b",
"photo_url": "http://testshop.com/img/p01b.jpg"
}
],
}
Field | Description |
---|---|
id_store string (optional) |
ID of the store. If you’re not a marketplace leave this empty |
id_product string |
Product ID |
price float |
Product price |
ean string (optional) |
European Product Article Number |
sku string (optional) |
Product SKU code |
upc string (optional) |
Universal product code |
jan string (optional) |
Product JAN code |
isbn string (optional) |
Product ISBN code |
mpn string (optional) |
Product MPN code |
brand string (optional) |
Product brand |
stock integer (optional) |
Available product stock |
locale array |
Array with the translated information of the product. For more, see the table below. |
combinations array |
Array with the available combinations of the product. For more, see the table below. |
Product translatable data
Field | Description |
---|---|
lang string |
ISO 639, 2 characters language code. Use this to tell the API in which language specified fields are translatable. |
name string |
Product name. translatable field |
Description string (optional) |
Product Description. translatable field |
url string |
Product direct URL. translatable field |
photo_url string (optional) |
Product Photo URL. translatable field |
Product combinations data
Field | Description |
---|---|
id_shop_product_combination string |
ID Product Combination. |
name string |
Product name. translatable field |
ean string (optional) |
European Product Article Number |
sku string (optional) |
Product SKU code |
upc string (optional) |
Universal product code |
jan string (optional) |
Product JAN code |
isbn string (optional) |
Product ISBN code |
mpn string (optional) |
Product MPN code |
brand string (optional) |
Product brand |
photo_url string (optional) |
Product Combination Photo URL |
Create products
Revi API needs basic product info to build beautiful and easy recognizable review emails. Without this information Revi couldn’t ask customers about their opinion on bought products and would only ask for a general shopping experience review.
HTTP Request
POST https://api.revi.io/api/v1/products
Request Parameters
Parameter | Description |
---|---|
products | Array of product objects |
Sample JSON request
{
"products": [
{
"id_product": "p01",
"price": 22.15,
"ean": "49513159135",
"brand": "ExampleBrand",
"stock": "20",
"locale": [
{
"lang": "en",
"name": "Awesome Computer",
"description": "This super computer will blow your mind!",
"url": "http://testshop.com/products/awesome-computer",
"photo_url": "http://testshop.com/img/awesome-computer-p01.jpg"
},
{
"lang": "es",
"name": "Asombroso ordenador",
"description": "Este súper ordenador te dejará flipado!",
"url": "http://testshop.com/productos/asombroso-ordenador",
"photo_url": "http://testshop.com/img/asombroso-ordenador-p01.jpg"
}
]
},
{
"id_product": "p02",
"price": 199.98,
"ean": "13513159879",
"brand": "TestBrand",
"stock": "0",
"locale": [
{
"lang": "en",
"name": "Photo Printer Pro",
"description": "Photo Printer Pro: Get your photos printed in seconds.",
"url": "http://testshop.com/products/photo-printer-pro",
"photo_url": "http://testshop.com/img/photo-printer-pro-126.jpg"
}
],
"combinations": [
{
"id_shop_product_combination": "p02a",
"photo_url": "http://testshop.com/img/p02a.jpg"
},
{
"id_shop_product_combination": "p02b",
"photo_url": "http://testshop.com/img/p02b.jpg"
}
],
}
]
}
Sample response
{
"success": true,
"product_count": 2
}
Link products to orders
Once the products are synced with the Revi platform the next step is linking the order products to the orders.
HTTP Request
POST https://api.revi.io/api/v1/orders_products
Request Parameters
Parameter | Description |
---|---|
orders_products | Array containing id_orders and a nested array with id_products for each order. Optionally you can add the id_shop_product_combination |
Sample JSON request
{
"orders_products": [
{
"id_order": "x0003",
"products": [
{
"id_product": "135" // Product with id 135 bought in id_order x0003
},
{
"id_product": "126" // Product with id 126 bought in id_order x0003
}
]
},
{
"id_order": "x0004",
"products": [
{
"id_product": "126", // Product with id 126 bought in id_order x0004
"id_shop_product_combination": "3a" // product combination with identifier 3a, child of product id 126
}
]
}
]
}
Sample response
{
"success": true,
"product_count": 2
}
Link products to orders, passing full product
Alternatively, you can send the full product object if it was not created previously with the products endpoint.
Sample JSON request
{
"orders_products": [
{
"id_order": "x0003",
"products": [
{
"id_product": "135",
"price": 22.15,
"ean": "13513513658",
"brand": "ExampleBrand",
"stock": "20",
"locale": [
{
"lang": "es",
"name": "Awesome Computer",
"description": "This super computer will blow your mind!",
"url": "http://testshop.com/products/awesome-computer",
"photo_url": "http://testshop.com/img/awesome-computer-135.jpg"
}
]
}
]
}
]
}
Sample response
{
"success": true,
"product_count": 1
}
Get product review info
With this method you can retrieve the number of reviews and average rating of a product.
HTTP Request
POST https://api.revi.io/api/v1/product_info
Parameter | Description |
---|---|
id_product | ID of the product that is being requested. |
Sample request
GET https://api.revi.io/api/v1/product_info?id_product=74
Sample response.
{
"success": true,
"data": {
"product": {
"id_product": "74",
"id_store": "0",
"avg_rating": "4.85",
"num_ratings": "917"
}
}
}
Reviews
The review object
{
"id_comment": "123",
"id_order": "xx1",
"id_store": "0",
"id_product": "0",
"type": "1",
"customer_name": "John",
"customer_lastname": "Doe",
"email": "test@sampleuser.com",
"IP": "00.00.00.00",
"date": "2018-09-20 17:18:05",
"comment": "I liked it so much!",
"rating": "5",
"lang": "en",
"id_product": "3256"
}
Field | Description |
---|---|
id_comment integer |
Revi’s ID of the comment. |
id_order string |
ID of the order that is being reviewed. |
id_store string |
ID of the store. |
type string |
Comment type. One of the following - 1: comment about the shop - 0: comment about a product |
customer_name string |
Customer name. |
customer_lastname string |
Customer lastname. |
email string |
Customer email. |
IP string |
Customer IPv4 Address. |
date datetime |
Comment date. Check date format |
comment string |
Actual comment |
rating float |
Rating from 1 to 5 |
lang string |
Comment language. ISO 639, 2 characters language code. |
id_product string |
If the comment type is product this value will be the product ID that is being reviewed. |
Get reviews
HTTP Request
GET https://api.revi.io/api/v1/reviews
Query parameters (search filters)
Filter | Description | Example |
---|---|---|
from_id | Get reviews with a greater ID than this filter | 15 |
to_id | Get reviews with a lower ID than this filter | 15 |
from_date | Get reviews after this filter’s date | 25 |
to_date | Get reviews before this filter’s date | 2019-01-01 |
equal_to_rating | Get reviews with rating equal to this filter | 2019-01-31 |
greater_than_rating | Get reviews with higher rating to this filter | 4.3 |
id_product | Get reviews of an specific product by ID | 135 |
id_store | For marketplaces. Get reviews of specific store. You can specify multiple store IDs separating them by commas. |
s01 |
Sample request
GET https://api.revi.io/api/v1/reviews?from_date=2018-08-00&limit=2
Sample response.
{
"success": true,
"data": {
"reviews": [
{
"id_comment": "20",
"id_order": "xx1",
"id_store": "0",
"type": "product",
"customer_name": "John",
"customer_lastname": "Doe",
"email": "test@testuser.com",
"IP": "00.00.00.00",
"date": "2018-09-20 17:18:05",
"comment": "I liked it so much!",
"rating": "5",
"lang": "en",
"id_product": "135"
},
{
"id_comment": "21",
"id_order": "xx2",
"id_store": "0",
"type": "general",
"customer_name": "Jane",
"customer_lastname": "Doe",
"email": "test@testuser2.com",
"IP": "00.00.00.00",
"date": "2018-09-20 17:18:05",
"comment": "I recommend this shop",
"rating": "4",
"lang": "en",
"id_product": "0"
}
]
}
}
Shop
Get shop rating info
Use this method if you want to get the number of reviews and average rating of your shop.
HTTP Request
GET https://api.revi.io/api/v1/shop_info
Sample response.
{
"success": true,
"data": {
"shop": {
"avg_rating": "4.68684",
"num_ratings": "7263"
}
}
}
Stores
The store object
{
"id_store": "s01",
"website": "market.com/shop",
"email": "store@market.com",
"default_language": "en",
"status": 1,
"admin_email": "store_admin@market.com",
"locale": [
{
"lang": "en",
"name" : "My Fancy Shop",
"website": "market.es/shop",
"logo_url": "https://market.com/img/logos/store_en.png",
"business": "Store S.L.",
"address": "2029 Oakdale Avenue, Waldron, Indiana",
"email": "store_support_en@market.com",
"phone": "863-462-9168",
"description": "Example shop",
"active": 1
},
{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
]
}
Field | Description |
---|---|
id_store string |
The identifier of the store. Use your own ID, other API calls will need it |
website string |
The store website |
email string |
The public store email |
default_language string |
The store default language. ISO 639, 2 characters language code |
status integer |
If the store is active or not. Use 1 for enabled and 2 for disabled |
admin_email string |
This email will be used to create the store admin account and Revi communications will be done through this address |
locale array |
Array with translated information of the store. See the table below. |
Store translatable data
{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
Field | Description |
---|---|
lang string |
Language of current translatable data. ISO 639, 2 characters language code |
name string |
Shop name |
website string |
Website url |
logo_url string |
Store logo url. Supported image formats: jpg,jpeg and png |
business string |
Business name |
address string |
Store address |
email string |
Store public email |
phone string |
Store public phone |
description string |
Store description |
active integer |
Store status. Use 1 to enable and 0 to disable this store language. |
Create/Update stores
Use this method to create/update your marketplace’s stores. If a id_store is found for the first time the system will create a new store. If the id_store is already at Revi’s database, the system will update that store with the new information provided.
HTTP Request
POST https://api.revi.io/api/v1/stores
Sample JSON request
{
"stores": [
{
"id_store": "s01",
"website": "market.com/shop",
"email": "store@market.com",
"default_language": "en",
"status": 1,
"admin_email": "store_admin@market.com",
"lang": [
{
"lang": "en",
"name" : "My Fancy Shop",
"website": "market.es/shop",
"logo_url": "https://market.com/img/logos/store_en.png",
"business": "Store S.L.",
"address": "2029 Oakdale Avenue, Waldron, Indiana",
"email": "store_support_en@market.com",
"phone": "863-462-9168",
"description": "Example shop",
"active": 1
},
{
"lang": "es",
"name" : "Mi tienda",
"website": "market.es/mitienda",
"logo_url": "https://market.com/img/logos/store_es.png",
"business": "Store S.L.",
"address": "Calle Ejemplo 5, Valencia, España",
"email": "store_support_es@market.com",
"phone": "667667667",
"description": "Tienda de ejemplo",
"active": 1
}
]
} // Add multiple stores by adding more items to the array
]
}
Sample response
{
"success": true,
"data": {
"stores_inserted": 1,
"stores_updated": 0
}
}
Get store rating info
Use this method if you want to get the number of reviews and average rating of a single store. You can pass more than one id_store separated by commas if more than one store is needed.
HTTP Request
GET https://api.revi.io/api/v1/store_info?id_store=s01,s03
Sample response.
{
"success": true,
"data": {
"stores": [
{
"id_store": "s01",
"avg_rating": "4.77778",
"num_ratings": "5",
"error": false
},
{
"id_store": "s03",
"error": true,
"errormsg": "Store s03 not found"
}
]
}
}
Polls
If you want to implement Revi polls without using Revi’s design you can develop your own surveys and then send the user’s answers to Revi via API.
The first step is to create a new Poll in the Revi Dashboard. Setup your survey by adding the appropiate questions and then publish it. Then, you can check the poll’s metadata by accessing to the Advanced tab. This information is needed to post the answers.
Post a poll answer
Use this call to send Revi your user’s answers.
HTTP Request
POST https://api.revi.io/api/v1/poll_answer
Parameters
Field | Description |
---|---|
poll_ident string |
You can find it at the poll advanced settings in Revi’s Dashboard |
id_store string (optional) |
Fill this to link this poll to a store’s order |
id_order string (optional) |
Fill this to link this poll to an order |
remote_ip string (optional) |
Remote user’s IP |
lang string (optional) |
Language in which the user has answered. ISO 639, 2 characters language code. |
answers Array |
Array of answers (see next table to know answer’s structure) |
Answer structure
Field | Description |
---|---|
id_poll_question | The REVI question’s ID. You can check this in poll Advanced tab in Revi’s Dashboard |
value | The value answer. - If the question was of type “text” this value is a string with the user’s response. - If the question was of type “yes or not” this value is a string with ‘yes’ or ‘no’ values. -If question has a numeric response this value is the number answered. -If it’s a question that has multiple options this value is the ID of the options as seen in the poll Advanced tab. -If multiple options can be answered this value will be an array with that option IDs (found at poll Advanced tab). |
Sample request
{
"poll_ident": "5ca7319225364",
"id_order": "e516",
"remote_ip": "XX.XX.XX.XX",
"lang": "es",
"answers": [
{
"id_poll_question": 53,
"value": "yes" // 'Yes' or 'no' response
},
{
"id_poll_question": 59,
"value": 4 // Number response
},
{
"id_poll_question": 52,
"value": "I love your shop design!" // Text response
},
{
"id_poll_question": 54,
"value": 53 // One id_option
},
{
"id_poll_question": 55,
"value": [
"55", "57" // Multiple options, array of id_option
]
}
]
}
Sample response.
{
"success": true,
}
Errors
The Revi API uses the following error codes:
Error Code | Meaning |
---|---|
200 | OK, Everything worked as expected. |
400 | Bad Request, The request was unacceptable, often due to missing a required parameter. |
401 | Unauthorized, No valid API key provided. |
402 | Request Failed, The parameters were valid but the request failed. |
403 | Forbidden, Forbidden access to this API KEY for this request. |
404 | Not Found, The requested resource doesn’t exist. |
500 | Server Errors, Something went wrong on Revi’s end. |