Adding (optional) shipping costs per product to nip-15

1 files changed, 24 insertions, 8 deletions

diff --git a/15.md b/15.md
index f8df328..bd0f0db 100644
--- a/15.md
+++ b/15.md
@@ -8,7 +8,7 @@ Nostr Marketplace (for resilient marketplaces)
 
 > Based on https://github.com/lnbits/Diagon-Alley
 
-> Implemented here https://github.com/lnbits/nostrmarket
+> Implemented in [NostrMarket](https://github.com/lnbits/nostrmarket) and [Plebeian Market](https://github.com/PlebeianTech/plebeian-market) 
 
 ## Terms
 
@@ -54,7 +54,7 @@ A merchant can publish these events:
         {
             "id": <String, UUID of the shipping zone, generated by the merchant>,
             "name": <String (optional), zone name>,
-            "cost": <float, cost for shipping. The currency is defined at the stall level>,
+            "cost": <float, base cost for shipping. The currency is defined at the stall level>,
             "countries": [<String, countries included in this zone>],
         }
     ]
@@ -63,9 +63,12 @@ A merchant can publish these events:
 
 Fields that are not self-explanatory:
  - `shipping`:
-   - an array with possible shipping zones for this stall. The customer MUST choose exactly one shipping zone.
+   - an array with possible shipping zones for this stall.
+   - the customer MUST choose exactly one of those shipping zones.
    - shipping to different zones can have different costs. For some goods (digital for example) the cost can be zero.
    - the `id` is an internal value used by the merchant. This value must be sent back as the customer selection.
+   - each shipping zone contains the base cost for orders made to that shipping zone, but a specific shipping cost per
+   product can also be specified if the shipping cost for that product is higher than what's specified by the base cost.
 
 **Event Tags**:
 ```json
@@ -87,17 +90,30 @@ Fields that are not self-explanatory:
     "price": <float, cost of product>,
     "quantity": <int, available items>,
     "specs": [
-      [ <String, spec key>, <String, spec value>]
-     ]
+        [<String, spec key>, <String, spec value>]
+    ],
+    "shipping": [
+        {
+            "id": <String, UUID of the shipping zone. Must match one of the zones defined for the stall>,
+            "cost": <float, base cost for shipping. The currency is defined at the stall level>,
+        }
+    ]
 }
 ```
 
 Fields that are not self-explanatory:
  - `specs`:
-   - an array of key pair values. It allows for the Customer UI to present present product specifications in a structure mode. It also allows comparison between products
+   - an optional array of key pair values. It allows for the Customer UI to present product specifications in a structure mode. It also allows comparison between products
    - eg: `[["operating_system", "Android 12.0"], ["screen_size", "6.4 inches"], ["connector_type", "USB Type C"]]`
 
-_Open_: better to move `spec` in the `tags` section of the event?
+    _Open_: better to move `spec` in the `tags` section of the event?
+
+- `shipping`:
+   - an _optional_ array of costs to be used per shipping zone, only for products that require special shipping costs to be added to the base shipping cost defined in the stall
+   - the `id` should match the id of the shipping zone, as defined in the `shipping` field of the stall
+   - to calculate the total cost of shipping for an order, the user will choose a shipping option during checkout, and then the client must consider this costs:
+     - the `base cost from the stall` for the chosen shipping option
+     - the result of multiplying the product units by the `shipping costs specified in the product`, if any. 
 
 **Event Tags**:
 ```json
@@ -211,4 +227,4 @@ Customer support is handled over whatever communication method was specified. If
 
 ## Additional
 
-Standard data models can be found here <a href="https://raw.githubusercontent.com/lnbits/nostrmarket/main/models.py">here</a>
+Standard data models can be found <a href="https://raw.githubusercontent.com/lnbits/nostrmarket/main/models.py">here</a>