-`checkout events` - A series of private messages exchanged between `merchant` and `customer`, representing the checkout process.
> [!NOTE]
> Nostr Marketplaces operates using Bitcoin as its currency, but `merchants` have the flexibility to set prices in their preferred currency for their `stalls`. This means they can convert from their chosen currency to set a fixed price. Alternatively, merchants can opt to use Bitcoin as their currency, ensuring a fixed price in BTC.
The `merchant` admin software is where the `merchant` creates, updates, and deletes `stalls` and `products`, as well as manages sales, payments, and communication with `customers`. While the `merchant` admin software can be purely client-side, implementations will likely have a server client listening for NOSTR events for convenience and uptime. The `merchant` admin software can be integrated into the marketplace client.
`Marketplace` software should be entirely client-side, either as a standalone app or as a purely frontend webpage. A `customer` subscribes to different merchant NOSTR public keys, and those `merchants'``stalls` and `products` become listed and searchable. The marketplace client is similar to any other e-commerce site, with a basket and checkout. `Marketplaces` may also wish to include a `customer` support area for direct message communication with `merchants`.
-`currency` defines the currency in which the merchant wishes to operate. If it's `BTC`, no conversion is required; if it's different from `BTC`, the platform should perform the necessary conversion to `BTC` at the time of purchase, ensuring accurate price conversion for each buyer.
- Ideally `currency` and `regions` values for shipping costs will utilize ISO 3166 codes to ensure accurate and consistent calculations.
- 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
- an _optional_ array of extra 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
-`type`:This determination categorizes a product as either a `simple` product, a `variable` product, or a `variation` of a variable product. For example, a shirt sold in a single color is a `simple` product, while a shirt offered in multiple colors is a `variable` product with `variations`. To establish a link between a variable product and its variations, the variation product event should include an `a` tag that references the event coordinate of the corresponding variable product.
- The `t` tag is as searchable tag, it represents different categories that the product can be part of (`food`, `fruits`). Multiple `t` tags can be present.
- The `a` tag is employed in products that are variations of a variable product, serving as a linking mechanism. It follows the conventions outlined in [nip01](https://github.com/nostr-protocol/nips/blob/master/01.md#tags)
The `merchant` and the `customer` can exchange JSON messages that represent different actions. Each `JSON` message `MUST` have a `type` field indicating the what the JSON represents. Possible types:
-`Pending` - The order has been created there is something that maintains it on hold, i.e: payment has not been received yet, or the stock of the product has been reduced but the merchant needs to approve the payment.
-`Processing` - The payment has been received and the order is awaiting fulfillment (i.e. shipping products)
-`Completed` - The payment is successful and the order has been fulfilled.
-`Cancelled` - The order has been manually cancelled by the admin or the customer.
-`Refunded` - The order has been refunded by the admin.
-`Failed` - The order has failed due to technical issues or the payment being declined.
Create a customized user experience using the `naddr` from [NIP-19](https://github.com/nostr-protocol/nips/blob/master/19.md#shareable-identifiers-with-extra-metadata). The use of `naddr` enables easy sharing of marketplace events while incorporating a rich set of metadata. This metadata can include relays, merchant profiles, and more. Subsequently, it allows merchants to be grouped into a market, empowering the market creator to configure the marketplace's user interface and user experience, and share that marketplace. This customization can encompass elements such as market name, description, logo, banner, themes, and even color schemes, offering a tailored and unique marketplace experience.
### Event `30019`: Create or update marketplace UI/UX
This event leverages naddr to enable comprehensive customization and sharing of marketplace configurations, fostering a unique and engaging marketplace environment.
> Items sold as an auction are very similar in structure to fixed-price items, with some important differences worth noting.
* The `start_date` can be set to a date in the future if the auction is scheduled to start on that date, or can be omitted if the start date is unknown/hidden. If the start date is not specified, the auction will have to be edited later to set an actual date.
* The auction runs for an initial number of seconds after the `start_date`, specified by `duration`.
Bids are simply events of kind `1021` with a `content` field containing the strigified version of the auction event, and tags consisting of a tag:`a` pointing to the auction event coordinates and a tag:`amount` containing the bid amount expressed as an integer in the auction currency. Bids must refer to an auction.
To ensure the validity of bids, merchants must confirm them before they can be considered valid by other clients. Therefore, clients should subscribe to 'bid confirmation' events (kind `1022`) for every auction they follow, in addition to the actual bids. When checking the bid confirmation, clients must verify that the pubkey of the bid confirmation matches the pubkey of the merchant, in addition to checking the signature.
The `content` field is a JSON object that includes, at a minimum, a `status` field. The `winner` field is used to respond to the winning bid after the auction ends and the merchant has selected the winner.
The reasons for marking a bid as `rejected` or `pending` are determined by the merchant's implementation and configuration. These reasons can range from basic validation errors (e.g., amount too low) to the bidder being blacklisted or lacking sufficient trust, which may lead to the bid being marked as `pending` until additional verification is performed. The key difference between `rejected` and `pending` bids is that `pending` bids may be approved after the bidder takes additional steps, whereas `rejected` bids cannot be later approved. Note that pending bids can be re-evaluated after an update to the auction event, at which point the merchant may publish an update to the starting bid field and mark bids with lower values as pending.
If bids are placed very close to the auction's end date, the merchant can extend the auction duration by updating the `duration` field in the auction event.
Customer support is handled over whatever communication method was specified. If communicating via nostr, NIP-04 is used https://github.com/nostr-protocol/nips/blob/master/04.md.
