This guide explains how to integrate and configure the FunnelFox Billing Subscription engine in a few simple steps.

​
Setup

Get your Subscription engine ready to go by integrating Primer, then defining your Offerings and Price Points.

​
1. Create account

  1. Request our support team to create a FunnelFox Billing account. You will receive:
    • FunnelFox Billing account credentials
    • Unique organization ID
  2. Log in to your FunnelFox Billing account.

​
2. Integrate with Primer

  1. Go to the Settings page.
  2. Configure your settings as follows, then click Submit:
    • Organization name or FF project: Enter your organization’s name.
    • Primer API domain: Provide the API URL
      • https://api.sandbox.primer.io for Production environment.
      • https://api.primer.io for Sandbox environment.
    • Primer API private key: Enter the private key generated in Primer. Make sure the key has full access permissions. Learn about API key in Primer.
    • Primer webhook signing: Enter the webhook signing secret from Primer. Learn about signing secret in Primer.
    • Webhook URL: Specify the URL if you want to receive events from the Subscription engine on your backend.
  3. Go to Developers > Webhooks in your Primer Dashboard and set up two webhooks:
    • Event type: One webhook for Automation and another one for Payment.
    • Endpoint URL: https://billing.funnelfox.com/{YOUR_ORG_ID}/v1/primer/webhook?region=default using your organization ID as {YOUR_ORG_ID}. You can find the complete URL at the top of the Settings page in your FunnelFox Billing account.

​
3. Create Offering

An Offering (Feature) represents what users get access to with their subscription (e.g., premium_access, pro_support). Each Offering (Feature) has a unique identifier called ident.
Most products have one main Offering (Feature) named premium, plus additional upsell Offerings (Features).
  1. Go to the Offering (Features) section from the Settings page.
  2. Fill out the Offering (Feature) Ident field.
  3. Click Create Offering (Feature).

​
4. Create Price Points

A Price Point defines the pricing and terms for your Offering (Feature) — including price, billing cycle, and trial options (e.g., 1€ trial for 30 days, then 5€/month). Price Points use versioned objects, which means subscription terms are locked when a user purchases. Even if you change a Price Point later, existing subscribers keep their original terms.
  1. Download our Price Points CSV example file (coming soon).
  2. Fill out a CSV with your Price Points. Follow the example CSV and this columns reference:
    • pp_id, pp_version: Skip this value as it’s automatically generated system value.
    • ident: Price Point identificator to be used later in the API.
    • intro_type
      • no_intro: Purchase without a trial period.
      • free_trial: Free access for a limited time (e.g., 3 days).
      • paid_trial: The first period has a different price or duration (e.g., 1 week for $1).
    • currency_code: The currency for this Price Point (USD, EUR, GBP, etc.).
    • lifetime_price: For lifetime purchases only to define the price.
    • intro_free_trial_period: For intro_type = free_trial only to define the free trial period, e.g. 2 or 30.
    • intro_free_trial_period_duration: For intro_type = free_trial only to define the unit of time that pairs with the free trial period above, e.g. days or weeks.
    • intro_paid_trial_price: For intro_type = paid_trial only to define the paid trial price that pairs with the currency above, e.g. 1.99.
    • intro_paid_trial_period: For intro_type = paid_trial only to define the paid trial period, e.g. 2 or 30.
    • intro_paid_trial_period_duration: For intro_type = paid_trial only to define the unit of time that pairs with the paid trial period above, e.g. days or weeks.
    • next_price: Subscription price per billing period after a trial ends.
    • next_period: The subscription billing period length after the trial, e.g. 2 or 30.
    • next_period_duration: Indicates the subscription period unit of time that pairs with the period above, e.g. days or weeks.
    • descriptor: The description to appear on your customer’s credit or debit card statement. Use something they’ll recognize to avoid chargebacks.
    • features: The Offering (Feature) for the Price Point. Only one item is supported per Price Point.
    • created_at: Skip this value as it’s automatically generated with the Price Point creation date.
    • updated_at: Skip this value as it’s automatically generated with the Price Point update date.
Intro periods are currently not supported for lifetime purchases.
  1. Click PricePoints CSV manager under the Offering (Features) section.
  2. Upload your CSV file.
The CSV Manager only supports creating new records and does not support editing existing ones.

​
User management

Assign roles to your team to control who can view data, handle payments and subscriptions, or administer organization-level settings. There are three permission groups for Subscription Engine management:
  • viewer: Can only view data.
  • support: Can view data and perform purchase and payment actions (refund, unsubscribe, pause, defer, etc.).
  • admin: Has full control, including the ability to modify organization settings.

​
Next steps

Now you’re ready to build your checkout flow.