About the Wix Automations Action SPI

The Action Provider SPI allows you to implement an action that site contributors can add to automations on their sites. This means you can take actions in your service in response to events that happen on Wix sites or in the business manager. For example, in response to a trigger, your service can send an email, generate an invoice, or update another Wix service using its APIs.

The Action SPI lets you do the following:

• Validate the input values to the action and return an error to the user if they are invalid.
• Display the limits you enforce on the number of actions a user can perform.

Before you begin

• Keep in mind that once you publish an app with a custom action, there are limitations to the changes you can make to the input schema you define when configuring your action. Learn more about editing a published input schema.
• Wix does not validate breaking changes to an input schema that uses composition. To ensure the user does not make errors when configuring an action that uses composition in its schema, we recommend performing the validation on your end.

Terminology

• Input schema: A JSON Schema object that defines the fields that Wix needs to pass to your Action SPI endpoints. Learn more about the input schema here.
• UI schema: The JSON schema that defines the UI for your action configuration in the user's site dashboard.

How to set up an action

To configure your action in the Wix Developers Center:

1. Select Automations from the left menu, then select Create New > Action.

2. Give your action a name. This is displayed to users when they add the action in the Automations UI.

   Notes:

   • Your action key is generated automatically from the action name. Once you save your action you cannot change the action key.
   • The action key is not displayed to users.

3. Add a short description explaining what your action does. The description is displayed to users when they select your action. This is an optional field.

4. Choose whether to hide the action, so it doesn't appear as an individual action on a user site. You should do this if the action is part of a pre-installed automation.

5. Under Action's SPI endpoints, enter your base provider URI and select the SPI endpoints you intend to implement.

6. Configure your input schema.

7. Optionally, configure your action's UI.

8. Click Save at the top of the page in order to save your action.

9. Next, you need to test your action to make sure everything's working. You can install your app on a free Premium development site to test it.

   Once you create the test site, return to your app in the Wix Developers Center and click Test Your App > Dashboard. Select the test site you installed your app on earlier. Use this site to make sure your action is working.

10. When you have tested your app and are ready to publish your new action, submit your app for review. A member of our team will check the changes and approve the latest version.

Once our team has approved your app, it will be published and available for users to install on their sites. When a user installs your app, your actions become available for their automations, as shown here:

About the Action SPI Input Schema

When an automation is triggered, Wix passes data from the trigger payload to your service so it can perform your action. You tell Wix exactly what data your action requires from the trigger by defining the input schema. The input schema is a JSON Schema object that allows you to define the data types your service needs to execute your action. You must provide the input schema for your action when you configure it in the Wix Developers Center.

By default, the fields defined by the schema are statically linked to a field in the trigger payload. This means the data from the payload passes to the input schema and does not require user input. However, you can allow users to input data into the schema by making the input fields dynamic. You can mark an input field as dynamic in the UI schema.

If the trigger payload fields do not match the fields in your input schema, your action will not run when the automation is triggered.

See the tables below for the expected input schema structure.

Schema properties

These properties are at the schema's root level.

The input schema supports schema composition keywords such as allOf, anyOf, and oneOf.

The properties object

The properties object contains the key-object pairs that make up the bulk of the data passed to the action. The key name can include only alphanumeric characters or underscores (A-Z, a-z, 0-9, _). It cannot start with an underscore.

Each paired object contains display and validation metadata. This table gives the expected data structure for an object in properties:

The items object

items is an object that contains an array schema.

Editing a saved input schema

Once you publish the action with your app, Wix enforces the following limits on changes you can make to the action's input schema. Once the action is saved, you can't:

• Add required fields to the schema.
• Mark existing non-required fields as required.
• Change a field’s type.
• Change a field’s format.
• Remove or change a field’s identity type.

Displaying Action Quotas

As an action provider, you can enforce limits on the number of times a site owner uses an action. For example, an action provider can limit the number of messages a user can send per billing cycle. You can enforce different quotas on specific features of the app, depending on the user. For example, your app might have a basic plan that allows the user to send 500 emails a month, and a premium plan that lets the user send unlimited emails.

Terminology

• quota: A limit on the number of times a site owner can perform an action. For example, you can set a quota of 500 reminder emails that the user may send.

• plan: Allows you to set different quotas for different users.

Creating and enforcing quotas

You are responsible for enforcing quotas for features used by their actions. If the features provided by your service have quotas you can implement the Get Action Quota Info endpoint so that Wix can display your quotas in the user's site dashboard. Wix displays the quotas in the Manage your automations quotas modal. This modal opens when site contributors click the Manage Your Quotas button on the Automations page in the dashboard.

The modal lists the quotas for all the features used by the site's automations. The list is organized by the apps providing the features.

You can define the different elements of each quota display in the responses from your Get Action Quota Info endpoint. In general, each quota display includes a plan, and the plan features associated with it. The current usage and limit for each feature is displayed.

One plan with one feature

To display one plan with a single feature quota, include the plan and quota data in the same quotaInfo object in your endpoint’s response.

Sample response body:

1
{
2
  "enforced": true,
3
  "quotaInfo":[
4
    {
5
      "plans": [
6
        {
7
          "id": "fdc7fe4b-523f-4d8c-b6e1-5faf3850d01e",
8
          "name": "Reminder emails"
9
        }
10
      ],
11
      "quotas":
12
      [
13
        {
14
          "featureName": "Reminders sent",
15
          "currentUsage": "10",
16
          "limit": "40"
17
        },
18
        {
19
          "featureName": "Tasks created",
20
          "renewalDate": "2022-01-12T01:20:00.000Z",
21
          "currentUsage": "346",
22
          "limit": "500"
23
        }
24
      ],
25
      "upgradeCta": {
26
        "url": "https://www.example.com/upgrade",
27
        "label": "Upgrade For More"
28
      }
29
    }
30
  ]
31
}

The resulting quota display looks like this:

One plan with two features

To display one plan with a single feature quota, include the plan and quota data in the same quotaInfo object in your endpoint’s response.

Sample response body:

1
{
2
 "enforced": true,
3
 "quotaInfo":[
4
  {
5
   "plans": [
6
    {
7
     "id": "f32c650f-ecc4-4818-a81c-8fa681e325a6",
8
     "name": "Email Marketing"
9
    }
10
   ],
11
   "quotas":[
12
    {
13
     "featureName":"Emails sent",
14
     "currentUsage":"346",
15
     "limit":"500",
16
     "renewalDate":"2023-01-12T01:20:00.000Z"
17
    }
18
   ],
19
   "upgradeCta": {
20
          "url": "https://www.example.com/upgrade",
21
    "label": "Upgrade Email Plan"
22
   }
23
  }
24
 ]
25
}

The resulting quota display should look something like this:

Two plans with different features

To display two different plans with different features that are both being used by your action service, include two quotaInfo objects in your response body.

Sample response body:

1
{
2
  "enforced": true,
3
  "quotaInfo": [
4
    {
5
      "plans": [
6
        {
7
          "id": "94e55e1f-b845-47a5-afad-4b8fc977d545",
8
          "name": "Forms on your site"
9
        }
10
      ],
11
      "quotas": [
12
        {
13
            "featureName": "Forms on your site",
14
            "currentUsage": "6",
15
            "limit": "40"
16
        }
17
      ],
18
      "upgradeCta": {
19
          "url": "https://www.example.com/upgrade",
20
          "label": "Upgrade For More",
21
          "planId": "fd9830b5-ce89-495f-87e8-30893168afd9"
22
      }
23
    },
24
    {
25
      "plans": [
26
        {
27
          "id": "c7f255a5-0aa2-47ad-9607-8f87ea56df5b",
28
          "name": "Code Forms on your site"
29
        }
30
      ],
31
      "quotas": [
32
        {
33
          "featureName": "Code Forms on your site",
34
          "currentUsage": "1",
35
          "limit": "20"
36
        }
37
      ],
38
      "upgradeCta": {
39
          "url": "https://www.example.com/upgrade",
40
          "label": "Upgrade For More",
41
          "planId": "b19345c1-380c-4fc6-8e45-9f7f72b3de5f"
42
      }
43
    }
44
  ]
45
}

The resulting quota display looks like this:

Unlimited plans

If your service supports a plan where features are unlimited, you can still display the site contributor’s current usage. To do this, provide a quotaInfo object with the relevant plan details. Include the feature’s name and current usage, but not a usage limit.

Sample response body:

1
{
2
 "enforced": true,
3
 "quotaInfo": [
4
    {
5
      "plans": [
6
        {
7
          "id": "1ccaa3a5-4994-4e17-b1d4-2fa3f76418e7",
8
          "name": "Marketing Emails"
9
        }
10
      ],
11
      "quotas": [
12
        {
13
          "featureName": "Emails",
14
          "currentUsage": "150"
15
        }
16
      ]
17
    }
18
  ]
19
}

The resulting quota display should look like this:

User hasn't purchased a plan

If your service enforces a quota on a feature that a site contributor hasn’t paid for, you can display this in the dashboard. This lets the site contributor know that your action isn’t running when their automation is triggered. To display this, set both the current usage and limit for the feature to 0 in the relevant quotaInfo object in your response body.

Sample response body:

1
{
2
  "enforced": true,
3
  "quotaInfo": [
4
    {
5
    "plans": [
6
        {
7
          "id": "d0a9fa93-f2a7-426a-89d6-a15d2e7c0d78",
8
          "name": "Marketing Emails"
9
        }
10
      ],
11
    "quotas":[
12
        {
13
          "featureName": "Monthly Emails",
14
          "renewalDate": "",
15
          "currentUsage": "0",
16
          "limit": "0"
17
        }
18
      ],
19
      "upgradeCta": {
20
          "url": "https://www.example.com/upgrade",
21
          "label": "Upgrade",
22
          "planId": "28d52c9c-7c59-4a14-bbc1-a7d9103e1038"
23
      }
24
    }
25
  ]
26
}

Quota descriptions

You can define a tooltip that provides more details about a feature quota. To display the tooltip, add an additionalInfo object together with the feature details.

Sample response body:

1
{
2
  "enforced": true,
3
  "quotaInfo": [
4
    {
5
      "plans": [
6
        {
7
          "id": "fa9bbb78-286f-46b4-83fe-4aa81d94c715",
8
          "name": "Marketing Messages"
9
        }
10
      ],
11
      "quotas": [
12
        {
13
          "featureName": "SMS sent",
14
          "renewalDate": "",
15
          "currentUsage": "400",
16
          "limit": "1200",
17
          "additionalInfo": {
18
            "description": "Your SMS quota will renew each month. Any remaining messages won't roll over to the next month.",
19
            "cta": {
20
                "url": "/home",
21
                "label": "Go to SMS Settings"
22
            }
23
          }
24
        }
25
      ],
26
      "upgradeCta": {
27
          "planId": "e15d2206-4226-4815-8684-41b101c7dcad",
28
          "url": "https://www.example.com/upgrade",
29
          "label": "Upgrade"
30
      }
31
    }
32
  ]
33
}

You should now see a message when you hover over the tooltip icon: