WordPress Advanced Guide

This guide includes more in-depth topics on how to use Verge3D with WordPress, including customization of WordPress plugin, e-commerce protocol specification, etc. For basic topics please refer to the WordPress Plugin section of the User Manual.

Receving 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 can compose this structure by creating a JavaScript object and then send it to the server via XMLHttpRequest, however using dictionary along with send data puzzle might be easier.

To do this, assign a proper URL for your "send data" puzzle. This one looks like:

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

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

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.
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.

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 URIs 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 JSON-based protocol 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 URIs 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?