WordPress Advanced Guide

This guide includes more in-depth topics on how to use Verge3D with WordPress. It describes how to send orders and forms in background and customize the plugin. Also you'll find the formal e-commerce protocol specification here. For basic topics please refer to the WordPress Plugin section of the User Manual.

Receiving Orders in Background via REST API

In some cases you might want to create custom experience for placing orders instead of redirecting users to the order page.

Say you want to create a basic table customizer. This is how your data might look like:


    {
        "user_name": "John Smith",
        "user_email": "john.smith@example.com",
        "user_phone": "+123456789"
        "items": [
            {
                "sku": "table_top_white",
                "quantity": 1
            },
            {
                "sku": "table_leg_brown",
                "quantity": 4
            },
        ]
    }

You have two options to make an order based on this data:

By using POST request with regular form data (version v1)
By using POST request with JSON (version v2)

Submitting Orders with Form Data

To do this, you might compose an HTML form with the fields specified above and then submit it directly or via send data puzzle to the following address:

https://WP_HOST/wp-json/verge3d/v1/place_order/

Where WP_HOST is the host name of your WordPress server, such as sandbox.soft8soft.com

With puzzles, the form fields which require user input (i.e. "user_name", "user_email", "user_phone") can be created as follows:

While order items with product SKUs can be composed with hidden form inputs:

The form can be submitted without reloading the entire page as follows:

Submitting Orders with JSON

You can compose this structure by creating a JavaScript object and then send it to the server via JavaScript fetch() call, however using dictionary along with send data puzzle might be easier.

The URL address for submitting orders in JSON format is:

https://WP_HOST/wp-json/verge3d/v2/place_order/

Where WP_HOST is the host name of your WordPress server, such as sandbox.soft8soft.com

For example, use the following puzzles to compose the order specified above:

The order item puzzle from the E-Commerce tab might save you some time when composing order items.

Sending Forms to Email

Verge3D for WordPress offers a feature which allows you to send data obtained from custom HTML forms to an email address specified in admin settings. For example, you can use this to receive inquiries or support questions for your products or services, implementing preorders, obtaining customer's contact info, etc.

The URL address for submitting custom forms is:

https://WP_HOST/wp-json/verge3d/v1/send_form/

Where WP_HOST is the host name of your WordPress server, such as sandbox.soft8soft.com.

The form itself can be implemented with HTML/CSS, Puzzles, or a website builder, like Webflow. See here for more info on creating HTML-based UI. Form submission is performed directly, by clicking on the "Submit" button, or indirectly, via JavaScript/Puzzles (to avoid page reload).

For example, by using Puzzles, you can send the form without reloading the page like that (actual form construction is not shown):

The Inquiry Form library can simplify things a lot. Use it as a basis for your own form solutions.

Customizing E-Commerce Forms

To modify e-commerce forms copy the form templates located in the templates directory of the Verge3D plugin to your WordPress theme directory under the verge3d subdirectory.

For example, if you need to modify order email template:

WORDPRESS/wp-content/plugins/verge3d/templates/order_email_body.php → THEME/verge3d

Where WORDPRESS is the root directory of your WordPress installation and THEME is the directory of your current theme.

Here is the list of templates you can customize:

Template File	Description
order_email_body.php	Order email body template. This template used both for order notifications sent to you and to your customers.
order_pdf.php	Order email PDF attachment template. This template is used to generate HTML files which will be converted to PDF and attached to order emails (e.g. quotes and invoices).
order_form.php	Order form template. This form is displayed to you customers on the pages where [verge3d_order] shortcode is present.
order_success.php	Message displayed when the order was accepted.
order_failed.php	Message displayed when the order was rejected.
payment_paypal.php	Page for PayPal payment processing.
send_form_email_body.php	Email template for forms generated by REST API.

Security Measures

When using custom forms for your e-commerce applications be sure to properly escape output data sent by your customers. Use the following guide for more info.

E-commerce Protocol Specification

The place order and place order + puzzles use the following protocol to handle orders. Orders are sent from the browser to server using HTTP POST requests with the following parameters:

POST parameters	Description
v3d_items	Order items. A JSON-encoded array with order items.
v3d_attachments[]	Order attachments. This optional value must be an array of Data URLs representing order attachments.

The order item has one of the following formats, depending on the puzzle you use. For place order:

Fields	Description
title	Order item title.
price	Order item price.
quantity	Order item quantity: number of units, weight, length, etc.

For place order +:

Fields	Description
sku	Order item SKU (stock keeping unit). This SKU is used as an ID to retrieve information about the product from the server.
quantity	Order item quantity: number of units, weight, length, etc.

The more advanced protocol based on REST API uses the following set of parameters:

JSON fields	Description
user_name	Customer's full name (also used as billing name).
user_email	Customer's e-mail address.
user_phone	Customer's phone number.
user_comment	Optional order comments.
items	Order items. An array with order items.
attachments	Order attachments. This optional value must be an array of Data URLs representing order attachments.
user_address1	Billing address — line 1. In order to use this field, activate the Billing address option on the General tab.
user_address2	Billing address — line 2. In order to use this field, activate the Billing address option on the General tab.
user_city	Billing address — city. In order to use this field, activate the Billing address option on the General tab.
user_state	Billing address — state, county, or province. In order to use this field, activate the Billing address option on the General tab.
user_country	Billing address — country. In order to use this field, activate the Billing address option on the General tab.
user_postcode	Billing address — postcode/ZIP. In order to use this field, activate the Billing address option on the General tab.
shipping_address1	Shipping address — line 1. In order to use this field, activate the Shipping address option on the General tab.
shipping_address2	Shipping address — line 2. In order to use this field, activate the Shipping address option on the General tab.
shipping_city	Shipping address — city. In order to use this field, activate the Shipping address option on the General tab.
shipping_state	Shipping address — state, county, or province. In order to use this field, activate the Shipping address option on the General tab.
shipping_country	Shipping address — country. In order to use this field, activate the Shipping address option on the General tab.
shipping_postcode	Shipping address — postcode/ZIP. In order to use this field, activate the Shipping address option on the General tab.

Got Questions?

Feel free to ask on the forums!