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 Users > Edit and checking the box at the bottom that says “Generate API Key”:

Screenshot from 2013-03-22 10:11:03

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

After generating API keys, the keys may be revoked at any time by checking the Revoke API Keys box and clicking Save Changes.

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' );

Comments

  1. vandai

    Hi, any chance of adding end-point for Discount codes??

    Reply

  2. Is the discount endpoint now available? Where is the info?

    Reply

  3. John Doe

    Hello!
    Can I generate API key automatically for any users?

    Reply

    • Automatically as in all users get them when registering, or automatically as in you click a button to generate the key?

      Reply

      • Nitram

        Hi Pippin,

        I have the same question as ‘John Doe’ – as he didn’t follow-up – I think it would make more sense if the key would be issued only upon a dedicated request. This way, people could charge for access. Ideally, the API would also be configurable as to providing roles of who can access which endpoints and how many queries can be made.

        Also, a push API and price feeds would be interesting to see…

        Thanks :)

        Reply

  4. John Doe

    Hello!
    Is there any way to generate API keys and token automatically for created user?

    Reply

  5. Hey Pippin,

    Is there any way to search for products by a category or tag?

    Reply

  6. Henry

    Hi Pippin,

    I have a small app created in .NET. I am trying to do something like this: when the user receives his license key via e-mail he will then download and run the app (portable app). Upon running it he will need to register it using his Lic Key via a form which can be open via the UI. This form will ask the user for the key, name and e-mail. This name and e-mail should be the same one used for the purchase. Upon entering all the info they would click on a button labeled ‘Activate’. I will like to check if the e-mail and name match the one associated with that key purchase, if they do then go ahead and activate the key. If they dont, then a message will appear to make sure they use the correct info.

    I know this logic can be done in the application side, so I guess I need to know if you can return the Name and E-mail (and other fields perhaps.. like version) using the activation API with the Key? Any help is appreciated. Thank You!

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>