eCom9eCom9
API Referencev1
API reference

ecom9 API Documentation

Access transactions, product catalogs, subscription state, and tier data for your connected accounts. Every request is authenticated with your Payment Gateway keys. See Subscription Event Handling: Design Patterns and Best Practices for lifecycle event guidance.

Getting Your API Key

  1. Sign in to the ecom9 dashboard.
  2. Open Payment Gateways.
  3. Select your active sandbox or live gateway.
  4. Copy the API Key and signing key ID from the gateway details and store them securely.

Integration Overview

account_ref_id is the primary identity key between ecom9 and your software. Use it to map customers, orgs, or workspaces and keep the same value across all API calls.

  • Required on most endpoints: pass account_ref_id on requests that read or write billing state.
  • Stable and internal: choose an immutable ID from your system (user/org/workspace) to avoid remapping later.
  • Consistent across systems: we echo account_ref_id back in responses and webhook payloads.

Sandbox and production API keys are available in the dashboard under Payment Gateways, letting you pick the right environment per deployment.

Prefer using an SDK? Jump to SDK Examples for language-specific snippets that call each endpoint.

Authentication

All endpoints require your Payment Gateway API key. Include it with each request using one of the supported headers.

Option 1: Authorization header (recommended)

Authorization: Bearer YOUR_API_KEY

Option 2: X-API-Key header

X-API-Key: YOUR_API_KEY

Base URL: https://app.ecom9.com/api/

Test with curl

curl -s https://app.ecom9.com/api/tiers/pro-plan/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

Base URL: https://app.ecom9.com/api/

Get Transactions by Account Reference ID

Retrieve the full transaction history for a specific account reference.

Request URL

GET https://app.ecom9.com/api/transactions/ACC123456789/?page=1&page_size=20

Parameters

  • account_ref_id — path parameter (required)
  • page — query parameter (optional, default 1)
  • page_size — query parameter (optional, default 20, max 100)
  • status — query parameter (optional: pending, completed, failed, cancelled)

Example response

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "transaction_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "account_ref_id": "ACC123456789",
      "status": "completed",
      "amount": "29.99",
      "currency": "usd",
      "customer_email": "customer@example.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z"
    }
  ]
}

Check Account Status

Return the live subscription state for an account reference, optionally filtered to a specific subscription + tier combination.

Request URL

GET https://app.ecom9.com/api/account/F8xQ2PnL7vKd93sH/status/?subscription=studio-suite&tier=pro

Parameters

  • account_ref_id — path parameter (required)
  • subscription — query parameter (optional subscription label, required whenever tier is provided)
  • tier — query parameter (optional tier label, only evaluated when paired with subscription)

Example response

{
  "account_ref_id": "TWY4k2ZQPp19s8Hd",
  "is_active": true,
  "customer_email": "orchid.ops@examplemail.com",
  "created_at": "2024-03-02T14:11:27Z",
  "updated_at": "2024-03-02T14:11:27Z",
  "subscription_tier": {
    "label_name": "pro",
    "name": "Aurora Growth",
    "description": "45k send limit and co-marketing boosts",
    "price": "32.00",
    "billing_cycle": "monthly",
    "features": "Deliverability audits, Campaign playbooks, Concierge migrations",
    "is_popular": true,
    "product_manage_id": "P6ZmR29aTyQb"
  }
}

Example response (multiple subscriptions)

{
  "account_ref_id": "TWY4k2ZQPp19s8Hd",
  "customer_email": "orchid.ops@examplemail.com",
  "subscriptions": [
    {
      "is_active": false,
      "created_at": "2023-12-18T09:54:12Z",
      "updated_at": "2024-01-01T00:00:00Z",
      "subscription_tier": {
        "label_name": "starter",
        "name": "Pulse Lite",
        "description": "5k send trial bundle",
        "price": "0.00",
        "billing_cycle": "monthly",
        "features": "API sandbox, Limited automation",
        "is_popular": false,
        "product_manage_id": "V8bLw4cNq0Xs"
      }
    },
    {
      "is_active": true,
      "created_at": "2024-03-02T14:11:27Z",
      "updated_at": "2024-03-02T14:11:27Z",
      "subscription_tier": {
        "label_name": "pro",
        "name": "Aurora Growth",
        "description": "45k send limit and co-marketing boosts",
        "price": "32.00",
        "billing_cycle": "monthly",
        "features": "Deliverability audits, Campaign playbooks, Concierge migrations",
        "is_popular": true,
        "product_manage_id": "P6ZmR29aTyQb"
      }
    }
  ],
  "total_subscriptions": 2
}

List Products

Return the products for the authenticated user's profile and payment gateway, ordered by title.

Request URL

GET https://app.ecom9.com/api/products/

Response fields

  • manage_id — product's unique manager ID
  • label_name — label name (for SaaS/subscription use)
  • type — product type (single or subscription)
  • price — price for single products only

Example response

{
  "results": [
    { "manage_id": "abc12xyz", "label_name": "my-product", "type": "single", "price": "49.99" },
    { "manage_id": "def34uvw", "label_name": "pro-plan", "type": "subscription" }
  ],
  "count": 2
}

Create Invoice

Create a Stripe-hosted invoice for a product and return the hosted payment URL. Optionally email the invoice to the customer.

Request URL

POST https://app.ecom9.com/api/invoices/create/

Sample payload

{
  "product_manage_id": "AlC3WiWyOIN1",
  "amount": 25.00,
  "customer_email": "client@example.com",
  "currency": "usd",
  "description": "Website development - Phase 1",
  "account_ref_id": "usr_abc123",
  "send_to_customer": true,
  "return_url": "https://yourapp.com/invoice/success"
}

Example response

{
  "hosted_invoice_url": "https://invoice.stripe.com/i/acct_xxx/...",
  "stripe_invoice_id": "in_1ABCdef...",
  "email_sent": true,
  "return_url": "https://app.example.com/thank-you"
}

Get Invoices

Retrieve invoices for an account. Optionally filter by email or status.

Request URL

GET https://app.ecom9.com/api/invoices/

Query parameters

  • account_ref_id - (optional) account reference ID
  • email - (optional) customer email
  • status - (optional) filter by status: draft, open, paid, uncollectible, void
  • page - (optional) page number (default 1)
  • page_size - (optional) items per page (default 20, max 100)
At least one of account_ref_id or email is required.

Example response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "stripe_invoice_id": "in_1TJJ5rAaxKcgrBGsDZAY79gt",
      "account_ref_id": "usr_abc123",
      "status": "paid",
      "is_paid": true,
      "amount_due": 25.00,
      "amount_paid": 25.00,
      "currency": "usd",
      "customer_email": "client@example.com",
      "invoice_date": "2026-04-06T19:46:00Z",
      "due_date": "2026-05-06T19:46:00Z",
      "period_start": null,
      "period_end": null,
      "hosted_invoice_url": "https://invoice.stripe.com/i/...",
      "stripe_subscription_id": "",
      "product_manage_id": "AlC3WiWyOIN1",
      "created_at": "2026-04-06T19:46:00Z",
      "updated_at": "2026-04-06T19:47:00Z"
    }
  ]
}

Get Available Subscription Tiers

List every tier configured for a subscription product so you can display pricing or validate selection on the client side.

Request URL

GET https://app.ecom9.com/api/tiers/{subscription_name}/?page=1&page_size=20

Path parameters

  • subscription_name — required; the label_name of the subscription product

Example response

{
  "count": 3,
  "results": [
    {
      "label_name": "basic",
      "name": "Basic Plan",
      "description": "Essential features for getting started",
      "price": "9.99",
      "billing_cycle": "monthly",
      "features": "Basic features, Email support",
      "is_popular": false,
      "product_manage_id": "ABC123DEF456"
    }
  ]
}

Resolve Public URL

Fetch the customer-facing link for a SaaS product or tier before appending your signed ?u= token. The resolver only returns URLs for catalog entries tagged saas_only.

Mandatory requirements

  • account_ref_id is required on every request and must match the account that owns the subscription.
  • When resolving by subscription_name + tier_name for a saas_only subscription product, include email so we can match the subscriber.
  • When resolving a single product_name that is saas_only, include email to attach the SaaS customer record correctly.
  • We recommend sending email for SaaS checkout links so customers do not pay with a different email that is harder to reconcile later. We do not lock buyers to that email, but it is required for subscription generation URLs.
  • Non-SaaS catalog items respond with 404 Not Found. Confirm the access mode before resolving.

Request URL

GET https://app.ecom9.com/api/resolve/public-url/?product_name=onboarding&account_ref_id=demo-account-123

Parameters

  • account_ref_id — query parameter (required)
  • product_name — query parameter (optional, mutually exclusive with subscription_name + tier_name)
  • subscription_name — query parameter (optional, requires tier_name)
  • tier_name — query parameter (optional, requires subscription_name)
  • email — query parameter (required when using subscription_name + tier_name for a saas_only subscription product; required when using a product_name that is saas_only; recommended for SaaS checkout links to keep customer records consistent)

Tip: Use product_name for one-time product sales. Use subscription_name + tier_name for subscriptions with saas_mode enabled.

Subscription + tier parameters

Use when you only know the catalog names. Required query params: subscription_name, tier_name, account_ref_id, email.

curl -X GET "https://app.ecom9.com/api/resolve/public-url/?subscription_name=pro-plan&tier_name=pro&account_ref_id=demo-account-123&email=buyer%40example.com" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Single product parameters

Required query params: product_name, account_ref_id. If the product is saas_only, include email.

curl -X GET "https://app.ecom9.com/api/resolve/public-url/?product_name=onboarding&account_ref_id=demo-account-123" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Example response

{
  "type": "redirect",
  "url": "https://your-domain.com/r/8f87f8e1-2f4c-4a7f-9b67-2f49a20e6d9a/"
}

Common error payloads

{ "error": "Provide product_name or both subscription_name and tier_name" }
{ "error": "Product not found" }
{ "error": "email is required when using subscription_name and tier_name" }
{ "error": "email is required when using a saas_only product" }
{ "error": "Subscription product not found" }
{ "error": "Subscription tier not found" }

Fix Subscription

Return a hosted payment URL for the invoice that failed and put a subscription into a past-due or incomplete state.

Request URL

GET https://app.ecom9.com/api/fix-subscription/?account_ref_id=IAS0I48ZMYEF&subscription_name=pro-plan&tier_name=pro

Parameters

  • account_ref_id — query parameter (required)
  • subscription_name — query parameter (required, requires tier_name)
  • tier_name — query parameter (required, requires subscription_name)

Example response

{
  "url": "https://app.ecom9.com/pay/in_1PLsXjKz8C7Demo"
}

If there is no past-due invoice or the subscription is already active, the response body is empty.

Error Responses

401 Unauthorized
{
  "detail": "Invalid API key"
}
404 Not Found
{
  "error": "Account not found or invalid subscription tier"
}
400 Bad Request
{
  "field_name": ["Error message describing the issue"]
}

Rate Limiting

If you exceed your plan's rate limit, responses include 429 Too Many Requests. Inspect the Retry-After header before retrying.

Data Privacy

  • Only data tied to your Payment Gateway account is returned.
  • Customer email addresses appear for identification only.
  • Sensitive payment identifiers (Stripe IDs) are never exposed.
  • All timestamps use UTC (ISO 8601) format.

SDK Examples

The official SDKs wrap the REST endpoints so you can keep signing, pagination, and retries consistent across services. Use the tabs to switch languages.

Get Transactions

from ecom9_sdk import Ecom9Client

client = Ecom9Client(api_key="YOUR_API_KEY")

transactions = client.transactions.list(
  account_ref_id="ACC123456789",
  page=1,
  status="completed"
)

for entry in transactions.results:
  print(entry["transaction_uuid"], entry["status"])

Check Account Status

status = client.accounts.status(
  account_ref_id="ACC123456789",
  tier="pro"
)

print(status["is_active"], status["subscription_tier"]["label_name"])

Get Subscription Tiers

tiers = client.tiers.list()

print([tier["label_name"] for tier in tiers["results"]])

Resolve Public URL

Use the SDK helper to wrap /api/resolve/public-url/. Refer to the endpoint documentation above for required parameters and SaaS-only constraints.

public_url = client.links.resolve_public_url(
  product_name="onboarding",
  account_ref_id="demo-account-123",
)

print(public_url["public_url"])

Support

Need a new endpoint or payload tweak? Reach the team through your dashboard chat or email support, and we'll scope it with you.