diff --git a/akka-contrib/docs/throttle.rst b/akka-contrib/docs/throttle.rst
index 391799d83c..f4c342c283 100644
--- a/akka-contrib/docs/throttle.rst
+++ b/akka-contrib/docs/throttle.rst
@@ -4,6 +4,11 @@ Throttling Actor Messages
 Introduction
 ------------
 
+.. warning::
+  **Deprecation warning** - ``TimerBasedThrottler`` has been deprecated and is scheduled for removal 
+  in the next major version. Use Akka Streams instead, see 
+  :ref:`migration guide <migration-guide-TimerBasedThrottler>`.
+
 Suppose you are writing an application that makes HTTP requests to an external
 web service and that this web service has a restriction in place: you may not
 make more than 10 requests in 1 minute. You will get blocked or need to pay if
diff --git a/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala b/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala
index 12514ac5d0..99c3af5ff6 100644
--- a/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala
+++ b/akka-contrib/src/main/scala/akka/contrib/throttle/TimerBasedThrottler.scala
@@ -17,6 +17,7 @@ import java.util.concurrent.TimeUnit
  * @see [[akka.contrib.throttle.Throttler.SetRate]]
  * @see [[akka.contrib.throttle.Throttler.SetTarget]]
  */
+@deprecated("Use streams, see migration guide", "2.5.0")
 object Throttler {
   /**
    * A rate used for throttling.
@@ -214,6 +215,7 @@ private[throttle] object TimerBasedThrottler {
  *
  * @see [[akka.contrib.throttle.Throttler]]
  */
+@deprecated("Use streams, see migration guide", "2.5.0")
 class TimerBasedThrottler(var rate: Rate) extends Actor with FSM[State, Data] {
   import FSM.`→`
 
diff --git a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst
index 560662943e..8f576faf5e 100644
--- a/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst
+++ b/akka-docs/rst/project/migration-guide-2.4.x-2.5.x.rst
@@ -575,6 +575,59 @@ PeekMailbox
 
 ``PeekMailbox`` is deprecated. Use an explicit supervisor or proxy actor instead.
 
+.. _migration-guide-TimerBasedThrottler:
+
+TimerBasedThrottler
+-------------------
+
+``TimerBasedThrottler`` is deprecated. Use the ``throttle`` stage in Akka Streams instead.
+
+Example in Scala::
+
+  import scala.concurrent.duration._
+  import akka.NotUsed
+  import akka.actor.ActorRef
+  import akka.actor.ActorSystem
+  import akka.stream.ActorMaterializer
+  import akka.stream.OverflowStrategy
+  import akka.stream.ThrottleMode
+  import akka.stream.scaladsl.Sink
+  import akka.stream.scaladsl.Source
+  
+  val system: ActorSystem = ??? // TODO real ActorSystem here
+  val target: ActorRef = ??? // TODO real target ActorRef here
+  implicit val materializer = ActorMaterializer.create(system)
+  
+  val throttler: ActorRef =
+    Source.actorRef(bufferSize = 1000, OverflowStrategy.dropNew)
+      .throttle(100, 1.second, 10, ThrottleMode.Shaping)
+      .to(Sink.actorRef(target, NotUsed))
+      .run()
+
+Example in Java::
+
+  import java.util.concurrent.TimeUnit;
+  import scala.concurrent.duration.FiniteDuration;
+  import akka.NotUsed;
+  import akka.actor.ActorRef;
+  import akka.actor.ActorSystem;
+  import akka.stream.ActorMaterializer;
+  import akka.stream.Materializer;
+  import akka.stream.OverflowStrategy;
+  import akka.stream.ThrottleMode;
+  import akka.stream.javadsl.Sink;
+  import akka.stream.javadsl.Source;
+  
+  final ActorSystem system = null; // TODO real ActorSystem here
+  final ActorRef target = null; // TODO real target ActorRef here
+  final Materializer materializer = ActorMaterializer.create(system);
+
+  final ActorRef throttler =
+    Source.actorRef(1000, OverflowStrategy.dropNew())
+      .throttle(100,  FiniteDuration.create(1, TimeUnit.SECONDS), 10, ThrottleMode.shaping())
+      .to(Sink.actorRef(target, NotUsed.getInstance()))
+      .run(materializer);
+
 Akka Typed
 ==========