Add required information

📝 Note
Add the required form to products configured for a combined purchase (end users must purchase or provide a domain during the purchase flow).

Developers can configure custom forms to collect information from end users when they purchase products. During checkout and assisted sales with the Opportunities feature, the data collection forms appear so that end users can enter the required information.

For each form, configure content including a form title and description, display preferences, and fields to collect each of the data elements from end users.

You can also configure a product settings validation URL, to which AppDirect sends the collected data for validation. If the validation fails, the checkout process does not progress, and an error message directs end users to correct the invalid entries.

During the initial purchase flow, the data collection forms appear and end users enter the required information. When an end user changes a subscription, the required information they entered at the time of the initial purchase is automatically added during the purchase flow.

To add a required information form

1. Complete one of the following actions:
   1. If you are on the Edit Integration page, click Add Required Info.
   2. From any other location, go to Manage > Billing and Distribution > Products > productName | Edit > Integration | Edit Integration > Add Required Info. The product settings section appears.
      1. When you click Add Required Info, the Additional product settings required during checkout setting is automatically selected. A checkbox and text appears under the Subscription Change Notification URL field. You can disable the setting.
         1. When this setting is enabled, a form is displayed during the checkout flow for the purchase of a new subscription and for a subscription change. End users will need to complete the form.
         2. When this setting is disabled, a form is only displayed during the checkout flow for the purchase of a new subscription. End users will need to complete the form.
2. (Optional) Click the toggle to enable Validation and error messaging. The validation and error messaging configuration pane appears.

You must add a Product Settings validation URL

Developers can configure custom forms to collect information from end users when they purchase products. As part of this process they can configure a Product settings validation URL. The information entered by the end user, during the purchase flow, is sent to this URL for validation.
During the purchase flow, the custom form appears. The end user enters the information on the form. The information is sent to the Product settings validation URL. For more information, see Product settings validation events.

If the end user enters the correct information the checkout process progresses. If the validation fails, the checkout process does not progress, and an error message directs end users to correct the invalid entries.
If the vendor’s service is unavailable, for example it is under maintenance, then the end user cannot complete their purchase.
The Product settings validation URL must return responses to the AppDirect platform with the following format:

{  
"result":  
    [  
     {  
         "field":"field1",  
         "title":"This is the error label",  
         "description":"Field1 must be an integer with values between 1 and 10.",  
         "level":"ERROR"  
     },  
     {  
         "field":"field2",  
         "title":"Mandatory",  
         "description":"Field2 is mandatory.",  
         "level":"ERROR"  
     }  
    ]  
}  

A response message, from the Product Settings validation URL, is displayed in the user interface. There are three levels of response.

Level	Description
INFO	The end user provided valid information.
WARN	The end user provided invalid information. They can proceed with the purchase because the missing information is optional.
ERROR	The end user provided invalid information. They cannot proceed with the purchase because the missing information is mandatory. They must enter the missing information to proceed.

1. (Optional) Select Enable validation of customer input before they proceed to the next step. The effect of this setting depends on your version of checkout.
   • If enabled for per-item checkout (v1), a Check button appears during the checkout. End users can click this button to validate their entries before continuing to the next step.
   • If enabled for cart-based checkout (v2), the field entries are validated at the field level without any action on the user's part.
     If disabled, the field entries are not validated until the user tries to move to the next step of the checkout process.
2. Enter a title for the data collection form, in Product Settings | Form Content | Form Title.
   Relate the title to the requested information.
3. (Optional) Enter a description for the data collection form, in Product Settings | Form Content | Description.
   Use this description to give end users context for the requested information. For example, describe the type of information you are requesting or the reason that you require it.
4. (Optional) Turn on Only show this form when selected by customer to display this form only if end users choose to see it. When this is turned on, end users see a checkbox, and can select it to see the form.
5. To add a data collection text field to the form, enter a code to identify the end users' entries when they are submitted to you, the Developer, in Product Settings | Form Content | Text Field | Input Code.
6. (Optional) Select Show input for each add-on unit if this is a standalone product to which you connected add-ons, and you want to display this field not only for every product subscription, but also for every connected add-on that an end user purchases.
7. (Optional) Select Enable the form field as required to mark the field as required.
8. Enter a data field title in Product Settings | Form Content | Text Field | Input Title, to add a title which appears above the data collection field .
9. (Optional) Enter a data field description in Product Settings | Form Content | Text Field | Input Descriptor, to add a description of the requested data, which appears below the data collection field.
10. (Optional) Click Product Settings | Form Content | Text Field | Add Another Text Field to add another data collection text field to this form. An additional Text Field pane appears. Repeat the steps to configure it.
11. (Optional) click Add Another Form to add another data collection form. An additional Form Content pane appears. Repeat the steps to configure it.
12. Click Save.