Documentation
Feedback
Guides

Order Configuration

The Order Configuration app, designed for B2B scenarios, displays a form responsible for collecting order data in a modal.

{"base64":"  ","img":{"width":2859,"height":1502,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":2640505,"url":"https://user-images.githubusercontent.com/52087100/91925199-e5125200-ecaa-11ea-8734-f98921ddb384.gif"}}

Once the form is submitted, the order data collected will be available at Master Data and saved in the current VTEX session.

This app can be used to enable customization of all kinds of behaviors, such as custom prices, custom products, etc. Keep in mind the Order Configuration app does not offer these functionalities, it only enables other apps to do so.

Follow the steps below to install and set up the Order Configuration app in your store.

Step 1: Install the app

First, you must add the order-configuration app to your theme's dependencies in the manifest.json file:


_10
dependencies: {
_10
"vtex.order-configuration": "2.x"
_10
}

This will enable you to use the blocks exported by the order-configuration app. Check out the full list below:

Block nameDescription
order-configParent block only responsible for rendering its children blocks, that in turn build the Order Configuration component.
order-config.titleRenders the component title, that is, the message text displayed for users to present the component. On the image above, the component title is Order Configuration.
order-config.modalRenders the modal responsible for displaying the component content.
order-config.formRenders the component content, that is, a form to be filled out by users.

Step 2: Declare the required blocks

Add the order-config block in the Header component, as shown in the example below.


_24
{
_24
"header-layout.desktop": {
_24
"children": [
_24
"flex-layout.row#1-desktop",
_24
"flex-layout.row#2-desktop",
_24
"flex-layout.row#3-desktop",
_24
"sticky-layout#4-desktop"
_24
]
_24
},
_24
"flex-layout.row#3-desktop": {
_24
"props": {
_24
"blockClass": "menu-link",
_24
"horizontalAlign": "center",
_24
"preventHorizontalStretch": true,
_24
"preventVerticalStretch": true,
_24
"fullWidth": true
_24
},
_24
"children": [
_24
"vtex.menu@2.x:menu#websites",
_24
"flex-layout.col#spacer",
_24
+ "order-config#header",
_24
"vtex.menu@2.x:menu#institutional"
_24
]
_24
},

Then, declare the order-config#header block and its children blocks: order-config.title and order-config.modal. Example:


_57
{
_57
"order-config#header": {
_57
"children": [
_57
"order-config.title#header",
_57
"order-config.modal#header"
_57
],
_57
"props": {
_57
"blockClass": "header",
_57
"formFields": [
_57
{
_57
"name": "orderType",
_57
"type": "string",
_57
"fieldType": "radio",
_57
"label": "Order Type",
_57
"defaultValue": "resale",
_57
"options": [
_57
{
_57
"label": "Resale",
_57
"value": "resale"
_57
},
_57
{
_57
"label": "Consumption",
_57
"value": "consumption"
_57
}
_57
]
_57
},
_57
{
_57
"name": "state",
_57
"type": "string",
_57
"fieldType": "select",
_57
"label": "State",
_57
"showInTitle": true,
_57
"options": [
_57
{
_57
"label": "ES",
_57
"value": "ES"
_57
},
_57
{
_57
"label": "SP",
_57
"value": "SP"
_57
}
_57
]
_57
}
_57
]
_57
}
_57
},
_57
"order-config.modal#header": {
_57
"children": [
_57
"order-config.form"
_57
]
_57
},
_57
"order-config.title#header": {
_57
"props": {
_57
"formTitle": "Order Configuration for Header"
_57
}
_57
},
_57
}

If the order-config.form block does not have any children configured, a default form will be rendered automatically based on the React Hook Form JSON Schema library. To declare children blocks according to your business needs, check out the Advanced configuration section below.

Step 3: Create main schema in Master Data

You must create a schema named main in Master Data, using the order_configuration data entity.

You can place a request using the Save schema by name endpoint of the Master Data v2 API to do so.

The schema should contain all the data that you added in the form above, otherwise the data will not be persisted.

Request body example


_24
{
_24
"v-cache": false,
_24
"properties": {
_24
"clientId": {
_24
"type": "string"
_24
},
_24
"orderType": {
_24
"type": "string"
_24
},
_24
"state": {
_24
"type": "string"
_24
}
_24
},
_24
"v-default-fields": [
_24
"clientId",
_24
"orderType",
_24
"state"
_24
],
_24
"v-indexed": [
_24
"clientId",
_24
"orderType",
_24
"state"
_24
]
_24
}

Refer to Master Data API - v2 documentation for more details.

Step 4: Update orderForm configuration

It is also necessary to configure a new app in the orderForm.

First, place a GET Get orderForm configuration request to retrieve the current orderForm settings before updating them. By doing so you ensure that you will only change the properties you want in the next step.

Then, place a POST Update orderForm configuration request, setting the following object inside the apps object in the request body:


_10
{
_10
"fields": [
_10
"values"
_10
],
_10
"id": "orderconfig",
_10
"major": 1
_10
}

Request body example


_35
{
_35
"paymentConfiguration": {
_35
"requiresAuthenticationForPreAuthorizedPaymentOption": false,
_35
"allowInstallmentsMerge": null,
_35
"blockPaymentSession": null,
_35
"paymentSystemToCheckFirstInstallment": null,
_35
"defaultPaymentSystemToApplyOnUserOrderForm": null
_35
},
_35
"taxConfiguration": null,
_35
"minimumQuantityAccumulatedForItems": 1,
_35
"decimalDigitsPrecision": 2,
_35
"minimumValueAccumulated": null,
_35
"apps": [
_35
{
_35
"fields": [
_35
"quoteId"
_35
],
_35
"id": "b2b-quotes-graphql",
_35
"major": 1
_35
},
_35
{
_35
"fields": [
_35
"values"
_35
],
_35
"id": "orderconfig",
_35
"major": 1
_35
}
_35
],
_35
"allowMultipleDeliveries": true,
_35
"allowManualPrice": true,
_35
"maxNumberOfWhiteLabelSellers": null,
_35
"maskFirstPurchaseData": null,
_35
"recaptchaValidation": "vtexcriteria",
_35
"maskStateOnAddress": true
_35
}

You can refer to Checkout API documentation for more information.

Advanced configuration

If desired, you can declare the order-config.form block by adding and configuring the formFields prop and an array of form children blocks (whose descriptions you can find below).


_92
{
_92
"order-config#static-page": {
_92
"props": {
_92
"formFields": [
_92
{
_92
"name": "orderType",
_92
"type": "string",
_92
"fieldType": "select",
_92
"label": "Order Type",
_92
"defaultValue": "res",
_92
"showInTitle": true,
_92
"options": [
_92
{
_92
"label": "Resale",
_92
"value": "res"
_92
},
_92
{
_92
"label": "Consumption",
_92
"value": "cons"
_92
}
_92
]
_92
},
_92
{
_92
"name": "state",
_92
"type": "string",
_92
"fieldType": "select",
_92
"label": "State",
_92
"showInTitle": true,
_92
"required": true,
_92
"options": [
_92
{
_92
"label": "ES",
_92
"value": "ES"
_92
},
_92
{
_92
"label": "SP",
_92
"value": "SP"
_92
}
_92
]
_92
},
_92
{
_92
"name": "someTextInput",
_92
"label": "Some Text Input",
_92
"fieldType": "input",
_92
"type": "string",
_92
"required": true,
_92
"showInTitle": true
_92
}
_92
]
_92
},
_92
"children": [
_92
"order-config.title#static-page",
_92
"order-config.form#static-page"
_92
]
_92
},
_92
"order-config.form#static-page": {
_92
"children": [
_92
"flex-layout.row#state-and-payment-method",
_92
"order-config.text#some-text-input",
_92
"order-config.submit"
_92
]
_92
},
_92
"flex-layout.row#state-and-payment-method": {
_92
"children": [
_92
"order-config.dropdown#state",
_92
"order-config.radiogroup#payment-method"
_92
],
_92
"props": {
_92
"blockClass": "stateAndPaymentMethod"
_92
}
_92
},
_92
"order-config.dropdown#state": {
_92
"props": {
_92
"pointer": "#/properties/state"
_92
}
_92
},
_92
"order-config.radiogroup#payment-method": {
_92
"props": {
_92
"pointer": "#/properties/paymentMethod"
_92
}
_92
},
_92
"order-config.text#some-text-input": {
_92
"props": {
_92
"pointer": "#/properties/someTextInput"
_92
}
_92
},
_92
"order-config.title#static-page": {
_92
"props": {
_92
"formTitle": "Order Configuration for Static Page"
_92
}
_92
}
_92
}

Block nameDescription
order-config.submitRenders a Submit button.
order-config.dropdownRenders the a dropdown field.
order-config.radiogroupRenders a radiogroup field.
order-config.textRenders a text field.
order-config.textareaRenders a text field with a wider range of available characters.
order-config.checkboxRenders a checkbox field.

Props

Check out the description of the available props below.

Prop nameTypeDescriptionDefault ValueBlock name
pointerstringPath to which the block must point in the formFields prop in order to properly work.undefinedorder-config.dropdown, order-config.radiogroup, order-config.text, order-config.textarea, and order-config.checkbox
formFieldsobjectObject responsible for defining the form fields.undefinedorder-config.form

The formFields object contains the following props:

Prop nameTypeDescriptionDefault Value
namestringName of the field (only used as an identifier in your code).undefined
typeenumValue type accepted by the field. Possible values are string and number.string
fieldTypeenumInput type accepted by the field. Possible values are: text, textarea, select, radio, and checkbox.text
labelstringField name shown to users.undefined
showInTitlebooleanWhether to display the value type accepted by the field on its name (true) or not (false).false
optionsobjectField options to be defined in case select, radio, or checkbox values were declared in the fieldType prop.undefined

The options object contains the following props:

Prop nameTypeDescriptionDefault Value
labelstringOption name shown to users.undefined
valuestringOption value.undefined

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
formSubmitButton
formSubmitContainer
formErrorServer
formErrorUserInput
loader
orderConfigFormWrapper
formObject
title
titleValues
titleWrapper
wrapper
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest Edits (GitHub)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page