Skip to main content

Getting Started

This guide walks you through setting up PortaAIM for the first time — from registration to sending your first charge.

Step 1: Register Your Account​

  1. Navigate to the PortaAIM registration page
  2. Enter your company name, email address, and password
  3. Select your country and billing currency. The currency denominates every plan, service, vendor cost and invoice, a new customer defaults to it, and it cannot be changed after your account is created
  4. Complete the reCAPTCHA verification
  5. Check your email for a 6-digit verification code (or click the magic link)
  6. Enter the code to verify your account
Business Email Required

By default, registration with public email providers (Gmail, Yahoo, Outlook, etc.) is not allowed. You must use a business domain email address. This can be changed by an administrator via the registration_allow_public_email configuration setting.

Restricted Countries

Registration is not available from North Korea, Iran, or Cuba due to export controls.

Step 2: Complete the Setup Wizard​

After verification, the onboarding wizard guides you through five steps:

2.1 Company Profile​

Enter your company details — name, address, and contact information. This appears on invoices sent to your customers.

2.2 Tax Configuration​

Set up your tax rates. You can configure:

  • Tax rate percentage (e.g., 20% VAT)
  • Inclusive or exclusive — whether prices include tax or tax is added on top
  • What taxes apply to — subscriptions, usage charges, or both

2.3 Create Your First Service​

A service represents a type of AI capability you sell (e.g., "LLM Tokens", "Speech-to-Text Minutes"). Create at least one service with:

  • A name and a short identifier (e.g., AI-TOKENS) used by the Charging API
  • Measurement unit (tokens, minutes, API calls, etc.)
  • Billing unit and ratio (e.g., 1 billing unit = 1,000 tokens)
  • Vendor cost: No vendor cost (nothing recorded, so the cost reads as zero in margin) or Has vendor cost (records your vendor cost via default_cost_per_unit and optional per-item overrides)

2.4 Create Your First Plan​

A plan (product) bundles services together with pricing:

  • Monthly subscription fee (can be $0 for usage-only plans)
  • Per-unit pricing for each included service
  • Free quotas with overage (optional)
  • Tiered pricing (optional — coming soon)
  • Free trial (optional)

2.5 Integration Setup​

Connect your application:

  • Create an API key for the Charging API

Step 3: Test in Sandbox​

PortaAIM provides a sandbox environment for safe testing. Toggle between Live and Sandbox using the environment switcher in the top bar.

In sandbox mode:

  • All data is isolated from your live environment
  • Charges, invoices, and payments don't affect real accounts
  • The top bar shows an orange "Test Mode" indicator

You log in with your regular credentials and switch between Live and Sandbox using the environment toggle in the top navigation bar.

Step 4: Send Your First Charge​

Use the Charging API to submit a usage event:

curl -X POST https://api.portaaim.ai/api/v1/charging \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_external_id": "usr_9f3k2x",
    "services": [
      {
        "service_code": "AI-TOKENS",
        "item_code": "GPT-4-TURBO",
        "units": 1500
      }
    ]
  }'

The billing engine will:

  1. Look up the customer's plan
  2. Find the pricing for the specified service and item
  3. Calculate the charge based on the plan's rate
  4. Add the charge against the customer's credit limit. If the resulting balance would exceed the credit limit, the charge for paid services is rejected (subscription fees continue to accrue regardless).

Step 5: Go Live​

Once you've tested your setup in sandbox:

  1. Switch to the Live environment
  2. Create your services and plans in the live environment (or clone them from sandbox)
  3. Update your application to use the live API key
  4. Start onboarding real customers

Next Steps​