EDD API Reference

Since v1.5, Easy Digital Downloads includes a complete RESTful API that allows store data to be retrieved remotely in either a jSON or XML format. The API includes methods for retrieving info about store products, store customers, store sales, and store earnings.

The API is accessed via the edd-api end point of your store, like so:

http://yoursite.com/edd-api/

In order to access the API, you will need to provide a valid public API key and also a valid token. An API key and token can be generated for any user by going to Downloads > Tools > API Keys:

Screenshot from 2014-07-06 10:03:14

The secret key is used for internal authentication and should never be used directly to access the API.

Once you have an API key, you can begin utilizing the EDD API. Both the API key and the token need to be appended to the URL as query parameters, like so:

http://yoursite.com/edd-api/?key=<API key here>&token=<token here>

Endpoints

The API has four endpoints, each for performing a specific kind of request:

  • stats - For retrieving earnings / sales stats specific dates, date ranges, and specific products.
  • products - For retrieving info about store products.
  • customers - For retrieving customer stats.
  • sales - For retrieving recent sales and info about each sale (items purchased, buyer, amount, etc).

The endpoints are used like so:

http://yoursite.com/edd-api/<endpoint>/

For example:

http://yoursite.com/edd-api/sales/

When combined with the API key and user, the complete URL looks like this:

http://yoursite.com/edd-api/sales/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

Response Format

The response given by the EDD API is available in two formats:

To specify the format returned (jSON will be used if none is specified), simply add the format argument to the URL:

http://yoursite.com/edd-api/sales/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&format=xml

A sample JSON response looks like this:

{
    "sales": [
        {
            "ID": 611,
            "subtotal": "20",
            "tax": 0,
            "fees": false,
            "total": "20",
            "gateway": "manual",
            "email": "johntest23@test.com",
            "date": "2013-02-25 11:42:05",
            "products": [
                {
                    "name": "Simple Notices Pro",
                    "price": "20",
                    "price_name": "Price one"
                }
            ]
        }
    ]
}

A sample XML response (for the same query) looks like this:

<edd>
  <sales>
    <ID>611</ID>
    <subtotal>20</subtotal>
    <tax>0</tax>
    <fees>false</fees>
    <total>20</total>
    <gateway>manual</gateway>
    <email>johntest23@test.com</email>
    <date>2013-02-25 11:42:05</date>
    <products>
      <name>Simple Notices Pro</name>
      <price>20</price>
      <price_name>Price one</price_name>
    </products>
  </sales>
</edd>

Paging Parameters

By default, the EDD API will return 10 results per page for the customers, sales, and products queries.

If a query has 20 results, the first ten will be displayed by default, but then the second 10 can be accessed by adding &page=2 to the query string, like so:

http://yoursite.com/edd-api/sales/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&page=2

You can change the number of results returned by using the number parameter. This example will return 25 results per page:

http://yoursite.com/edd-api/sales/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&number=25

If you want to retrieve all results (no paging), set number to -1.

Customers Query

The customers endpoint allows for you to query the database and retrieve a list of customers that have purchased items from your shop. A basic customers query looks like this:

http://yoursite.com/edd-api/customers/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&number=25

For each customer returned, the following information is returned for each customer:

  • id - The WordPress user ID. If the customer purchased as a guest, this will return as -1.
  • username - The WordPress user login name. If the customer purchased as a guest, this will return as "Guest".
  • display_name - The WordPress user display name. If the customer purchased as a guest, this will return as "Guest".
  • first_name - The WordPress user first name. If the customer purchased as a guest, this will return as "Guest".
  • last_name - The WordPress user last name. If the customer purchased as a guest, this will return as "Guest".
  • email - The customer's email address.
  • total_purchases - The total number of purchases the customer has made.
  • total_spent - The total amount the customer has spent.
  • total_downloads - The total number of files the customer has downloaded.

Along with the data returned for each customer is a stats object that shows the total number of customers in the database.

A customers query response looks like this:

{
    "customers": [
        {
            "info": {
                "id": -1,
                "username": "Guest",
                "display_name": "Guest",
                "first_name": "Guest",
                "last_name": "Guest",
                "email": "johnson@test.com"
            },
            "stats": {
                "total_purchases": 2,
                "total_spent": "20",
                "total_downloads": 0
            }
        },
        {
            "info": {
                "id": -1,
                "username": "Guest",
                "display_name": "Guest",
                "first_name": "Guest",
                "last_name": "Guest",
                "email": "asda@test.com"
            },
            "stats": {
                "total_purchases": 0,
                "total_spent": "0",
                "total_downloads": 0
            }
        }
    ]
}

If you wish to retrieve the info for a specific customer, you can add the &customer={identifier} parameter, like this:

http://yoursite.com/edd-api/customers/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&customer=1

or

http://yoursite.com/edd-api/customers/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&customer=email@domain.com

The response for a single customer will be like this:

{
    "customers": [
        {
            "info": {
                "id": 1,
                "username": "pippin",
                "display_name": "Pippin Williamson",
                "first_name": "Pippin",
                "last_name": "Williamson",
                "email": "pippin@pippinsplugins.com"
            },
            "stats": {
                "total_purchases": 61,
                "total_spent": 1139.68,
                "total_downloads": 31
            }
        }
    ]
}

Sales Query

The sales endpoint allows for you to query the database and retrieve information for recent sales. A basic sales query looks like this:

http://yoursite.com/edd-api/sales/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

For each sale returned, the following information will be available:

  • ID - The sale ID number.
  • key -The sale purchase key.
  • subtotal - The sale subtotal.
  • tax - The sales tax amount.
  • fees - Any arbitrary fees that were added to the sale.
  • total - The total sale amount.
  • gateway - The payment method, such as stripe or paypal, used to make the purchase.
  • email - The email address associated with the sale.
  • date - The date the sale was made.
  • products - A list of products purchased. For each product:
    • name - The name of the product.
    • price - The price of the product (after any discounts).
    • price_name - The price option name that was purchased (if the product has variable prices).

An example sales query response looks like this:

{
    "sales": [
        {
            "ID": 611,
            "key": "ca2aaaa2a9e9e5369b8280403431b6fd",
            "subtotal": "20",
            "tax": 0,
            "fees": null,
            "total": "20",
            "gateway": "manual",
            "email": "johntest23@test.com",
            "date": "2013-02-25 11:42:05",
            "products": [
                {
                    "name": "Simple Notices Pro",
                    "price": "20",
                    "price_name": "Price one"
                }
            ]
        },
        {
            "ID": 607,
            "key": "7608c3f1b8f5e00b7f21add193ab7ced",
            "subtotal": "20",
            "tax": 0,
            "fees": null,
            "total": "20",
            "gateway": "manual",
            "email": "johntest23@test.com",
            "date": "2013-02-25 11:41:48",
            "products": [
                {
                    "name": "Simple Notices Pro",
                    "price": "20",
                    "price_name": "Price one"
                }
            ]
        }
    ]
}

Products Query

The products endpoint allows you to retrieve information about your store products. A basic products query looks like this:

http://yoursite.com/edd-api/products/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70

A sample products response looks like this:

{
    "products": [
        {
            "info": {
                "id": 435,
                "slug": "test-2",
                "title": "Test",
                "create_date": "2013-02-06 19:25:18",
                "modified_date": "2013-02-12 09:40:31",
                "status": "publish",
                "link": "http:\/\/localhost\/wordpress\/?post_type=download&p=435",
                "content": "Test",
                "thumbnail": "http:\/\/localhost\/wordpress\/wp-content\/uploads\/edd\/2013\/01\/2649089468_abb2633bc6_o.jpg"
            },
            "stats": {
                "total": {
                    "sales": "6",
                    "earnings": "60"
                },
                "monthly_average": {
                    "sales": 6,
                    "earnings": 60
                }
            },
            "pricing": {
                "amount": "29000.00"
            },
            "files": [
                {
                    "name": "",
                    "file": "test",
                    "condition": "all"
                }
            ],
            "notes": ""
        },
        {
            "info": {
                "id": 16,
                "slug": "simple-notices-pro",
                "title": "Simple Notices Pro",
                "create_date": "2013-01-07 22:42:18",
                "modified_date": "2013-02-25 16:16:39",
                "status": "publish",
                "link": "http:\/\/localhost\/wordpress\/?post_type=download&p=16",
                "content": "Dapibus dignissim hac ac penatibus eros, quis diam augue! Nisi dapibus in ridiculus auctor ridiculus scelerisque turpis augue, vel turpis ac odio egestas urna, eros in augue amet, mus et? Nisi est tincidunt ultricies et montes, massa sit. Nec purus? Est cras arcu vut pid? In, dapibus urna porttitor pellentesque pellentesque scelerisque! Diam vel in, adipiscing, dictumst? Cursus vut nec? Cras amet nunc? Tortor vel. Tempor phasellus integer et, turpis nec in! Ut vel turpis, ac dictumst augue! Auctor vel ut, penatibus parturient aliquam, porttitor! Aliquet vut magna eu, ac, aliquam montes a vel, odio, dictumst nec enim vel, pulvinar. Mattis dignissim, urna lacus purus integer, eros vel! Augue dictumst, in arcu integer magna elementum ut. Pid a lacus ultrices.",
                "thumbnail": "http:\/\/localhost\/wordpress\/wp-content\/uploads\/2013\/01\/edd_product_support.png"
            },
            "stats": {
                "total": {
                    "sales": "47",
                    "earnings": "902.2"
                },
                "monthly_average": {
                    "sales": 47,
                    "earnings": 902.2
                }
            },
            "pricing": {
                "priceone": "20",
                "pricetwo": "30",
                "price3": "40.55"
            },
            "files": [
                {
                    "name": "Screenshot from 2013-01-09 16:21:43",
                    "file": "http:\/\/localhost\/wordpress\/wp-content\/uploads\/edd\/2013\/01\/Screenshot-from-2013-01-09-162143.png",
                    "condition": "all"
                },
                {
                    "name": "Screenshot from 2013-01-14 09:37:41",
                    "file": "http:\/\/localhost\/wordpress\/wp-content\/uploads\/edd\/2013\/02\/Screenshot-from-2013-01-14-093741.png",
                    "condition": "1"
                }
            ],
            "notes": "These are the product notes."
        }
    ]
}

If you want to retrieve info for only a specific product, you can pass a product ID via the product parameter:

http://yoursite.com/edd-api/products/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&product=55

Stats Query

The stats query is used for retrieving earnings/sales stats from your store. It can be used to retrieve total earnings for the current month, last year, a specific date rage, etc, as well as the same options for sales. It can also be used for retrieving earnings / sales stats for any or all products.

The stats endpoint is:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=<QUERY TYPE>

Note that the stats query requires a type parameter to be passed. There are two type options:

  • sales - For retrieving sale stats.
  • earnings - For retrieving earning stats.

Both sales and earnings query types include additional parameters for date and product options:

  • date - The date to retrieve earnings or sales for. This has three accepted values:
    • today - Will retrieve stats for the current day.
    • yesterday - Will retrieve stats for the previous day.
    • range - Will retrieve stats for a date range.
      • startdate - Format: YYYYMMDD. Example: 20120224 = 2012/02/24
      • enddate - Format: YYYYMMDD. Example: 20120531 = 2012/02/24
  • product - used to retrieve sale or earnings stats for a specific product, or all products. This option has two accepted values:
    • # - The product ID to retrieve stats for.
    • all - Retrieve stats for all products. This option does not support paging.

Note: the product and date options cannot be combined. You may only use one or the other.

A basic earnings stats query looks like this:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=earnings

And the response is:

{
    "earnings": {
        "current_month": 20,
        "last_month": 311.96,
        "totals": 1302.2764
    }
}

A basic sales stats query looks like this:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=sales

And the response is:

{
    "sales": {
        "current_month": 1,
        "last_month": 18,
        "totals": 71
    }
}

If passing a date of today or yesterday, the query looks like this:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=sales&date=today

And the response:

{
    "sales": {
        "today": 1
    }
}

If passing a date range, the query will be:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=sales&date=range&startdate=20130201&enddate=20130210

And the response:

{
    "totals": 12,
    "sales": {
        "20130201": 0,
        "20130202": 0,
        "20130203": 0,
        "20130204": 0,
        "20130205": 0,
        "20130206": 1,
        "20130207": 0,
        "20130208": 0,
        "20130209": 11,
        "20130210": 0
    }
}

Each item in the sales object represents the day and the value is the amount.

If passing the product parameter, like so

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=sales&product=all

the response will be:

{
    "sales": [
        {
            "test-2": "6"
        },
        {
            "simple-notices-pro": "48"
        },
        {
            "love-it-pro": "13"
        },
        {
            "test-product-2-2": "0"
        },
        {
            "test-product-1-2": "0"
        }
    ]
}

Or for an individual product:

http://yoursite.com/edd-api/stats/?key=c281cf0a95be875d9eeb284fb004c938&token=5f9432f3ffa5945755ebc66179810d70&type=sales&product=16

Response:

{
    "sales": [
        {
            "simple-notices-pro": "48"
        }
    ]
}

Error Messages

If the query you have passed to the EDD API returns an error, the response will come back like this:

{
    "error": "Invalid query!"
}

Each query method in the API includes meaningful error messages to help you figure out what you have done wrong.

For example, if you attempt to perform a stats query with a date range but enter an end date that is before the start date, you will get an error like this:

{
    "error": "The end date must be later than the date date!"
}

API Request Logging

By default, Easy Digital Downloads will log all API request attempts. The log entries for API requests can be seen at Downloads > Reports > Logs > API Requests:

Screenshot from 2013-03-08 14:33:13

The main purpose of the API request logs is to provide a means of monitoring how the API is being used (or abused). For example, if you discover that an ex shop worker is still using the API, you can easily see that by monitoring the logs.

If you wish to disable API Request logging, simply add this filter:

add_filter( 'edd_api_log_requests', '__return_false' );

Last updated on December 25, 2014