ConvertmaxDocumentation
Talk to usGet started
Convertmax API

Convertmax API

Use api.convertmax.io to send product, contact, and order data to Convertmax, read subscription reports, retrieve records, and understand authentication, scopes, and idempotency.

Copy page
Open in ChatGPTOpen with page contextOpen in ClaudeOpen with page context

Base URL: https://api.convertmax.io

Use this API to send product, contact, and order data from your store or CRM into Convertmax, retrieve individual records, and read subscription reports. For analytics events such as page views and conversions, use the separate Event API on event.convertmax.io.

Authentication

Send your API key on every request:

  • Authorization: Bearer private-<your_key>
  • x-api-key: private-<your_key>

Products

Method Endpoint Description
POST /v1/products Create or update a product
DELETE /v1/products Delete a product
GET /v1/products/:id Get a product by SKU

Create or update

curl -X POST https://api.convertmax.io/v1/products \
  -H "Authorization: Bearer private-<your_key>" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: product:upsert:sku-42" \
  -d '{
    "entityType": "product",
    "id": "sku-42",
    "sourceUpdatedAt": "2026-05-26T12:00:00.000Z",
    "data": {
      "sku": "sku-42",
      "name": "Example product"
    }
  }'

Successful requests return 202 Accepted.

Get by SKU

curl https://api.convertmax.io/v1/products/sku-42 \
  -H "Authorization: Bearer private-<your_key>"

Contacts

Method Endpoint Description
POST /v1/contacts Create or update a contact
DELETE /v1/contacts Delete a contact
GET /v1/contacts/:id Get a contact by ID

Orders

Method Endpoint Description
POST /v1/orders Create or update an order
DELETE /v1/orders Delete an order
GET /v1/orders/:id Get an order by ID

Subscriptions

Read-only subscription reports. Every route requires the subscriptions:read scope and a currency query parameter (for example USD). Totals stay in that currency. The tenant comes from the API key.

Method Endpoint Description
GET /v1/subscriptions/overview MRR, ARR, ARPA, active subscriptions, accounts, exclusions, coverage, attention counts, acquisition, invoiced and collected amounts, and 30-day MRR movements
GET /v1/subscriptions/attention Payment issues, renewals, scheduled cancellations, and upcoming billing
GET /v1/subscriptions/acquisition Current MRR by acquisition source, plus retained MRR when snapshot coverage allows it
GET /v1/subscriptions/account Account summary, subscription items, and timeline

Query parameters

  • currency — required on every subscription route
  • days — attention window: 30, 60, or 90 (default 30)
  • horizon — acquisition window: 30, 60, or 90 (default 30)
  • customer — account lookup
  • subscription_id — account lookup by subscription
  • page_size — rows per list, default 50, max 100

List fields are paged. Each list returns results, page, page_size, count, and pages. A page past the end has empty results.

Route List Page query
overview accounts page
overview acquisition sources acquisition_page
overview exclusions exclusion_page
attention payment issues, renewals, cancellations, upcoming billing issue_page, renewal_page, cancel_page, billing_page
acquisition sources page
account items, timeline page, timeline_page 
curl "https://api.convertmax.io/v1/subscriptions/overview?currency=USD" \
  -H "Authorization: Bearer private-<your_key>"
curl "https://api.convertmax.io/v1/subscriptions/attention?currency=USD&days=30" \
  -H "Authorization: Bearer private-<your_key>"
curl "https://api.convertmax.io/v1/subscriptions/account?currency=USD&customer=acct_123" \
  -H "Authorization: Bearer private-<your_key>"

Events

Method Endpoint Description
GET /v1/events List normalized non-conversion events for the authenticated tenant
GET /v1/conversions List normalized conversion events for the authenticated tenant

Query parameters

Both endpoints support:

  • limit — number of rows to return, default 50, max 100
  • offset — pagination offset, default 0
  • event_type — exact event type filter
  • since — inclusive ISO 8601 timestamp filter
  • until — inclusive ISO 8601 timestamp filter

Conversion response shape

GET /v1/conversions returns normalized rows with fields such as:

  • id
  • occurred_at
  • conversion_type
  • source
  • source_object_id
  • amount
  • currency
  • profile_id
  • contact_id
  • contact_name
  • contact_email
  • company_name
  • integration_id

Example:

curl "https://api.convertmax.io/v1/conversions?limit=10" \
  -H "Authorization: Bearer private-<your_key>"

Request body

Use the same JSON shape for products, contacts, and orders.

Create or update (POST)

Field Required Description
entityType Yes product, contact, or order
id Yes Your identifier for the record
sourceUpdatedAt Yes When the record last changed in your system (ISO 8601)
externalId No Optional secondary ID
idempotencyKey No Optional; you can also send x-idempotency-key as a header
data No Fields for the record (defaults to {})

Delete (DELETE)

Field Required Description
entityType Yes product, contact, or order
sourceUpdatedAt Yes When the delete occurred in your system (ISO 8601)
id or externalId One required Which record to remove
data No For products, you can pass sku or code instead

Repeating the same idempotency key returns 200 with "duplicate": true and does not apply the change again.

  • Event API — analytics and conversion events on event.convertmax.io
  • Event Tracking — supported event names and client examples