***

title: Getting Started: Developer Teams
subtitle: Integration architecture and approach for connecting your application to Prolifi
slug: getting-started/developers
---------------------

For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.prolifi.io/getting-started/llms.txt. For full documentation content, see https://docs.prolifi.io/getting-started/llms-full.txt.

<Tip>
  The full [API Reference](/api-reference) is now available with interactive endpoint documentation, request/response schemas, and code examples. Refer to the [Authentication guide](/api-guides/authentication) for API key setup.
</Tip>

## 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](/welcome) 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](/getting-started/marketing-strategy)
* Operating entities have been configured for your markets — see [Getting Started: Finance](/getting-started/finance)
* API credentials have been issued for your environment
* Payment gateway connection has been configured — see [Getting Started: Finance](/getting-started/finance)

***

## Section 1 — Architecture Overview: Where Prolifi Sits

<Note>
  Before writing a single line of integration code, understanding the boundary between your application's responsibilities and Prolifi's responsibilities is the most important decision you will make. A misconfigured boundary leads to duplicated logic, synchronisation problems, and billing state that drifts from application state.
</Note>

### 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:

```mermaid
graph TD
    A["Customer"] --> B["PaymentMethod"]
    A --> C["Subscription"]
    C --> D["Plan"]
    C --> E["Entitlements"]
    E --> F["EntitlementBalance"]
    C --> G["Invoices"]
    G --> H["Payments"]

    I["UsageEvent"] --> J["UsageMetric"]
    J -.->|"linked to"| D
```

### 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](/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

<Note>
  Usage tracking is the data pipeline that connects your application's activity to Prolifi's billing engine. If usage events are not sent correctly, usage-based invoices will be wrong. Getting this right — including idempotency, event properties, and metric configuration — is the most technically demanding part of a Prolifi integration.
</Note>

### 2.1 Understanding events and event properties

A **usage event** (see [Glossary: Platform Concepts](/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:**

```json
{
  "idempotency_key": "evt_unique_per_action_12345",
  "customer_id": "cust_abc123",
  "metric_id": "metric_api_calls",
  "quantity": 1,
  "timestamp": "2026-03-07T14:30:00Z",
  "properties": {
    "endpoint": "/v1/completions",
    "model": "gpt-4",
    "region": "eu-west-1"
  }
}
```

<Warning>
  Always include an `idempotency_key` on usage events. If your application retries a failed event submission, the idempotency key prevents the event from being double-counted.
</Warning>

### 2.2 Usage metrics

A **Usage Metric** (see [Glossary: Platform Concepts](/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

<Note>
  Payment collection is where billing state connects to real money movement. The architecture decision you make here — self-collect, collect through Prolifi, or collect through existing channels — determines how much of the payment lifecycle Prolifi manages automatically and how much you handle manually.
</Note>

### 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

<Note>
  The customer record in Prolifi is the anchor for everything — subscriptions, invoices, entitlements, and payment methods. Creating and syncing customer records correctly, with reliable cross-reference identifiers, prevents a class of integration problems that are expensive to fix later.
</Note>

### 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:**

```json
{
  "external_id": "your_app_user_id_789",
  "name": "Acme Corporation",
  "email": "billing@acmecorp.com",
  "billing_address": {
    "line1": "123 Example Street",
    "city": "London",
    "country": "GB",
    "postal_code": "EC1A 1BB"
  },
  "currency": "GBP"
}
```

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

<Note>
  Payment links are the lowest-friction way to collect payment from a customer — particularly for sales-led motions where a Sales team member wants to send a customer a payment link rather than collecting card details manually. They are also the standard pattern for self-serve sign-up flows.
</Note>

### 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

<Note>
  The customer portal is how your customers self-serve their subscription management — viewing invoices, updating payment methods, upgrading or downgrading plans, and managing cancellation. Integrating the portal correctly dramatically reduces the support burden for subscription-related requests.
</Note>

### 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:

| Webhook event               | What happened                                | Recommended application action             |
| --------------------------- | -------------------------------------------- | ------------------------------------------ |
| `subscription.plan_changed` | Customer upgraded or downgraded              | Update feature access in your app          |
| `subscription.cancelled`    | Customer cancelled                           | Revoke access at period end or immediately |
| `subscription.paused`       | Customer paused                              | Restrict access based on your pause policy |
| `payment_method.updated`    | Customer updated their card                  | No application action required             |
| `invoice.paid`              | Invoice was paid (e.g., after updating card) | If access was restricted, restore it       |

### 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

<Note>
  The cancellation moment is a high-stakes retention opportunity. A poorly handled cancellation flow loses customers who could have been saved with the right offer. Prolifi's cancellation workflow — whether hosted or API-driven — supports intervention at the cancellation point.
</Note>

### 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:

| Event                                 | When it fires                                        | Action                                                       |
| ------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| `subscription.cancellation_scheduled` | Customer has requested cancellation at end of period | Update UI to show cancellation date; send confirmation email |
| `subscription.cancelled`              | Subscription has reached cancellation                | Revoke access; send final communication                      |
| `invoice.credited`                    | Credit note issued on immediate cancellation         | Update customer balance display                              |

***

## Section 8 — Webhook Reference and Event Handling

<Note>
  A complete and robust webhook integration is the difference between a billing system that stays in sync with your application and one that constantly drifts. Treat webhook events as the source of truth for billing state changes — never rely solely on API polling.
</Note>

### 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:**

| Event                        | Significance                                       |
| ---------------------------- | -------------------------------------------------- |
| `subscription.trial_started` | Trial began — provision trial access               |
| `subscription.activated`     | Subscription went active — provision full access   |
| `subscription.plan_changed`  | Plan upgraded or downgraded — adjust access        |
| `subscription.paused`        | Billing suspended — adjust access per pause policy |
| `subscription.resumed`       | Billing reinstated — restore access                |
| `subscription.cancelled`     | Subscription ended — revoke access                 |

**Payment events:**

| Event                    | Significance                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------ |
| `invoice.created`        | Invoice generated — informational                                                    |
| `invoice.paid`           | Payment collected — confirm access if previously restricted                          |
| `invoice.payment_failed` | Payment attempt failed — initiate application-level dunning communications if needed |
| `invoice.voided`         | Invoice cancelled — update records                                                   |

**Entitlement events:**

| Event                     | Significance                                                 |
| ------------------------- | ------------------------------------------------------------ |
| `entitlement.exhausted`   | Entitlement fully consumed — enforce paywall; prompt upsell  |
| `entitlement.low_balance` | Entitlement approaching limit — prompt upsell proactively    |
| `entitlement.reset`       | Entitlement renewed at billing period start — restore access |
| `entitlement.expired`     | Expirable entitlement has expired — revoke access            |

### 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](/glossary/platform-concepts)
* [Welcome to Prolifi](/welcome)
* [Billing Models Reference](/billing-pricing/billing-models)
* [Entitlement Management Reference](/billing-pricing/entitlement-management)
* [Dunning & Payment Recovery](/payments-recovery/dunning-payment-recovery)