diff --git a/docs/features/ratelimiting.rst b/docs/features/ratelimiting.rst
new file mode 100644
index 00000000..d929c905
--- /dev/null
+++ b/docs/features/ratelimiting.rst
@@ -0,0 +1,40 @@
+Rate Limiting
+=============
+
+Thanks to `@catcherwong article <http://www.c-sharpcorner.com/article/building-api-gateway-using-ocelot-in-asp-net-core-rate-limiting-part-four/>`_ for inspiring me to finally write this documentation.
+
+Ocelot supports rate limiting of upstream requests so that your downstream services do not become overloaded. This feature was added by @geffzhang on GitHub! Thanks very much.
+
+OK so to get rate limiting working for a ReRoute you need to add the following json to it. 
+
+.. code-block:: json
+
+    "RateLimitOptions": {  
+        "ClientWhitelist": [],  
+        "EnableRateLimiting": true,  
+        "Period": "1s",  
+        "PeriodTimespan": 1,  
+        "Limit": 1  
+    }  
+
+ClientWhitelist - This is an array that contains the whitelist of the client. It means that the client in this array will not be affected by the rate limiting.
+EnableRateLimiting - This value specifies enable endpoint rate limiting.
+Period - This value specifies the period, such as 1s, 5m, 1h,1d and so on.
+PeriodTimespan - This value specifies that we can retry after a certain number of seconds.
+Limit - This value specifies the maximum number of requests that a client can make in a defined period.
+
+You can also set the following in the GlobalConfiguration part of configuration.json
+
+.. code-block:: json
+
+    "RateLimitOptions": {  
+      "DisableRateLimitHeaders": false,  
+      "QuotaExceededMessage": "Customize Tips!",  
+      "HttpStatusCode": 999,
+      "ClientIdHeader" : "Test"
+    }  
+
+DisableRateLimitHeaders - This value specifies whether X-Rate-Limit and Rety-After headers are disabled.
+QuotaExceededMessage - This value specifies the exceeded message.
+HttpStatusCode - This value specifies the returned HTTP Status code when rate limiting occurs.
+ClientIdHeader - Allows you to specifiy the header that should be used to identify clients. By default it is "ClientId"
diff --git a/docs/index.rst b/docs/index.rst
index 3ae28d2e..258085ef 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -25,6 +25,7 @@ Thanks for taking a look at the Ocelot documentation. Please use the left hand n
    features/authentication
    features/authorisation
    features/administration
+   features/ratelimiting
    features/caching
    features/qualityofservice
    features/headerstransformation