Maxio

Sync customer and subscription data from your warehouse to Maxio (Advanced Billing). Keep your Maxio customer records and subscriptions enriched with the latest profile data, billing details, and metadata from your data warehouse.

Prerequisites

A Maxio Advanced Billing account
A Maxio API key with write access to Customers and/or Subscriptions
Your Maxio subdomain (the part before .chargify.com in your account URL)

Authentication

Maxio uses API key authentication via HTTP Basic Auth.

API Key

Log in to your Maxio Advanced Billing dashboard
Navigate to Config (gear icon) > Integrations > API Keys
Copy an existing API key, or click Create API Key to generate a new one
Paste the API key into the API Key field in Zeotap

Maxio authenticates via HTTP Basic Auth using the API key as the username and x as the password. Zeotap handles this encoding automatically.

Important: API keys have full read/write access to your Maxio account. Store them securely and rotate them periodically.

Configuration

Field	Type	Required	Description
Subdomain	Text	Yes	Your Maxio subdomain. For example, if your account URL is `acme.chargify.com`, enter `acme`.

Target Settings

Field	Type	Required	Description
Maxio Object	Select	Yes	The Maxio object to sync data to: Customers or Subscriptions.
ID Field	Text	No	The name of the mapped field containing the Maxio customer or subscription ID for update and upsert operations. Leave blank to always create new records in insert mode.

Supported Operations

Sync Modes

Mode	Supported
Upsert	Yes
Insert	Yes
Update	Yes
Mirror	—

Audience Sync Modes

Mode	Supported
Add	—
Remove	—
Mirror	—
Upsert	—

Maxio does not have a list or audience membership concept, so audience sync modes are not supported.

Features

Field Mapping: Yes
Schema Introspection: No — Maxio customer and subscription fields are well-known and provided as default destination fields

Required Mapping Fields

Object	Required Fields
Customers	`first_name`, `last_name`, `email`
Subscriptions	`product_handle`, `customer_id`

Default Destination Fields

Customer Fields

Field	Type	Description
`first_name`	string	Customer’s first name
`last_name`	string	Customer’s last name
`email`	string	Customer’s email address
`organization`	string	Customer’s organization or company name
`phone`	string	Customer’s phone number
`address`	string	Customer’s street address
`city`	string	Customer’s city
`state`	string	Customer’s state or province
`zip`	string	Customer’s postal/ZIP code
`country`	string	Customer’s country
`reference`	string	Unique external reference for the customer (e.g. your internal ID)

Subscription Fields

Field	Type	Description
`product_handle`	string	API handle of the Maxio product
`customer_id`	string	Maxio customer ID that owns this subscription
`customer_reference`	string	External reference of the customer (alternative to `customer_id`)
`product_id`	string	Numeric Maxio product ID (alternative to `product_handle`)
`reference`	string	Unique external reference for the subscription

Only the standard fields listed above are synced to Maxio. Non-standard fields are silently dropped. Maxio metadata (custom fields) must be managed separately via the Maxio metadata API and cannot be sent inline with customer or subscription records.

How It Works

Field Mapping: Zeotap maps your warehouse columns to Maxio object fields. Standard fields (first_name, last_name, email, etc.) are sent as top-level parameters. Non-standard fields are dropped — only well-known Maxio fields are synced.
Request Format: Maxio uses JSON request bodies. Each object is wrapped in a singular root key — {"customer": {...}} for customers and {"subscription": {...}} for subscriptions. Zeotap handles this wrapping automatically.
Per-Record API Calls: Maxio does not offer a batch API for customer or subscription management. Each row in your sync results in a single API call. Zeotap processes rows sequentially within each batch.
Sync Mode Behavior:
- Insert: Creates a new object for every row via POST /{object_type}.json.
- Update: Updates an existing object via PUT /{object_type}/{id}.json. Requires a Maxio object ID in the configured ID field.
- Upsert: If a Maxio object ID is present, attempts to update the object. If the object does not exist (404), creates a new one. If no ID is present, creates a new object.
Error Handling: Failed rows are tracked individually with per-row error details. Transient errors (rate limits, server errors) are retried automatically with exponential backoff.

Rate Limits

Maxio enforces rate limits on API requests. The exact limits depend on your account plan, but the standard limits are approximately 120 requests per minute per API key.

Zeotap automatically handles rate limiting:

HTTP 429 responses trigger exponential backoff with retry
Up to 3 retries per request

Because Maxio has no batch API, syncing large datasets (10,000+ customers) may take considerable time. Consider scheduling syncs during off-peak hours if you are close to your rate limit.

Best Practices

Start with a small test sync: Use a limited dataset to verify field mappings before syncing your full customer base.
Map the ID field for upserts: For upsert and update modes, always configure the ID Field in target settings and map a column containing the Maxio customer or subscription ID. Without it, upsert mode creates duplicate records.
Pre-configure metafields: Custom fields sent as metafields must be defined in your Maxio account before syncing. Navigate to Config > Custom Fields to set them up.
Use the reference field: The reference field is useful for storing your internal customer or subscription ID in Maxio, making it easier to correlate records across systems.
Sync customers before subscriptions: Subscriptions require a customer_id. Sync your customers first, then use the resulting Maxio customer IDs to create subscriptions.

Troubleshooting

Authentication failed: invalid API key or subdomain

Verify that your API key is correct and has not been revoked. Check that the subdomain matches your Maxio account URL exactly (e.g., acme from acme.chargify.com). Regenerate the key in the Maxio dashboard under Config > Integrations > API Keys if needed.

Object ID is required for update mode

Update mode requires a Maxio object ID for each row. Ensure the ID Field is configured in target settings and that the corresponding column in your warehouse contains valid Maxio IDs. Use insert mode if you want to create new records without an ID.

Rate limiting (429 errors)

Maxio limits API requests to approximately 120 per minute. Zeotap retries automatically, but persistent rate limit errors may indicate too many concurrent syncs or other applications sharing the same API key. Reduce sync frequency or stagger your sync schedules.

Non-standard fields not appearing in Maxio

Only well-known Maxio fields (listed in the Default Destination Fields tables above) are synced. Non-standard fields are silently dropped. If you need to sync custom data, use the Maxio metadata API separately or map your data to one of the supported standard fields.

Customer not found (404) in update mode

The Maxio customer ID in your data does not match an existing customer. Verify the ID column contains valid numeric Maxio customer IDs. In upsert mode, a 404 triggers automatic creation of a new customer.

Subscription creation fails with missing product

Subscriptions require a valid product_handle or product_id. Verify the product exists in your Maxio catalog by checking Setup > Products in the dashboard. Product handles are case-sensitive.

Subscription creation fails with invalid customer

Subscriptions require a valid customer_id or customer_reference. Ensure the customer has already been created in Maxio before attempting to create a subscription. Consider syncing customers first in a separate sync job.

Sync is slow for large datasets

Maxio does not offer a batch API — each record requires an individual API call. At approximately 120 requests per minute, syncing 10,000 records takes about 83 minutes. Schedule large syncs during off-peak hours and consider breaking them into smaller incremental syncs.