Back to top

API Documentation

JVZoo API v2.0

Introduction

The REST APIs provides programmatic access to data in JVZoo.com. With JVZoo’s API you can retrieve Transaction Summaries, Affiliate Status, Recurring Payment Information, and much more. The REST API identifies JVZoo Applications using Basic Auth; responses are in JSON.

Versions

Latest Stable Version: v2.0

This Version: v2.0

Click to make sure you are looking at the latest version!

Version Description Last Updated End of Life Date
v2.0 First publicly available version 2017-03-03 N/A

Calling the API

Requests (Authorization)

All requests sent to the JVZoo REST API need to be authenticated with valid a API Key over HTTPS. This is to prevent unauthorized access to your account through the API.

Caution

Your API Key grants full access to your JVZoo account including personal, financial and sensitive information - keep these values secret.

To obtain an API key, you first need go to https://www.jvzoo.com/account/applications to create a new API Application under the My Account tab.

Once created, your API key for the active app will be shown under Vendor Applications at http://www.jvzoo.com/account/applications/index.

We will use this API Key to verify your identity on each API call you make. The URL of the JVZoo API v2.0 is:

https://api.jvzoo.com/v2.0

In the examples below, simply replace MyAPIKeyString with your API Key and put in the full api url. Note: leave x in the password portion.

Example Command Line Code: If your API Key is MyAPIKeyString then you can call JVZoo API using curl like:

curl -u MyAPIKeyString:x https://api.jvzoo.com/v2.0

Example PHP Code:

Responses

For ease of use and simplicity for the developers that integration with our API, we have adopted a common response for ALL API calls.

Custom headers and the set of attributes do not change from call to call - only the values of the attributes and the content of the results array are different from call to call

Custom Headers

Every response has the default headers (some shown below), however we also include a custom header X-API-Version in all responses to make it easier to debug.

HTTP/1.0 200 OK
Date: Fri, 30 Oct 2015 10:26:52 GMT
X-API-Version: 2.0
Cache-Control: no-cache
Content-Length: 162
Connection: close
Content-Type: application/json

Sample Response

{
"meta": {
    "status": {
        "http_status_code": 200,
        "code": 2000,
        "message": "Success",
        "detail": null
    },
    "results_count": 1,
    "api_version": "2.0"
},
"results": [
    {
        "id": 1,
        "name: "John Doe",
        "age": 23,
        "birthday": "1991-10-18"
    }
]
}
Name Location Description
Meta meta A set of data that describes and gives information about other data. In this case, it gives the codes, message, detail, count, and version of the results.
Status meta> status The response data from the request.
HTTP Status Codes meta> status> http_status_code Industry standard three digit http status codes used to show what response the request resulted in. Check below for a full list of codes used.
Code meta> status> code JVZoo internal four digit code used to show the response the request resulted in. Used to differentiate between status codes with different messages.
Message meta> status> message Message from the request in basic terms to show what each status code means.
Detail meta> status> detail Details from the request. Default is NULL.
Result Count meta> results_count Shows how many response arrays were given from the requests.
API Version meta> api_version The called version of the API.
Results results> The results given from the request. The results will always be an array. The results can contain more than one array, depending on the request.

HTTP Status Codes

The JVZoo API uses the common and conventional HTTP response codes to show the success and failures of an API request. The following is a list of response codes that are used.

Response Meaning
200 Success
204 Request yielded no content
400 Bad Request - Parameter may be wrong
401 Unauthorized Request - Due to bad request, API key missing, or invalid API key
402 Request Failed - Parameters correct
403 Request Refused - User does not have access
404 Not Found
405 Request Refused - Method not allowed
429 Too Many Requests
500 Internal Server Error

Response Codes

Code Meaning
2000 Success
2040 No content found
4000 Bad Request
4001 Invalid Parameters
4010 API Key is missing
4011 Invalid API Key present
4012 Authenticated user does not have access (specific)
4030 Authenticated user does not have access (general)
4031 Authenticated user does not have access (forbidden)
4040 Not found
4050 Method not allowed
4290 Too many requests
5000 Internal Server Error

Bad or Invalid Responses

All responses (except 204) return the same response body structure as a successful response but with the proper attributes set.

  • Response 204 - based on the specification a 204 the response cannot return a body but only the headers.

  • Example Response 400

{
    "meta": {
        "status": {
            "http_status_code": 400,
            "code": 4001,
            "message": "Invalid Parameters",
            "detail": null
        },
        "results_count": 1,
        "api_version": "2.0"
    },
    "results": [
        null
    ]
}

Payment Statuses

Code Meaning
Unpaid Payment is currently being held.
Payment Error Error while trying to make the payment. Not recoverable.
Paid Payment was paid successfully.
Refunded Payment was successfully refunded.

Affiliate Status

Affiliate Status

Affiliate Status is the details of an affiliate’s relationship with a particular product.

Retrieve a Affiliate Status
GET/v2.0/products/{product_id}/affiliates/{affiliate_id}

Returns the details of a specific affiliate relationship for the specified product.

Example URI

GET https://api.jvzoo.com/v2.0/products/1/affiliates/1
URI Parameters
HideShow
product_id
integer (required) Example: 1

The ID of the product.

affiliate_id
integer (required) Example: 1

The ID of the affiliate.

Response  200
HideShow
Body
{
  "meta": {
    "status": {
      "http_status_code": 200,
      "code": 2000,
      "message": "Success",
      "detail": null
    },
    "results_count": 1,
    "api_version": "2.0"
  },
  "results": [
    {
      "created": "2014-07-31T19:06:11+00:00",
      "product_id": 123456,
      "affiliate_id": "12345",
      "comments": "My Test Comments",
      "status_id": 2,
      "custom_commission": "0.75",
      "delayed_commission": "0"
    }
  ]
}

Payments

Recurring Payments

Cancel
PUT/v2.0/recurring_payment/{preKey}

Cancels a recurring payment for the specified PreKey.

Example URI

PUT https://api.jvzoo.com/v2.0/recurring_payment/PA-1234567890ABCDEFG
URI Parameters
HideShow
preKey
string (required) Example: PA-1234567890ABCDEFG

The key used for that payment.

Request
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "CANCEL"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
"meta": {
    "status": {
        "http_status_code": 200,
        "code": 1000,
        "message": "Success",
        "detail": null
    },
    "results_count": 1,
    "api_version": "2.0"
},
"results": [
    {
        "canceled": TRUE
    }
]
}

Status
GET/v2.0/recurring_payment/{preKey}

Returns the status of a recurring payment for the PreKey specified.

Example URI

GET https://api.jvzoo.com/v2.0/recurring_payment/PA-1234567890ABCDEFG
URI Parameters
HideShow
preKey
string (required) Example: PA-1234567890ABCDEFG

The key used for that payment.

Response  200
HideShow
Body
{
  "meta": {
    "status": {
      "http_status_code": 200,
      "code": 2000,
      "message": "Success",
      "detail": null
    },
    "results_count": 1,
    "api_version": "2.0"
  },
  "results": [
    {
      "id": 123456,
      "status": "ACTIVE",
      "current_payments": 6,
      "max_number_of_payments": 13,
      "max_total_of_all_payments": "37.00",
      "max_amount_per_payment": "3.00",
      "next_payment": "3.00",
      "paypal_email": "email@domain.com",
      "contact_email": "email@domain.com",
      "code": null,
      "price": "3.00",
      "payment_period": 1,
      "payment_count": 12,
      "payment_first_payout": "0.25",
      "has_payment_trial": true,
      "payment_trial_price": "1.00",
      "payment_trial_period": 3,
      "payment_trial_payout": "0.5",
      "payout": null,
      "current_payments_amount": "16.00",
      "created": "2015-06-19T13:12:44+00:00",
      "preKey": "PA-1234567890ABCDEFG",
      "sender_email": "email@domain.com",
      "last_date": "2015-10-23T04:00:00+00:00",
      "next_date": "2015-11-23T05:00:00+00:00",
      "ip": "1.1.1.1",
      "referrer": "https://www.domain.com",
      "tid": null,
      "vtid": null,
      "product_id": 123456
    }
  ]
}

Transactions

Transaction Summaries

Transaction Summaries
GET/v2.0/transactions/summaries/{paykey}

Returns a summary for the specified transaction id.

Example URI

GET https://api.jvzoo.com/v2.0/transactions/summaries/AP-1234567890ABCDEFG
URI Parameters
HideShow
paykey
string (required) Example: AP-1234567890ABCDEFG

The key used for that transaction.

Response  200
HideShow
Body
{
  "meta": {
    "status": {
      "http_status_code": 200,
      "code": 2000,
      "message": "Success",
      "detail": null
    },
    "results_count": 1,
    "api_version": "2.0"
  },
  "results": [
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2014-12-19T12:49:16+00:00",
      "product_name": "My Product",
      "product_id": 123456,
      "status": "COMPLETED",
      "price": "0.75",
      "first_name": "Joe",
      "last_name": "Smith",
      "paypal_email": "email@domain.com"
    }
  ]
}

Affiliate Transactions

Retrieve transactions made by you as an affiliate.

Limitations:

  • Will only return 100 at a time.

Get Affiliate Transactions
GET/v2.0/latest-affiliates-transactions/{paykey}

Example URI

GET https://api.jvzoo.com/v2.0/latest-affiliates-transactions/AP-1234567890ABCDEFG
URI Parameters
HideShow
paykey
string (optional) Example: AP-1234567890ABCDEFG

If a payKey is provided it will use that as the starting point to select from - it will not be included in the results. If not provided the results will start at the oldest transactions starting 90 days ago.

Response  200
HideShow
Body
{
  "meta": {
    "status": {
      "http_status_code": 200,
      "code": 2000,
      "message": "Success",
      "detail": null
    },
    "results_count": 2,
    "api_version": "2.0"
  },
  "results": [
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2016-12-18T08:09:15+00:00",
      "product_name": "Example Product Name",
      "product_id": 123456,
      "status": "COMPLETED",
      "price": "0.01",
      "customer_email": "email@domain.com",
      "ip": "1.1.1.1",
      "first_name": "Joe",
      "last_name": "Smith",
      "affiliate_commission": "0.01",
      "affiliate_commission_status": "UNPAID",
      "affiliate_id": 1,
      "affiliate_name": "Jane Doe"
    },
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2017-02-21T23:00:46+00:00",
      "product_name": "Example Product Name",
      "product_id": 123456,
      "status": "INCOMPLETE",
      "price": "1.20",
      "customer_email": "email@domain.com",
      "ip": "1.1.1.1",
      "first_name": "Joe",
      "last_name": "Smith",
      "affiliate_commission": "0.01",
      "affiliate_commission_status": "PAID",
      "affiliate_id": 2,
      "affiliate_name": "Mary Jane"
    }
  ]
}

Latest Transactions

Retrieve latest transactions of all of your produc ts

Limitations:

  • Will only return 100 at a time.

Get Latest Transactions
GET/v2.0/latest-transactions/{paykey}

Example URI

GET https://api.jvzoo.com/v2.0/latest-transactions/AP-1234567890ABCDEFG
URI Parameters
HideShow
paykey
string (optional) Example: AP-1234567890ABCDEFG

If a payKey is provided it will use that as the starting point to select from - it will not be included in the results. If not provided the results will be start at the oldest transactions.

Response  200
HideShow
Body
{
  "meta": {
    "status": {
      "http_status_code": 200,
      "code": 2000,
      "message": "Success",
      "detail": null
    },
    "results_count": 3,
    "api_version": "2.0"
  },
  "results": [
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2016-12-02T12:50:30+00:00",
      "product_name": "Example Product Name",
      "product_id": 123456,
      "status": "COMPLETED",
      "price": "27.00",
      "customer_email": "email@domain.com",
      "ip": "1.1.1.1",
      "first_name": "Joe",
      "last_name": "Le Feuvre",
      "affiliate_id": 1,
      "affiliate_name": "John Doe"
    },
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2016-12-02T12:51:29+00:00",
      "product_name": "Example Product Name",
      "product_id": 123456,
      "status": "COMPLETED",
      "price": "17.00",
      "customer_email": "dail.email@domain.com",
      "ip": "1.1.1.1",
      "first_name": "Joe",
      "last_name": "Smith",
      "affiliate_id": 2,
      "affiliate_name": "Mary Doe"
    },
    {
      "transaction_id": "AP-1234567890ABCDEFG",
      "date": "2016-12-02T12:51:55+00:00",
      "product_name": "Example Product Name",
      "product_id": 123456,
      "status": "COMPLETED",
      "price": "37.00",
      "customer_email": "email@domain.com",
      "ip": "1.1.1.1",
      "first_name": "Joe",
      "last_name": "Smith",
      "affiliate_id": 3,
      "affiliate_name": "Sue Bates"
    }
  ]
}

Generated by aglio on 18 Jan 2018