diff --git a/README.md b/README.md
index df34e2fd6c..d1dc60c6df 100644
--- a/README.md
+++ b/README.md
@@ -468,6 +468,36 @@ an object giving a point-in-time snapshot of Gratipay. The
           - `undefined` (key not present)—no OpenStreetMap account connected
           - `http://www.openstreetmap.org/user/%openstreetmap_username`
 
+**/`%username`/payment-instructions.json**
+([source](https://github.com/gratipay/gratipay.com/www/~/%username/payment-instructions.json.spt))—*private*—Responds to `GET` with an array of objects representing your current payment instructions. A payment instruction is created when a ~user instructs Gratipay to make voluntary payments to a Team. Pass a `team_slug` with `GET` to fetch payment instruction only for that particular team. `POST` an array of objects containing `team_slug` and `amount` to bulk upsert payment instructions(make sure to set `Content-Type` to `application/json`). The `amount` must be encoded as a string rather than a number. In case the upsert is not successful for any object, there will be an `error` attribute in the response explaining the error along with the `team_slug` to identify the object for which the error occured.
+
+This endpoint requires authentication. Look up your user ID and API key on your [account page](https://gratipay.com/about/me/settings/) and pass them using basic auth.
+
+E.g.:
+Request
+
+```
+curl -L https://gratipay.com/username/payment-instructions.json \
+     -u $userid:$api_key \
+     -X POST \
+     -d '[{"amount": "1.00", "team_slug": "foobar"}]' \
+     -H "Content-Type: application/json"
+```
+
+Response
+
+```
+[
+    {
+        "amount": "1.00",
+        "ctime": "2016-01-30T12:38:00.182230+00:00",
+        "due": "0.00",
+        "mtime": "2016-02-06T14:37:28.532508+00:00",
+        "team_name": "Foobar team",
+        "team_slug": "foobar"
+    }
+]
+```
 
 API Implementations
 -------------------