@vendure/docs 0.0.0-202601161541

package/docs/user-guide/orders/orders.md

@@ -0,0 +1,65 @@
+---
+title: "Orders"
+weight: 3
+---
+
+# Orders
+
+An Order is created whenever someone adds an item to their cart in the storefront. In Vendure, there is no distinction between a "cart" and an "order". Thus a "cart" is just an Order which has not yet passed through the checkout process.
+
+## The Order Workflow
+
+The exact set of stages that an Order goes through can be customized in Vendure to suit your particular business needs, but we can look at the default steps to get a good idea of the typical workflow:
+
+![./order-state-diagram-for-admin.png](./order-state-diagram-for-admin.png)
+
+When a new Order arrives, you would:
+
+1. **Settle the payment** if not already done (this may or may not be needed depending on the way your payment provider is configured).
+    ![./screen-settle-payment.webp](./screen-settle-payment.webp)
+1. **Create a Fulfillment** by clicking the "Fulfill Order" button in the top-right of the order detail page. A Fulfillment represents the physical package which will be sent to the customer. You may split up your order into multiple Fulfillments, if that makes sense from a logistical point of view.
+    ![./screen-fulfillment.webp](./screen-fulfillment.webp)
+1. **Mark the Fulfillment as "shipped"** once the physical package leaves your warehouse. 
+1. **Mark the Fulfillment as "delivered"** once you have notice of the package arriving with the customer. 
+   ![./screen-fulfillment-shipped.webp](./screen-fulfillment-shipped.webp)
+
+## Refunds
+
+You can refund one or more items from an Order by clicking this menu item, which is available once the payments are settled:
+
+![./screen-refund-button.webp](./screen-refund-button.webp)
+
+This will bring up a dialog which allows you to select which items to refund, as well as whether to refund shipping. You can also make an arbitrary adjustment to the refund amount if needed.
+
+A Refund is then made against the payment method used in that order. Some payment methods will handle refunds automatically, and others will expect you to perform the refund manually in your payment provider's admin interface, and then record the fact manually.
+
+## Cancellation
+
+One or more items may also be cancelled in a similar way to how refunds are handled. Performing a cancellation will return the selected items back into stock.
+
+Cancellations and refunds are often done together, but do not have to be. For example, you may refund a faulty item without requiring the customer to return it. This would be a pure refund.
+
+## Modifying an Order
+
+An Order can be modified after checkout is completed. 
+
+![./screen-modify-button.webp](./screen-modify-button.webp)
+
+Modification allows you to:
+
+* Alter the quantities of any items in the order
+* Remove items from the order  
+* Add new items to the order
+* Add arbitrary surcharges or discounts
+* Alter the shipping & billing address
+
+![./screen-modification.webp](./screen-modification.webp)
+
+Once you have made the desired modifications, you preview the changes including the price difference.
+
+If the modifications have resulted in an increased price (as in the above example), the Order will then be set into the "Arranging additional payment" state. This allows you to process another payment from the customer to make up the price difference.
+
+On the other hand, if the new price is less than what was originally paid (e.g. if the quantity is decreased), then a Refund will be generated against the payment method used.
+
+
+

package/docs/user-guide/promotions/index.md

@@ -0,0 +1,44 @@
+---
+title: "Promotions"
+weight: 4
+---
+
+# Promotions
+
+Promotions are a means of offering discounts on an order based on various criteria. A Promotion consists of _conditions_ and _actions_.
+
+* **conditions** are the rules which determine whether the Promotion should be applied to the order.
+* **actions** specify exactly how this Promotion should modify the order.
+
+## Promotion Conditions
+
+A condition defines the criteria that must be met for the Promotion to be activated. Vendure comes with some simple conditions provided which enable things like:
+
+* If the order total is at least $X
+* Buy at least X of a certain product
+* Buy at least X of any product with the specified [FacetValues](/user-guide/catalog/facets)
+* If the customer is a member of the specified [Customer Group](/user-guide/customers#customer-groups)
+
+Vendure allows completely custom conditions to be defined by your developers, implementing the specific logic needed by your business.
+
+## Coupon codes
+
+A coupon code can be any text which will activate a Promotion. A coupon code can be used in conjunction with conditions if desired.
+
+
+:::note
+Note: Promotions **must** have either a **coupon code** _or_ **at least 1 condition** defined.
+:::
+
+## Promotion Actions
+
+If all the defined conditions pass (or if the specified coupon code is used), then the actions are performed on the order. Vendure comes with some commonly-used actions which allow promotions like:
+
+* Discount the whole order by a fixed amount
+* Discount the whole order by a percentage
+* Discount selected products by a percentage
+* Free shipping
+
+## Coupon code per-customer limit
+
+If a per-customer limit is specified, then the specified coupon code may only be used that many times by a single Customer. For guest checkouts, the "same customer" status is determined by the email address used when checking out.

package/docs/user-guide/settings/administrators-roles.md

@@ -0,0 +1,34 @@
+---
+title: "Administrators & Roles"
+---
+
+# Administrators & Roles
+
+An **administrator** is a staff member who has access to the Admin UI, and is able to view and modify some or all of the items and settings.
+
+The exact permissions of _what_ a given administrator may view and modify is defined by which **roles** are assigned to that administrator.
+
+## Defining a Role
+
+The role detail page allows you to create a new role or edit an existing one. A role can be thought of as a list of permissions. Permissions are usually divided into four types:
+
+* **Create** allows you to create new items, e.g. "CreateProduct" will allow one to create a new product.
+* **Read** allows you to view items, but not modify or delete them.
+* **Update** allows you to make changes to existing items, but not to create new ones.
+* **Delete** allows you to delete items.
+
+Vendure comes with a few pre-defined roles for commonly-needed tasks, but you are free to modify these or create your own.
+
+In general, it is advisable to create roles with the fewest amount of privileges needed for the staff member to do their jobs. For example, a marketing manager would need to be able to create, read, update and delete promotions, but probably doesn't need to be able to update or delete payment methods.
+
+### The SuperAdmin role
+
+This is a special role which cannot be deleted or modified. This role grants _all permissions_ and is used to set up the store initially, and make certain special changes (such as creating new Channels).
+
+## Creating Administrators
+
+For each individual that needs to log in to the Admin UI, you should create a new administrator account. 
+
+Apart from filling in their details and selecting a strong password, you then need to assign at least one role. Roles "add together", meaning that when more than one role is assigned, the combined set of permissions of all assigned roles is granted to that administrator. 
+
+Thus, it is possible to create a set of specific roles "Inventory Manager", "Order Manager", "Customer Services", "Marketing Manager", and _compose_ them together as needed.

package/docs/user-guide/settings/channels.md

@@ -0,0 +1,18 @@
+---
+title: "Channels"
+---
+
+# Channels
+
+Channels allow you to split your store into multiple sub-stores, each of which can have its own selection of inventory, customers, orders, shipping methods etc.
+
+There are various reasons why you might want to do this:
+
+* Creating distinct stores for different countries, each with country-specific pricing, shipping and payment rules.
+* Implementing a multi-tenant application where many merchants have their own store, each confined to its own channel.
+* Implementing a marketplace where each seller has their own channel.
+
+Each channel defines some basic default settings - currency, language, tax options.
+
+There is _always_ a **default channel** - this is the "root" channel which contains _everything_, and any sub-channels can then contain a subset of the contents of the default channel.
+  

package/docs/user-guide/settings/countries-zones.md

@@ -0,0 +1,12 @@
+---
+title: "Countries & Zones"
+---
+
+# Countries & Zones
+
+**Countries** are where you define the list of countries which are relevant to your operations. This does not only include those countries you ship to, but also those countries which may appear on a billing address.
+
+By default, Vendure includes all countries in the list, but you are free to remove or disable any that you don't need.
+
+**Zones** provide a way to group countries. Zones are used mainly for defining [tax rates](/user-guide/settings/taxes) and can also be used in shipping calculations.
+

package/docs/user-guide/settings/global-settings.md

@@ -0,0 +1,12 @@
+---
+title: "Global Settings"
+---
+
+# Global Settings
+
+The global settings allow you to define certain configurations that affect _all_ channels.
+
+* **Available languages** defines which languages you wish to make available for translations. When more than one language has been enabled, you will see the language switcher appear when viewing translatable objects such as products, collections, facets and shipping methods.
+  ![./screen-translations.webp](./screen-translations.webp)
+* **Global out-of-stock threshold** sets the stock level at which a product variant is considered to be out of stock. Using a negative value enables backorder support. This setting can be overridden by individual product variants (see the [tracking inventory](/user-guide/catalog/products#tracking-inventory) guide).
+* **Track inventory by default** sets whether stock levels should be tracked. This setting can be overridden by individual product variants (see the [tracking inventory](/user-guide/catalog/products#tracking-inventory) guide).

package/docs/user-guide/settings/payment-methods.md

@@ -0,0 +1,32 @@
+---
+title: "Payment Methods"
+---
+
+# Payment Methods
+
+Payment methods define how your storefront handles payments. Your storefront may offer multiple payment methods or just one.
+
+A Payment method consists of two parts: an **eligibility checker** and a **handler**
+
+## Payment eligibility checker
+
+This is an optional part which can be useful in certain situations where you want to limit a payment method based on things like:
+
+* Billing address
+* Order contents or total price
+* Customer group
+
+Since these requirements are particular to your business needs, Vendure does not provide any built-in checkers, but your developers can create one to suit your requirements.
+
+## Payment handler
+
+The payment handler contains the actual logic for processing a payment. Again, since there are many ways to handle payments, Vendure only provides a "dummy handler" by default and it is up to your developers to create integrations. 
+
+Payment handlers can be created which enable payment via:
+
+* Popular payment services such as Stripe, Paypal, Braintree, Klarna etc
+* Pay-on-delivery
+* Store credit
+* etc
+
+

package/docs/user-guide/settings/shipping-methods.md

@@ -0,0 +1,55 @@
+---
+title: "Shipping Methods"
+---
+
+# Shipping Methods
+
+Shipping methods define:
+
+* Whether an order is eligible for a particular shipping method
+* How much the shipping should cost for a given order
+* How the order will be fulfilled
+
+Let's take a closer look at each of these parts:
+
+## Shipping eligibility checker
+
+This is how we decide whether a particular shipping method may be applied to an order. This allows you to limit a particular shipping method based on things like:
+
+* Minimum order amount
+* Order weight
+* Shipping destination
+* Particular contents of the order
+* etc.
+
+By default, Vendure comes with a checker which can impose a minimum order amount. To implement more complex checks, your developers are able to create custom checkers to suit your requirements.
+
+## Shipping calculator
+
+The calculator is used to determine how much to charge for shipping an order. Calculators can be written to implement things like:
+
+* Determining shipping based on a 3rd-party service such as Shippo
+* Looking up prices from data supplied by couriers
+* Flat-rate shipping
+
+By default, Vendure comes with a simple flat-rate shipping calculator. Your developers can create more sophisticated integrations according to your business requirements.
+
+## Fulfillment handler
+
+By "fulfillment" we mean how we physically get the goods into the hands of the customer. Common fulfillment methods include:
+
+* Courier services such as FedEx, DPD, DHL, etc.
+* Collection by customer
+* Delivery via email for digital goods or licenses
+
+By default, Vendure comes with a "manual fulfillment handler", which allows you to manually enter the details of whatever actual method is used. For example, if you send the order by courier, you can enter the courier name and parcel number manually when creating an order.
+
+Your developers can however create much more sophisticated fulfillment handlers, which can enable things like automated calls to courier APIs, automated label generation, and so on.
+
+## Testing a Shipping Method
+
+At the bottom of the shipping method **detail page** you can test the current method by creating a fake order and shipping address and testing a) whether this method would be eligible, and b) how much it would cost.
+
+![./screen-shipping-test.webp](./screen-shipping-test.webp)
+
+Additionally, on the shipping method **list page** you can test _all_ shipping methods at once.

package/docs/user-guide/settings/taxes.md

@@ -0,0 +1,32 @@
+---
+title: "Taxes"
+---
+
+# Taxes
+
+Taxes represent extra charges on top of the base price of a product. There are various forms of taxes that might be applicable, depending on local laws and the laws of the regions that your business serves. Common forms of applicable taxes are:
+
+* Value added tax (VAT)
+* Goods and services tax (GST)  
+* Sales taxes (as in the USA)
+
+
+## Tax Category
+
+In Vendure every product variant is assigned a **tax category**. In many countries, different rates of tax apply depending on the type of product being sold.
+
+For example, in the UK there are three rates of VAT:
+
+* Standard rate (20%)
+* Reduced rate (5%)
+* Zero rate (0%)
+
+Most types of products would fall into the "standard rate" category, but for instance books are classified as "zero rate".
+
+## Tax Rate
+
+Tax rates set the rate of tax for a given **tax category** destined for a particular **zone**. They are used by default in Vendure when calculating all taxes.
+
+## Tax Compliance
+
+Please note that tax compliance is a complex topic that varies significantly between countries. Vendure does not (and cannot) offer a complete out-of-the-box tax solution which is guaranteed to be compliant with your use-case. What we strive to do is to provide a very flexible set of tools that your developers can use to tailor tax calculations exactly to your needs. These are covered in the [Developer's guide to taxes](/guides/core-concepts/taxes/). 

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@vendure/docs",
+    "version": "0.0.0-202601161541",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js",
+        "./manifest": "./dist/manifest.js"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "docs"
+    ],
+    "scripts": {
+        "build": "rimraf dist && tsc -p ./tsconfig.build.json",
+        "prepublishOnly": "npm run build",
+        "publish:local": "npm version 0.0.0-$(date +%Y%m%d%H%M) --no-git-tag-version && npm publish",
+        "publish:local:next": "npm version 0.0.0-$(date +%Y%m%d%H%M) --no-git-tag-version && npm publish --tag next",
+        "typecheck": "tsc"
+    },
+    "dependencies": {
+        "@vendure-io/docs-provider": "^0.2.0"
+    },
+    "devDependencies": {
+        "rimraf": "^5.0.5",
+        "typescript": "5.8.2"
+    }
+}