fix #8260

1 files changed, 21 insertions, 8 deletions

diff --git a/core/api-merchant.rst b/core/api-merchant.rst
index 7cd0f0dd..d3044505 100644
--- a/core/api-merchant.rst
+++ b/core/api-merchant.rst
@@ -1983,14 +1983,14 @@ Creating orders
       // Short summary of the order.
       summary: string;
 
-      // See documentation of fulfillment_url in ContractTerms.
+      // See documentation of fulfillment_url in `ContractTerms`.
       // Either fulfillment_url or fulfillment_message must be specified.
       // When creating an order, the fulfillment URL can
       // contain ``${ORDER_ID}`` which will be substituted with the
       // order ID of the newly created order.
       fulfillment_url?: string;
 
-      // See documentation of fulfillment_message in ContractTerms.
+      // See documentation of fulfillment_message in `ContractTerms`.
       // Either fulfillment_url or fulfillment_message must be specified.
       fulfillment_message?: string;
     }
@@ -3256,13 +3256,26 @@ The contract terms must have the following structure:
     public_reorder_url?: string;
 
     // URL that will show that the order was successful after
-    // it has been paid for.  Optional. When POSTing to the
-    // merchant, the placeholder "${ORDER_ID}" will be
-    // replaced with the actual order ID (useful if the
+    // it has been paid for.  Optional, but either ``fulfillment_url``
+    // or ``fulfillment_message`` must be specified in every
+    // contract terms.
+    //
+    // If a non-unique fulfillment URL is used, a customer can only
+    // buy the order once and will be redirected to a previous purchase
+    // when trying to buy an order with the same fulfillment URL a second
+    // time. This is useful for digital goods that a customer only needs
+    // to buy once but should be able to repeatedly download.
+    //
+    // For orders where the customer is expected to be able to make
+    // repeated purchases (for equivalent goods), the fulfillment URL
+    // should be made unique for every order. The easiest way to do
+    // this is to include a unique order ID in the fulfillment URL.
+    //
+    // When POSTing to the merchant, the placeholder text "${ORDER_ID}"
+    // is be replaced with the actual order ID (useful if the
     // order ID is generated server-side and needs to be
-    // in the URL).
-    // Note that this placeholder can only be used once.
-    // Either fulfillment_url or fulfillment_message must be specified.
+    // in the URL). Note that this placeholder can only be used once.
+    // Front-ends may use other means to generate a unique fulfillment URL.
     fulfillment_url?: string;
 
     // Message shown to the customer after paying for the order.