For AI agents: the complete documentation index is available at https://docs.clickmax.io/en/llms.txt, the full documentation bundle is available at https://docs.clickmax.io/en/llms-full.txt, and this page is available as Markdown at https://docs.clickmax.io/en/features/integrations/principia.md.
  • English

      • Integrate Principia

      Create an inbound integration in Clickmax, paste your Principia (formerly Provi) account's API Token, and register the generated URL in Principia's webhook with the Authorization header. From then on every event carrying an email creates or updates a contact (tagged principia), and confirmed purchases become sales in Clickmax.

      Before you start

      • Workspace role: Owner, Admin, Editor or Collaborator. The Finance, Guest and Agent roles cannot access Integrations.
      • Plan:
      • From your Principia account you need the API Token (side menu > Settings > API Token). It is required: besides authorising the integration, it is what lets Clickmax list your courses in the automation product picker.
      • You also choose your own secret value to authenticate the deliveries. That same value goes into Clickmax's Token field and into the Authorization header of Principia's webhook.

      Step by step

      1. In Clickmax, open Integrations and select the Principia card.
      2. In another tab, go to Principia and log in.
      3. In Principia, from the side menu, go to Settings > API Token, copy the token and paste it into Clickmax's Api Token field.
      4. Choose a secret value (a long, random password) and paste it into Clickmax's Token field. Keep it: you will reuse it in step 7.
      5. Enter a Nickname for the integration and click Create integration.
      6. Clickmax generates a webhook URL. Copy it.
      7. In Principia, under Settings > Webhooks, register the copied URL and set the Authorization header to the secret value from step 4.
      8. In Principia, select the events you want to receive (purchase confirmed, purchase canceled, payment declined, financing denied, invoice created, invoice expired, cart abandoned and guarantor required).
      9. Back in Clickmax, click Complete integration.

      What starts arriving

      Every event carrying an email creates or updates a contact tagged principia. Confirmed purchases mark the contact as a customer and record the sale; purchase canceled, payment declined and financing denied are also recorded as sales, with the matching outcome.

      A checkout with more than one course records one activity per course in the contact history, and the sale keeps the additional courses linked to it. Principia only reports the order total, never a price per course, so the individual activities show no value.

      Because Principia is a financing checkout, it sends stages other checkouts do not have: financing denied (the credit analysis refused it) and guarantor required (a guarantor is needed to proceed). Both arrive as activity in the contact history and can start automations, alongside invoice created, invoice expired and cart abandoned.

      Events without the buyer's email are ignored.

      For the full list of recognised events and what each one triggers, see the inbound webhooks reference and the events reference.

      If it didn't work

      • The integration is not created: the Api Token is validated at creation time. If it is wrong or expired, Clickmax refuses and nothing is saved — generate a new one under Settings > API Token. See the error codes.
      • No events arrive: the Authorization header value on Principia's webhook must match Clickmax's Token field exactly — any difference makes Clickmax reject the delivery. Also check that the integration is active. See the error codes.
      • One specific event does not arrive: events without the buyer's email are discarded (Clickmax cannot resolve the contact). Also check that the event is selected on Principia's webhook. See the error codes.
      • The course does not show up in the automation product picker: the picker lists courses from Principia's API using the Api Token. If it was not saved or is no longer valid the list comes back empty — in that case you can still type the course id manually. See the FAQ.