FunnelFox Payments API

The Billing API lets you model products as price points, orchestrate checkout with your PSPs, and manage subscriptions end-to-end — including pausing/resuming, discounts, migrations, and refunds.

This doc covers the FunnelFox Payments API only. If you’re using the FunnelFox API, go to the FunnelFox API section.

Base URL

All API requests should be made to:

https://billing.funnelfox.com/{org_id}/v1

Replace {org_id} with your organization ID provided by your Customer Success Manager when your FunnelFox Payments account was created.

Don’t confuse {org_id} with your FunnelFox Project ID found in your FunnelFox General settings.

Authentication

Authenticate your API requests by including your secret key in the ff-secret-key header. Some endpoints are public and don’t require authentication.

Endpoints requiring ff-secret-key header

/payment/refund
/payment/cancel
/payment/one_off_charge
/subscription/enable_autorenew
/subscription/disable_autorenew
/subscription/migration
/discount
/subscription/defer
/subscription/pause
/subscription/resume
/subscription/search
/pp/list
/pp/export_csv
/pp/import_csv
/pp/update
/pp/create
/feature/create
/payments_history
/transaction_report
/search_users
/user/update_email

Endpoints not requiring authentication

/checkout/create_client_session
/checkout/create_simple_client_session
/checkout/update_client_session
/checkout/create_payment
/checkout/one_click
/checkout/resume_payment
/my_assets
/price_points
/features

Secret key

Request your API secret key from your Solution manager, or set it yourself on the Settings > Main page of the FunnelFox Payments dashboard. To set your API secret key:

Go to Settings > Main in the FunnelFox Payments dashboard.
Set the New Value of the following settings:

ff_api_secrets_new.first.enabled: Set to Enabled to turn on the secret key.
ff_api_secrets_new.first.group: Define access level group to set API access limitations. Learn more about access groups.
ff_api_secrets_new.first.key: Enter your secret key value. Store this securely—once saved, the UI will not display it again.

Click Save, then confirm the change.

You can set an additional secret key using the ff_api_secrets_new.second fields.

Access groups

The group value assigned to each secret key defines endpoints available to the user. There are three access levels: viewer, support, and admin. Viewer can only call endpoints that don’t require authentication. Support can call all unprotected endpoints plus the following authenticated endpoints:

Support — authenticated endpoints

POST /payment/refund
POST /payment/cancel
POST /payment/one_off_charge
POST /payments_history
POST /transaction_report
POST /search_users
POST /user/update_email
POST /subscription/search
POST /subscription/migration
POST /subscription/enable_autorenew
POST /subscription/disable_autorenew
POST /subscription/defer
POST /subscription/pause
POST /subscription/resume
POST /discount

Admin can call all unprotected and support endpoints plus the following:

Admin — additional endpoints

POST /pp/create
POST /pp/update
POST /pp/import_csv
POST /pp/export_csv
POST /pp/list
POST /feature/create

Available endpoints

The FunnelFox Payments API provides the following endpoints, grouped by function.

Payment management

POST /payment/refund — Refund an order (full or partial; optional “soft” refund)
POST /payment/cancel — Cancel an order
POST /payment/one_off_charge — Charge a custom amount to a saved card (custom charges)

Subscription management

POST /subscription/enable_autorenew — Turn on autorenew
POST /subscription/disable_autorenew — Turn off autorenew
POST /subscription/migration — Move a sub to another price point (price_prorate, delayed_start)
POST /discount — Apply a percentage discount for a number of iterations
POST /subscription/defer — Delay the next charge until a time
POST /subscription/pause — Stop billing and access until a time
POST /subscription/resume — Cancel pause and restart billing/access
POST /subscription/search — Search and filter subscriptions

PricePoints

POST /price_points — List price points (filter by ident)
POST /pp/list — List price points with admin fields (pp_id, pp_version, descriptor, description, apple_pay_merchant_name, pp_extra_metadata)
POST /pp/export_csv — Export all price points to CSV
POST /pp/import_csv — Bulk-create price points from CSV
POST /pp/update — Update by ident
POST /pp/create — Create a price point
POST /feature/create — Create a feature (timebased, lifetime, consumable)
POST /features — List all features

User management

POST /user/update_email — Update the email address associated with a user account

Information

POST /my_assets — Fetch user ownership (subscriptions, one-off purchases & consumables)
POST /payments_history — Return successful payments of user
POST /transaction_report — Return all transactions
POST /search_users — Search user

Checkout

POST /checkout/create_client_session — Get a client token & order for the selected price point
POST /checkout/create_simple_client_session — Start a lightweight checkout session without a price point or user, returning only a client token
POST /checkout/update_client_session — Re-bind an order to a different price point
POST /checkout/create_payment — Charge using a payment_method_token
POST /checkout/one_click — One-click purchase by external_id + pp_ident
POST /checkout/resume_payment — Complete a payment after additional action

Learn more in the FunnelFox Payments API reference.

You can also manage price points and offerings from the dashboard. See Price points and Offerings.

Making requests

Path parameters

All endpoints defined under https://billing.funnelfox.com/{org_id}/v1/... require the org_id in the URL path.

Request body

Most endpoints accept JSON parameters in the request body. Parameters vary by endpoint - see the API Reference for details.

Example request

curl -X POST 'https://billing.funnelfox.com/{org_id}/v1/price_points' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "ident": null
  }'

const response = await fetch('https://billing.funnelfox.com/{org_id}/v1/price_points', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ident: null
  })
});

const data = await response.json();
console.log(`Found ${data.data.price_points.length} price points`);

import requests

response = requests.post(
  'https://billing.funnelfox.com/{org_id}/v1/price_points',
  headers={
    'accept': 'application/json',
    'Content-Type': 'application/json'
  },
  json={'ident': None}
)

data = response.json()
print(f"Found {len(data['data']['price_points'])} price points")

Response format

All successful responses follow this structure:

{
  "data": {
    // Response data specific to the endpoint
  },
  "status": "success"
}

Example response

{
  "data": {
    "price_points": [
      {
        "ident": "monthly-premium",
        "currency": {
          "code": "USD",
          "minor_units": 2,
          "title": "US Dollar",
          "symbol": "$"
        },
        "intro_type": "free_trial",
        "lifetime_price": null,
        "intro_free_trial_period": 7,
        "intro_free_trial_period_duration": "days",
        "intro_paid_trial_price": null,
        "intro_paid_trial_period": null,
        "intro_paid_trial_period_duration": null,
        "next_price": "9.99",
        "next_period": 1,
        "next_period_duration": "months",
        "features": [
          {
            "ident": "premium-access"
          }
        ]
      }
    ]
  },
  "status": "success"
}

Filtering

The POST /price_points endpoint is the only one that supports narrowing results by ident to retrieve specific price points. Pass an ident value to retrieve only the matching price point:

curl -X POST 'https://billing.funnelfox.com/{org_id}/v1/price_points' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "ident": "pro_monthly_usd"
  }'

List all price points (no filter):

curl -X POST 'https://billing.funnelfox.com/{org_id}/v1/price_points' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{}'

Error handling

The API returns standard HTTP status codes with detailed error messages.

{
  "status": "error",
  "req_id": "acMMsjP9",
  "error": [
    {
      "msg": "Error description",
      "type": "error_type"
    }
  ]
}

Response fields:

status - Always "error" for failed requests
req_id - Unique request identifier for debugging
error - Array of error objects with msg (description) and type (error category)

API reference

Webhook reference

Billing Web SDK

FunnelFox Payments API

Base URL

Authentication

Secret key

Access groups

Available endpoints

Making requests

Path parameters

Request body

Example request

Response format

Example response

Filtering

Error handling

​Base URL

​Authentication

​Secret key

​Access groups

​Available endpoints

​Making requests

​Path parameters

​Request body

​Example request

​Response format

​Example response

​Filtering

​Error handling

Base URL

Authentication

Secret key

Access groups

Available endpoints

Making requests

Path parameters

Request body

Example request

Response format

Example response

Filtering

Error handling