API Responses
Responses from the API will include headers and JSON data. Depending on the request and HTTP Status Code the information contained in the JSON response will vary. Generally speaking, the JSON response will include a status value, message value, and a body value. The status value is the HTTP Status Code and the message value is the corresponding HTTP Status text. In some cases the body may include additional information. Below you will find a brief overview of the API responses for different request types, more information is available for specific endpoints in the Endpoints section of this documentation.
{
"status":"200",
"message":"OK",
"body":{
"text":"Hello World"
}
}
Example of a basic response
Headers
Responses from the API will include header information for the HTTP Status Code, HTTP Status text, and the amount of tokens remaining before the rate limit is reached for the given window.
JSON Responses
The JSON responses will vary from request to request, but will include the status value, message value, and body value. The information within the body will vary from based on request type, but will stay consistent in its formatting.
GET Request responses
GET request responses will contain a data item within the JSON body. If the request is for one specific piece of data, like an Add-On by unique ID, the data value will be an object with the returned data.
{
"status": "200",
"message": "OK",
"body": {
"data": {
"id": "21",
"store_id": "00",
"subscription_id": null,
"seller_id": "0",
"unique_id": "SAO-000000",
"addon_status": "Active",
"addon_name": "Add On",
"addon_description": "<p>Add-On</p>\n",
"addon_price": "10.00",
"addon_code": "",
"addon_quantities": "0",
"addon_quantity": "0",
"charge_shipping": "0",
"charge_tax": "0",
"addon_image": "20",
"addon_video": null,
"shipping_measurements_weight": null,
"shipping_measurements_length": null,
"shipping_measurements_width": null,
"shipping_measurements_height": null,
"created_admin": "3",
"modified_admin": null,
"deleted_admin": null,
"created": "2018-03-20 15:00:47",
"modified": "2018-04-24 18:46:59",
"deleted": null
}
}
}
Example GET request response
If there are multiple items returned within the response, like requesting all Add-Ons, the data value will be an array of objects.
{
"status": "200",
"message": "OK",
"body": {
"data": [
{
"id": "21",
"store_id": "00",
"subscription_id": null,
"seller_id": "0",
"unique_id": "SAO-000000",
"addon_status": "Active",
"addon_name": "Add On",
"addon_description": "<p>Add-On</p>\n",
"addon_price": "10.00",
"addon_code": "",
"addon_quantities": "0",
"addon_quantity": "0",
"charge_shipping": "0",
"charge_tax": "0",
"addon_image": "20",
"addon_video": null,
"shipping_measurements_weight": null,
"shipping_measurements_length": null,
"shipping_measurements_width": null,
"shipping_measurements_height": null,
"created_admin": "3",
"modified_admin": null,
"deleted_admin": null,
"created": "2018-03-20 15:00:47",
"modified": "2018-04-24 18:46:59",
"deleted": null
},
{
"id": "23",
"store_id": "00",
"subscription_id": null,
"seller_id": "0",
"unique_id": "SAO-000001",
"addon_status": "Active",
"addon_name": "Add-On",
"addon_description": "<p>Add-On</p>\n",
"addon_price": "4.99",
"addon_code": "",
"addon_quantities": "0",
"addon_quantity": "0",
"charge_shipping": "0",
"charge_tax": "0",
"addon_image": null,
"addon_video": null,
"shipping_measurements_weight": null,
"shipping_measurements_length": null,
"shipping_measurements_width": null,
"shipping_measurements_height": null,
"created_admin": null,
"modified_admin": null,
"deleted_admin": null,
"created": "2018-04-24 20:58:32",
"modified": "2018-11-07 20:00:32",
"deleted": null
}
]
}
}
Example GET request response
PUT Request responses
Successful PUT requests will include a text value in the body of the JSON response confirming the content was updated.
{
"status": "200",
"message": "OK",
"body": {
"text": "Content updated"
}
}
PUT request response example
POST Request responses
POST responses will not include a JSON body value and will only include the status and message values.
{
"status": "201",
"message": "Created"
}
Example POST request response
You may also see a POST response for HTTP Status Code 400 Bad Request if information in your request is invalid. Typically, this response means a required field is missing or you are attempting to pass in a field that is not valid. The response body will contain more information about why the request failed in the text value and a fields value containing an object of the values causing an issue will be included.
{
"status": "400",
"message": "Bad Request",
"body": {
"text": "Unknown fields submitted.",
"fields": {
"9": "this_should_fail"
}
}
}
Example of 400 Bad Request response
The key value within the fields object, "9" in the above example, will correspond the location of the item within the data you submitted. So in our example the "this_should_fail" item was the 10th value we passed. Below you can see an example of the passed data.
{
"coupon_code":"API1",
"amount":"5.00",
"amount_type":"currency",
"min_order_total":"5.00",
"uses_allowed":"0",
"start_date":"2018-12-25 00:00:00",
"end_date":"2018-12-31 00:00:00",
"applies_to":"addon",
"addon_id":"21",
"this_should_fail":"because I am unknown"
}
Example of failed POST request data
If the 400 Bad Request response is sent because of required fields being absent the missing fields will be listed.
{
"status": "400",
"message": "Bad Request",
"body": {
"text": "Required fields missing.",
"fields": {
"0": "addon_status",
"2": "addon_description",
"3": "addon_price",
"4": "addon_quantities",
"5": "addon_code"
}
}
}
Missing required fields POST request failure.
DELETE Request Responses
The DELETE response will return a text value in the body confirming the item was deleted.
{
"status": "200",
"message": "OK",
"body": {
"text": "Delete successful"
}
}
Example DELETE response