Commerce

From docs.warpcs.org

This is the documentation for warp CS Commerce (ec.warpcs.com). Also see https://ec.warpcs.com/about.jspx.

Businesses

Register Business

To start, click "Register new business" at the bottom of the "Manage Businesses" tab.

You will be asked to enter the registered business name and address. Only some countries are supported for businesses. During the verification process, the given data might be slightly modified for correctness.

After you click "Start Registration", an unverified business entry will be created and you must contact support to complete the registration process. For this, simply send an email to the contact email address under "About This Page", including the shown "Internal ID" and proof of registration documents. Which documents exactly depends on the type of business (see below). After the check is complete, your business is marked verified and you can start using it on the platform.

Required Documents

Germany

  • Handelsgesellschaften (GmbH, AG, UG, OHG, ...) oder e.K.: Handelsregisterauszug
  • Personengesellschaften (Einzelunternehmen, GbR, ..., außer PartG): Gewerbeanmeldung von der Stadt oder Gemeinde
  • Freiberufler: Umsatzsteuer-Voranmeldung oder Einkommensteuerbescheid
  • Partnerschaftsgesellschaft: Partnerschaftsregisterauszug
  • eingetragener Verein: Vereinsregisterauszug
  • Stiftung: Stiftungsurkunde

Bei manchen Rechtsformen darf der angegebene Name Zusätze enthalten (z.B. Einzelunternehmen).

Manage Business

General

The first two options are the registered business name and address. To request changes for these, contact support.

Other settings are described next to the input field.

Management

See description next to inputs.

Attributes

The following attributes are defined (important: names are case-sensitive, but all defined attributes are lowercase):

  • website: Link to the business website. Will be shown on invoices.
  • telephone: Business phone number. Will be shown on invoices.
  • email: Support email address. This is the email address shown in order details and on invoices, overriding the email address set in General settings above.
  • vatid: Wikipedia:VAT identification number of the business. If and under what conditions this is required for order completion depends on the business country. Has the highest preference on invoices among vatid, taxid, and taxnumber, meaning if all are defined, this is the only value shown.
  • taxid: Country-specific tax ID of the business. Has medium preference on invoices.
  • taxnumber: Tax number (German "Steuernummer") of the business. Has the lowest preference on invoices.
  • tax_exemption: If this is set to any value, no VAT calculation will be shown on invoices due to the business charging no VAT. Similar to setting "Tax Percentage" of all products of the business to -1. A generic note will be put on the invoice to indicate this, if the value is not instead equal to some special value used to reference specific legal documents: "kleinunternehmer" (references German § 19 UStG).
  • owner: Name of the business owner. Will be shown on invoices, only for information purposes.
  • ceo: Name of the CEO, overrides owner. Will be shown on invoices, only for information purposes.
  • tradename: The trade name of the business. Overrides the prominently shown registered business name on invoices, although the registered name is always also on the invoice.
  • invoice_language: Language ID of the language to generate invoices in, a lowercase two-letter language code (e.g. "en", "de"). Overrides the default behavior, which is to use the language of the businesses country or a default.
  • invoice_note: Any small note added to the end of the invoice, after the item list. May contain "\n" for line breaks.
  • invoice_auto_regenerate: If exists (value is ignored), the invoice is automatically regenerated if an order is marked as paid (PAID event; both automatically or manually).
  • invoice_transfer_reference: The format of the reference string embedded in the QR code for a manual transfer. Any string, and "??" is replaced by the order number of the order being paid. Default is "??". The QR code is shown on the order overview page if the "Bank Transfer" payment option was chosen, and after clicking "Pay" if the business allows bank transfer payments.
  • shipping_cost: The default shipping cost in the used currency.
  • shipping_cost_*: More specific shipping cost configuration. See below under "Products" for more information.
  • shipping_restrict_countries: A comma-separated case-insensitive list of countries your business is willing to ship to. If a country not in this list is given as the shipping address during checkout, it cannot be completed. The special string "eu" may be included in the list to include all countries in the European Union. Example: eu,us,ca.
  • bank_iban: IBAN of business bank account. Will be shown on invoices and required to show a QR code for simpler payment.
  • bank_bic: BIC of business bank account. Will be shown on invoices.
  • banktransfer: If exists (value is ignored), enables payment using bank transfer. Using this method, an order will be completed and the invoice sent to the buyer. Be aware payment is not necessarily done yet when this is done. Some kind of bank information is required.
  • banktransfer_other: If exists (value is ignored), allows bank transfer payments even though no other bank information is given. You must inform the buyer about a way of payment.
  • prepaidbalance: If exists (value is ignored), enables payment using prepaid balance of the user. There should be a way for the user to add prepaid balance to their account.
  • prepaidbalance_add_pid: The product ID of the product that can be purchased by a user to top up a their prepaid balance. Is not required and is only shown on the prepaid balances overview page for the user's convenience.
  • prepaidbalance_pretaxed: If exists (value is ignored), prepaid balance added to this business is assumed to be taxed already, and all invoices paid with prepaid balance will not include a VAT calculation and a note to inform about this.
  • sepadirectdebit_webhookurl: Webhook URL for SEPA payment information during checkout. Enables the SEPA Direct Debit payment option if given together with sepadirectdebit_secret. The debit process must be initiated by the business. If a customer uses this payment option, the payment information entered by the customer is sent to the given URL as a webhook during the checkout process and must be handled by the business.
  • sepadirectdebit_secret: Any secret string sent along with the webhook, to prevent forged requests.
  • paypal_clientid: Client ID for PayPal API access. Enables PayPal Checkout if given together with paypal_secret. For testing with sandbox API credentials, prefix this value with sandbox:. IMPORTANT: Some payment methods with PayPal take some time to complete, and the payment in the order is first marked as "NOT paid (pending)". To make sure it is automatically set to "Paid" when the payment completes, you must add a PayPal API webhook in your PayPal account application settings. The webhook URL to set is https://ec.warpcs.com/api/orderm/checkoutexternalhook?source=paypal with all Event types starting with "Payment capture ..." (under "Payments & Payouts") enabled.
  • paypal_secret: Secret key for PayPal API access.
  • stripe_publickey: Stripe API Public Key. Enables Stripe Checkout if given together with stripe_secretkey.
  • stripe_secretkey: Stripe API Secret Key.

Requirements

None of the attributes are necessarily required for all businesses, although the following is recommended:

  • Set up any kind of payment option by setting the appropriate attributes.
  • Provide a website link, telephone number, or support email address so that buyers can contact you in case of issues.
  • Set a shipping_cost if your business will ship products.

Requirements: German Business

  • Either taxnumber or vatid must be specified to be able to process orders of 250€ or above.


Products

Products are representations of real products a business sells.

Create Product

A product can simply be created in the web interface. At creation, only the name must be specified. More settings can be configured after this.

Manage Product

General

Name and Icon URL are simply how the product is presented.

If Sale paused is checked, this product cannot be bought by a customer.

Linked Businesses

Here, you can select one or more products which sell the product. Only businesses for which you at least have management permissions are listed here. All managers of all businesses linked to the product have full configuration access to the product.

Base Price

The base unit price of the product. This can be further adapted using product parameters set by the customer (see below).

Tax Percentage

The percentage of tax (VAT) included in the configured price. This is only relevant for invoices, since the tax is already included in the price. This value may be 0 for tax-free products, or -1 if no VAT is charged by the business in some special cases (for example, the German Kleinunternehmerregelung).

Parameters

A list of parameters configurable by the customer while placing an order. These can, for example, be used to provide additional information to the seller business. Every parameter is either a string, number, or boolean. It has a configurable precedence, which determines the order the parameters are presented to the customer; parameters with higher precedence are shown first. The name can be any string, shown to the customer, and potentially on invoices. Validation is either a regex (if type is string), or a range in the format min-max (type number), where min and max (both inclusive) are both integers limiting the allowed range. The optional checkbox specifies whether this parameter must be configured by the customer. If On Invoice is checked, this parameter, including the value configured by the customer, is shown on the invoice.

Some parameter types (number, boolean) can have a math expression to adapt the effective price based on parameters configured by the customer. The math expression field can have one or more statements separated by a ;, each with the general format variable = expression, where variable is any variable name to be set, and expression is any math expression resulting in a number to which the left-hand variable is set to. An example for an expression is abs(variable) * 3 + 1. Variables carry over across all statements of all product parameters of a product. There are two special variables: price is read out after evaluating all statements of all parameters in the order given by the precedence and sets the final effective unit price of a configured order item, and this is unique for each product parameter and contains the current configured value (for booleans, this is 1 if checked and 0 otherwise). Full example for the math expression field: price *= this; price = price + 1.23.

Shipping Class

The shipping class of the product. See below in "Configure Shipping Cost" for more information.

Renewal Interval

If not 0, marks this product as a subscription, and the value is the renewal interval of the subscription, in days. Buying a subscription product requires a user account. See §C5f in the Terms for more information. If "Allow early renewals" is checked, the subscription cannot be renewed by the user before the current expiration time minus the renewal interval.

Technical

Actions

Actions are performed when something happens with this product, for example it is bought by a customer. There are different types of actions: "Buy" (initial purchase of a product or subscription), "Renew" (upon successful renewal of a subscription), and "Cancel" (when a subscription is cancelled or has ended). Similar to product parameters, they have a precedence, determining the order in which they are executed, but here higher ones are executed later. If any action fails, the execution of all actions for this order item (combination of product and configured parameters) is stopped and the order item state is set to ERROR including an error message. Finally, the URI determines the action:

  • http:// or https:// URLs specify a webhook to be sent to the given URL. Fails if a non-2xx status code is returned.
  • action: URIs have special internal meanings:
    • action:setState:<state> Changes the order item state to the given state, any of PENDING, PROCESSING, TRANSIT, COMPLETE.
    • action:complete Changes the order item state to COMPLETE.
    • action:setExternalId:<value> Sets the externalId of the order item, used for references in other applications (also sent as part of the webhook JSON object). The value can either be a fixed string, or "$" followed by a local variable name (see below).
    • action:addToPrepaidBalance:<expression> The numeric result of the given expression is added to the prepaid balance of the buyer. This requires a user account (check "Requires User Account" to enforce), otherwise this action fails.

Local variables of an order item are the combination of the product parameters and strings in responses of previous webhook requests. The product parameters are the initial variables, where the variable name is the name of the product parameter (string containing any characters), and the value is the configured parameter value. Then, for each webhook request, if the response is a JSON object, all key-value pairs with string values are added to the set of variables, and new variables with an existing name overwrite the previous value. For example, in some action URLs, the variable containing the value of product parameter "Param 1" can be accessed using "$Param 1", or "{Param 1}" if an expression is expected. In the latter, only variables with a numeric value are available.

Webhook Secret

Any string sent along with all action webhooks.

Requires User Account

If checked, user must be logged in to buy this product.

Configure Shipping Cost

The shipping cost of an order is determined by the country it is shipped to and the shipping class of the order. A shipping class is a number setting of products, and the shipping class of the product with the highest shipping class number in the order determines the shipping class of the order. Then, the shipping cost is determined from the configured business attributes. The first configured attribute value, which must be set to a decimal number, of the following attributes is taken as the order shipping cost, from highest to lowest precedence. [sclass] is the shipping class of the order and [cc] is the country code of the country being shipped to.

  • shipping_cost_[sclass]_[cc]
  • shipping_cost_[sclass]_eu if [cc] is a country in the European Union.
  • shipping_cost_[sclass]_international if [cc] is not equal to the country of the business address.
  • shipping_cost_[cc]
  • shipping_cost_eu if [cc] is a country in the European Union.
  • shipping_cost_international if [cc] is not equal to the country of the business address.
  • shipping_cost_[sclass]
  • shipping_cost

If none of these are set (to a decimal number), the shipping cost will be 0.


Sale and Management

Order Configure Page

To sell a product, you must direct the customer to the configure page, so that they can add the product to their cart and continue with checkout. The order configure page of a particular product is https://ec.warpcs.com/order/configure.jspx?p=[bid]/[pid], where [bid] is the ID of your business and [pid] the ID of the product (each shown under Internal ID on the management page). The combination of [bid]/[pid] is referred to as [iid]. You can add an additional query parameter to set the language when a user first visits the page: &il=[lc], where [lc] is a two-letter lowercase language code, such as en or de.

After Checkout

After a customer placed an order for your business, you will get a notification via email. Make sure the email address is functional! In it, there is a link to the order overview page. You can also view a list of all order for your business under "View Orders" on the left a described below.

List of Orders

Under "View Orders", you can view a list of all order for your business. Be careful to not view your own placed orders, but orders for your business; it is stated at the top of the page. Each entry shows the time, order content summary, order number, seller, and status of buyer and seller completion. A green "B" next to the order number means the buyer has completed (i.e. paid), and a green "S" means the seller has completed (i.e. provided all products or services). The goal is for both to be complete, others will have a note in the top right of the box saying something is not complete.

Order Overview Page

The order overview page, accessible over the link in the email or the list of orders, shows all information about an order. This includes addresses, statuses, and a list of included items. At the top right, there is a button to open the invoice PDF file. If a business has provided shipping tracking links, these are also linked using buttons below the invoice; there may be multiple in case the order is split up into multiple packages.

"Completed (seller)" becomes "Yes" if all items are set to COMPLETED by the business. "Completed (buyer)" says "Paid" if the payment is complete; some payment methods take some time to complete, in this case the status is "NOT paid (pending)" until the payment is completed.

A user with management permissions also has permissions to change details of the order, as described in the next subsections.

Regenerate Invoice

If Regenerate Invoice is checked, the invoice PDF file is regenerated when clicking the View Invoice button. There can be any reason to do this, but be aware that details on the invoice might change, for example the invoice issue date, and names, parameter names, or images, in case you changed some of these settings of your business or products.

Shipping Update

Under Shipping tracking links, you can provide one or more tracking links for packages (separated by a space). After adding this, you can also notify the buyer via email that their package, containing all or part of their order, is on the way. You need to have at least one item with status TRANSIT to do this.

Order Item Status

For each of the items in the order, you can change the status of the order item to one of the following: PROCESSING (you are working on completing this order item), TRANSIT (the package containing this item is on the way), COMPLETE (the services or products were fulfilled). This changes the shown status on the overview page, but does not notify the buyer further, via email or something.

You can also press Claim responsibility to let other business managers know that you will complete this order item. This will be filled with the name in your account, and is only visible to other users with management permissions.

Retrieved from "https://docs.warpcs.org/wiki/w/index.php?title=Commerce&oldid=73"