Checkout validation

A webhook that lets you check if a plan or quantity change is allowed before the user can checkout.

When a user attempts to upgrade or change their subscription using the Bunny portal we call this a checkout.

In some cases you might want to check if the plan or quantity change should be allowed before letting the user proceed.

Bunny sends the checkout validation webhook:

• while the user builds or edits their change in the checkout
• when the user checks out, before any payment is taken
• when a new customer signs up, after their account and tenant are created and before any payment is taken

Enabling checkout validationLink to Enabling checkout validation section

To enable this webhook you will need to ensure that you have enabled a webhook endpoint for your platform in Bunny.

Then turn on Checkout validation enabled on your platform.

Checkout validation webhook payloadLink to Checkout validation webhook payload section

The payload that will be sent will contain information about the tenant on your platform that is requesting a change and the features and quantities that they will be change to.

{
  "type": "CheckoutValidation",
  "payload": {
    "tenant": {
      "id": 132,
      "code": "8c665dde-69ae-4c53-990b-3d19bf71791e",
      "name": "Superdesk Inc"
    },
    "change": {
      "features": [
        {
          "code": "users",
          "name": "Users",
          "value": "",
          "quantity": 10,
          "plan": {
            "code": "enterprise",
            "name": "Enterprise"
          },
          "price_list": {
            "code": null,
            "name": "Enterprise Monthly"
          }
        },
        {
          "code": "widgets",
          "name": "Widgets",
          "value": "100",
          "quantity": 100,
          "plan": {
            "code": "enterprise",
            "name": "Enterprise"
          },
          "price_list": {
            "code": null,
            "name": "Enterprise Monthly"
          }
        }
      ]
    }
  }
}

change is always an object, and each feature’s value is always a string. It’s empty for features without a value.

If you wanted to validate the number of users you would use the Tenant code to look up the relevant tenant in your application, get a count of the users and then compare this to the number of users requested in the checkout validation payload.

For a signup, the tenant is new, so your application may not know its code yet.

Responding to the webhookLink to Responding to the webhook section

If you opt in to the checkout validation webhook, your endpoint decides whether the change can go ahead. Bunny waits up to 5 seconds for the response and doesn’t retry.

The request is signed with the platform’s Webhook signing key so you can verify it. Unlike the provisioning webhook, it doesn’t include the Webhook auth token.

Change approvedLink to Change approved section

Respond with any 2xx status, for example 200 OK. The user can continue with the subscription change. No response body is required and will be ignored if provided.

Change deniedLink to Change denied section

Respond with 422 Unprocessable Content. The user can’t continue and is shown the messages you return.

The response body must be a non-empty JSON array of strings that explain why the subscription change is not possible.

[
   "You have too many users to downgrade to this plan. Please remove some users and try again."
]

Validation unavailableLink to Validation unavailable section

Any other outcome also blocks the change. That includes a timeout, a refused connection, a failed TLS handshake, any other status code, and a 422 whose body isn’t a non-empty array of strings. The user sees “We couldn’t validate this change right now. Please try again or contact support.” Make sure the endpoint answers quickly and reliably.