Skip to main content

API Reference

Subscriptions

Import subscription data for MRR and churn analytics. Uses the secret key for authentication. Companies are matched by the customer_domain field on each subscription.

Import Subscriptions

POST /api/v1/subscriptions Secret Key

Full-replacement import of subscriptions and invoices. All existing data for the account is replaced.

Parameters

Parameter Type Required Description
currency string Yes ISO 4217 currency code (e.g. "USD", "EUR")
subscriptions array Yes Array of subscription objects
invoices array No Array of invoice objects
contacts array No Array of contact objects to upsert (matched by email)

Subscription Object

Field Type Required Description
external_id string Yes Unique identifier from your system
customer_domain string Yes Company domain (e.g. "acme.com") — used to find or create a company
customer_name string No Customer display name (used as company name when creating a new company)
amount_cents integer Yes Subscription amount in cents
interval string Yes "month", "quarter", or "year"
status string Yes One of: active, canceled, past_due, trialing, paused
plan_name string No Name of the plan
started_at string Yes ISO 8601 datetime
canceled_at string No ISO 8601 datetime
ended_at string No ISO 8601 datetime
quantity integer No Number of units (e.g. seats)
renewal_probability float No 0 to 1
payment_provider string No "xero" or "stripe"
payment_provider_customer_id string No Customer/contact ID in the payment provider

Invoice Object

Field Type Required Description
external_id string Yes Unique identifier from your system
subscription_external_id string No Links to a subscription's external_id
invoice_number string No Human-readable invoice number (e.g. "INV-0042")
amount_cents integer Yes Invoice amount in cents
status string No Invoice status
currency string No ISO 4217 code (if different from account currency)
issued_at string No ISO 8601 datetime
paid_at string No ISO 8601 datetime
period_start string No ISO 8601 datetime
period_end string No ISO 8601 datetime
payment_provider_id string No Invoice ID in the payment provider

Contact Object

Field Type Required Description
email string Yes Contact email (used as unique key for upsert)
first_name string No First name
last_name string No Last name
phone string No Phone number
job_title string No Job title
country string No Country code or name
contact_type string No Contact type classification

Success Response

{
  "status": "ok",
  "warnings": [
    {
      "entity": "invoice",
      "index": 0,
      "external_id": "inv_123",
      "message": "currency 'GBP' differs from account currency 'USD'"
    }
  ]
}

Error Response (422)

{
  "errors": [
    {
      "entity": "subscription",
      "index": 0,
      "message": "customer_domain is required"
    }
  ]
}