Getting Started: Developer Teams

What you will learn

This guide provides the integration architecture for connecting your application to Prolifi. By the end of this guide you will understand:

• How Prolifi fits into your application architecture and what it is responsible for
• How to set up usage tracking (events, metrics, streaming)
• How to integrate payment collection
• How to sync customer data
• How to integrate payment links and hosted payment pages
• How to integrate the customer portal (hosted or self-hosted)
• How to integrate the cancellation workflow
• The webhook event model and how to keep your application in sync with billing state

This guide assumes familiarity with REST APIs, webhook integrations, and server-side development. Business context is covered in the Welcome to Prolifi document if needed.

Prerequisites

Before you begin this guide:

• Your Prolifi account has been created
• At least one product and pricing plan exists in the catalog — see Getting Started: Marketing & Strategy
• Operating entities have been configured for your markets — see Getting Started: Finance
• API credentials have been issued for your environment
• Payment gateway connection has been configured — see Getting Started: Finance

Section 1 — Architecture Overview: Where Prolifi Sits

1.1 The integration boundary

Your application is responsible for:

• The core product experience (the UI, features, user interactions)
• The business logic specific to your product
• User authentication and session management
• Surfacing entitlement state to users (showing paywalls, feature gates)
• Sending usage events to Prolifi when metered features are consumed

Prolifi is responsible for:

• Subscription lifecycle management
• Billing and invoice generation
• Payment collection and retry
• Entitlement state tracking
• Usage metering and aggregation
• Dunning and payment recovery
• Revenue recognition and financial reporting
• The hosted customer portal (if using hosted option)
• The hosted cancellation flow (if using hosted option)

The integration between your application and Prolifi is primarily via two channels:

1. Outbound API calls: Your application calls the Prolifi REST API to create customers, subscriptions, send usage events, query entitlement state, etc.
2. Inbound webhooks: Prolifi calls your application’s webhook endpoints to notify you of events — payment succeeded, subscription cancelled, entitlement exhausted, etc.

1.2 Data model overview

The core entities you will work with:

1.3 Event-driven architecture

Prolifi is event-driven. Almost everything that happens in the platform emits an event — and events are delivered to your application via webhooks. Your integration should be designed to respond to events rather than polling the API for state changes.

Key principles:

• Register webhook endpoints for every event type that affects your application’s state
• Use idempotency keys (see Glossary: Payments & Integration Terms) on all write operations to handle safe retries
• Treat webhook events as the source of truth for billing state changes
• Store the relevant Prolifi object IDs (customer ID, subscription ID) in your application database alongside your own entity IDs

Section 2 — Setting Up and Tracking Usage

Before you begin this section:

• Product catalog and pricing plans exist
• Usage-based pricing plans have been configured with usage metric definitions
• API credentials are available

2.1 Understanding events and event properties

A usage event (see Glossary: Platform Concepts) is a data payload your application sends to Prolifi when a metered action occurs. Each event tells Prolifi:

• Who performed it: The customer identifier
• What was consumed: The usage metric identifier
• How much was consumed: The quantity
• When it happened: The timestamp
• Additional context: Optional custom properties for filtering or segmentation

Conceptual event structure:

1
{
2
  "idempotency_key": "evt_unique_per_action_12345",
3
  "customer_id": "cust_abc123",
4
  "metric_id": "metric_api_calls",
5
  "quantity": 1,
6
  "timestamp": "2026-03-07T14:30:00Z",
7
  "properties": {
8
    "endpoint": "/v1/completions",
9
    "model": "gpt-4",
10
    "region": "eu-west-1"
11
  }
12
}

2.2 Usage metrics

A Usage Metric (see Glossary: Platform Concepts) is the Prolifi configuration that defines how raw events are aggregated into a billable amount. Before sending events, ensure the corresponding usage metric is configured in Prolifi:

• Metric ID: The identifier your events reference
• Aggregation method: How events are summed over the billing period (sum of quantities, count of events, max value, etc.)
• Billing period scope: Whether the metric resets at billing period close

Usage metrics are configured by the Marketing/Strategy or Finance team in Prolifi, typically alongside the pricing plan they feed into.

2.3 Feature mapping

Map each metered feature in your application to its corresponding usage metric in Prolifi. Maintain this mapping explicitly in your application configuration — not hardcoded throughout the codebase:

Application feature: "AI completion request"  ->  Prolifi metric: "metric_ai_tokens"
Application feature: "Export to PDF"          ->  Prolifi metric: "metric_exports"
Application feature: "API call (external)"    ->  Prolifi metric: "metric_api_calls"

2.4 Event streaming

For high-volume usage events (thousands or millions per day), send events in batches rather than individually. Prolifi’s API supports batch event ingestion — submit arrays of events in a single request to reduce HTTP overhead and improve throughput.

For very high volumes, consider:

• Buffering events in your application and flushing periodically (every 60 seconds or every N events)
• Using an event queue (Kafka, SQS, etc.) between your application and the Prolifi event ingestion endpoint
• Implementing backpressure mechanisms to handle temporary Prolifi API unavailability without losing events

2.5 Verifying events

After sending events to Prolifi, verify that they are being received and aggregated correctly:

• Query the usage metric API to see the current aggregated total for a test customer’s billing period
• Compare the aggregated total against your expected value based on sent events
• Run this verification check as part of your integration test suite

2.6 Connecting metrics to pricing

When a usage metric is correctly linked to a pricing plan’s pricing model, Prolifi automatically calculates the billable amount from the metric at invoice generation. Verify the connection by:

1. Confirming the pricing plan references the correct usage metric
2. Sending a known quantity of test events for a test customer
3. Triggering a manual invoice generation for the test customer
4. Confirming the invoice line item matches the expected calculation

2.7 Migrating existing usage data

If you are migrating from an existing billing system, you may need to import historical usage data into Prolifi so that the first billing period is calculated correctly. Usage event ingestion accepts timestamps, so historical events can be submitted with their original event timestamps.

Consider:

• The billing period boundaries in Prolifi versus your previous system
• Whether in-flight usage from the current period needs to be imported or whether Prolifi billing starts from a clean period
• Testing the import against a single test customer before migrating the full customer base

Section 3 — Integrating Payment Collection

Before you begin this section:

• Payment gateway connection has been configured (operating entity level)
• Customer record exists in Prolifi with a payment method attached
• A subscription exists or is being created

3.1 Collection modes

Prolifi supports three payment collection approaches:

Self-collect: Your application continues to use your existing payment gateway directly. You send usage data and subscription information to Prolifi for billing calculations, but you handle payment collection yourself. Prolifi generates the invoice; you collect against it.

Collect through Prolifi: Prolifi orchestrates payment collection through a connected payment gateway. When an invoice is finalised, Prolifi automatically attempts to charge the customer’s payment method. This is the fully automated mode — recommended for most implementations.

Collect through existing channels: For offline or manual payment scenarios, invoices are generated by Prolifi and sent to customers. Payments are received outside the platform and recorded manually. Common for enterprise customers on bank transfer or BACS.

The collection mode is configured per operating entity and can differ across countries.

3.2 Per collection country and operating entity

In multi-country deployments, configure payment collection separately for each operating entity and collection country:

• Which payment gateway processes transactions in each country
• Which payment methods are enabled per country (e.g., card, SEPA, ACH)
• Whether auto-collection or manual collection applies per country
• Whether the collection currency matches the invoice currency or requires conversion

Section 4 — Integrating Customer Data

Before you begin this section:

• Your application has identified the user or business entity to be billed
• API credentials are available

4.1 Identifying the customer in your application

Before creating a customer record in Prolifi, identify the unit of billing in your application:

• Is this a user (individual person) or an account/organisation (a business)?
• Does your application support multiple billing entities per organisation (e.g., departmental billing)?
• What is the authoritative identifier in your system that you will use to cross-reference the Prolifi customer?

The external_id field on the Prolifi Customer object is how you link Prolifi’s customer record to your application’s entity. This field should carry the stable unique identifier from your application — not an email address (which can change) or a username (which can change), but a database primary key or UUID.

4.2 Creating and syncing customer records

Create a customer record in Prolifi when your application creates a billable account. The record creation call returns a Prolifi customer ID — store this ID in your application database alongside your own entity ID.

Minimal customer record fields:

1
{
2
  "external_id": "your_app_user_id_789",
3
  "name": "Acme Corporation",
4
  "email": "billing@acmecorp.com",
5
  "billing_address": {
6
    "line1": "123 Example Street",
7
    "city": "London",
8
    "country": "GB",
9
    "postal_code": "EC1A 1BB"
10
  },
11
  "currency": "GBP"
12
}

Keep customer records synchronised when billing-relevant data changes in your application: name changes, email changes, address changes. These updates affect invoice display and tax calculation accuracy.

4.3 Payment method attachment

For automated payment collection (Collect through Prolifi mode), customers must have a payment method on file. Payment methods are attached to customer records via a tokenisation flow:

1. Your application collects payment method details from the customer (via a payment gateway-hosted form or JavaScript component — never raw card details on your server)
2. The payment gateway returns a token representing the payment method
3. Your application passes the token to Prolifi via the payment method attachment API
4. Prolifi stores the token against the customer record (it never stores raw card data)

For hosted payment link integrations, Prolifi manages this flow automatically — the customer enters payment details on a Prolifi-hosted page, and the tokenisation and attachment happen without any server-side code from your application.

Section 5 — Integrating Payment Links

Before you begin this section:

• Customer record exists in Prolifi
• The plan to be subscribed to exists in the product catalog
• Payment gateway connection is configured

5.1 Configure integration settings

Before generating payment links:

• Confirm the Prolifi integration is configured with the correct redirect URLs (where to send the customer after a successful or failed payment)
• Configure the allowed payment methods for the payment link experience
• Set branding on the hosted payment pages (logo, colours, custom domain if applicable)

5.2 Authenticate the API request

All payment link generation requires an authenticated API request from your server-side application. Do not generate payment links from client-side code — the API credentials must remain server-side.

5.3 Create the billable object

To generate a payment link, you need a billable object — a subscription, an order, or an invoice — that represents what the customer will be paying for. Create the subscription (in a pending state) or order via the API, then generate the payment link against that object.

Conceptual flow:

1. Create customer record (if not already exists)
2. Create subscription in PENDING state:
   {
     "customer_id": "cust_abc123",
     "plan_id": "plan_professional_monthly_gbp",
     "state": "pending_payment"
   }
3. Generate payment link for the subscription:
   {
     "subscription_id": "sub_xyz789",
     "success_redirect_url": "https://yourapp.com/onboarding/success",
     "cancel_redirect_url": "https://yourapp.com/pricing"
   }
4. Return payment link URL to your frontend
5. Redirect customer to payment link URL

5.4 Generate and share the payment link

The payment link API returns a URL. Present this URL to the customer:

• Redirect them directly in a web flow
• Send the URL in an email
• Share via a Sales team member’s CRM or outreach tool

5.5 Handle the payment outcome

After the customer completes or abandons the payment link flow:

• Successful payment: Prolifi emits a subscription.activated and invoice.paid webhook event. Your application receives these events and activates the customer’s access.
• Abandoned / failed payment: Prolifi emits a payment.failed event. Your application handles the failure (show a retry message, update the customer’s state).

5.6 Customise the payment link experience

Payment link pages can be customised with:

• Company logo and branding
• Custom domain (so the hosted page shows your domain, not Prolifi’s)
• Custom plan display name and description
• Localisation (language and currency display)

Section 6 — Integrating the Customer Portal

Before you begin this section:

• Customer records and subscriptions exist in Prolifi
• Branding has been configured on the Prolifi account

6.1 Hosted Prolifi portal vs. self-hosted via API

Option A — Hosted Prolifi portal (recommended for most implementations): Prolifi hosts the portal at a secure URL. You generate a short-lived authenticated URL for each customer and redirect them to it. The portal is fully functional out of the box — customers can manage their subscription without any additional development from you.

Advantages: Fast to implement, maintained by Prolifi, includes all subscription management capabilities automatically.

Option B — Self-hosted portal via API: You build a custom portal in your own application, using Prolifi API calls to retrieve subscription data, entitlement balances, invoice history, and to perform actions (update plan, update payment method, etc.).

Advantages: Complete control over UX and branding, fully integrated with your application experience.

Most implementations start with the hosted portal and migrate to a self-hosted portal as the product matures.

6.2 Generate a secure portal link (hosted option)

To redirect a customer to the hosted portal:

1. Make a server-side API call to generate a short-lived, customer-specific portal session URL
2. The URL is tied to the customer ID and expires after a configured window (typically 15 minutes)
3. Redirect the customer to the URL
4. Prolifi authenticates the session from the signed URL — the customer does not need a separate Prolifi login

Conceptual flow:

Customer clicks "Manage Subscription" in your app
  |
Your server calls Prolifi API: POST /portal/sessions
  { "customer_id": "cust_abc123" }
  |
Prolifi returns: { "url": "https://portal.prolifi.io/session/tok_..." }
  |
Your server redirects customer to the portal URL
  |
Customer manages their subscription in the Prolifi-hosted portal
  |
On action completion, customer is redirected back to your configured return URL

6.3 Handle portal webhooks

Actions taken in the customer portal emit webhook events to your application. Register handlers for these events to keep your application state in sync:

6.4 Customise the hosted portal

Customise the hosted portal appearance:

• Upload your company logo
• Set brand colours
• Configure which self-service actions are available (e.g., disable plan downgrade, enable pause)
• Set the return URL after portal actions complete
• Configure a custom domain for the portal URL

6.5 Manage access control

For the self-hosted portal option, your application manages what actions each user can perform. Use the Prolifi API to:

• Retrieve the customer’s current subscription and entitlement state
• Retrieve invoice history
• Initiate plan changes, pauses, or cancellations
• Update the payment method via a tokenisation flow

Ensure you perform server-side authentication for all Prolifi API calls — never expose API credentials in client-side code.

Section 7 — Integrating the Cancellation Workflow

Before you begin this section:

• Subscription management is in place
• The decision has been made on hosted vs. self-hosted cancellation flow

7.1 Cancellation flow options

Option A — Hosted cancellation page: When a customer initiates cancellation in the hosted customer portal, Prolifi presents a configurable cancellation page. This page can:

• Present a retention offer (e.g., a discount, a plan downgrade, or a pause option)
• Capture a cancellation reason
• Present terms of the cancellation (what the customer will lose access to and when)

The hosted cancellation page is configurable in Prolifi without any code — configure the offers, messages, and options in the Prolifi dashboard.

Option B — Self-hosted cancellation flow via API: You build the cancellation experience in your application and call the Prolifi API to execute the cancellation after any retention intervention logic you have implemented.

7.2 Cancellation timing options

When a customer (or your application) cancels a subscription, configure the timing:

• Immediate cancellation: The subscription ends at the point of cancellation. If the customer has paid for a period they have not yet used, issue a credit note for the unused portion.
• End-of-period cancellation: The subscription continues to the end of the current billing period, then cancels. This is the most common consumer-facing behaviour.

Entitlement behaviour on cancellation is also configurable: expire immediately, expire at period end, or expire at a future defined date.

7.3 Webhook events on cancellation

Cancellation events to handle in your application:

Section 8 — Webhook Reference and Event Handling

8.1 Registering webhook endpoints

Register one or more webhook endpoint URLs in Prolifi. Each endpoint will receive the events you subscribe it to. Best practice:

• Use a dedicated /webhooks/prolifi endpoint, not a general-purpose event endpoint
• Process webhook events asynchronously — return a 200 OK response immediately, then process in a background job
• Store incoming webhook payloads in a queue or database before processing, to prevent data loss if processing fails

8.2 Verifying webhook authenticity

Prolifi signs all webhook payloads with an HMAC signature. Always verify the signature before processing the event:

1. Receive webhook POST request
2. Extract the signature from the Prolifi-Signature header
3. Recompute the HMAC signature using:
   - Your webhook signing secret (from Prolifi dashboard)
   - The raw request body (before JSON parsing)
4. Compare computed signature to received signature
5. If they match: proceed with processing
6. If they do not match: reject the event (return 401)

8.3 Core events to handle

Subscription events:

Payment events:

Entitlement events:

8.4 Idempotent event processing

Webhook delivery is at-least-once — you may receive the same event more than once. Implement idempotent event processing:

• Store processed event IDs in your database
• Before processing an event, check if the event ID has been processed before
• If already processed: return 200 OK without re-processing
• If not yet processed: process and mark as processed

Section 9 — Integration Checklist

Use this checklist to confirm your integration is complete and production-ready:

Customer data:

• Customer records created and external_id synced to Prolifi on account creation
• Customer record updates synchronised when billing-relevant data changes

Usage tracking (if applicable):

• Usage events sent with correct metric IDs and customer references
• Idempotency keys included on all usage event submissions
• Event verification tested: aggregated totals match expected values
• Batch ingestion implemented for high-volume event sources

Payment collection:

• Payment method attachment flow implemented (or hosted payment links configured)
• Collection mode configured per operating entity

Payment links (if applicable):

• Payment link generation implemented server-side
• Redirect URLs configured (success, cancel)
• Successful payment webhook handled and access granted

Customer portal:

• Portal session generation implemented server-side
• Webhook handlers implemented for portal actions
• Return URL configured

Cancellation workflow:

• Cancellation flow configured (hosted or self-hosted)
• Cancellation webhooks handled and access revoked appropriately

Webhook infrastructure:

• Webhook endpoint registered in Prolifi
• Signature verification implemented
• Asynchronous processing implemented
• Idempotent event handling implemented
• All core events handled (subscription, payment, entitlement)

Cross-references

• Glossary: Platform Concepts
• Welcome to Prolifi
• Billing Models Reference
• Entitlement Management Reference
• Dunning & Payment Recovery