canonical: https://jentic.com/apis/chargify.com/chargify

# Chargify API

Chargify (now branded as Maxio Advanced Billing) is a subscription billing and revenue management platform aimed at B2B SaaS companies with complex pricing models. The API exposes subscriptions, customers, products, invoices, components (metered usage and on-off entitlements), one-off charges, and payment profiles. Resources are subdomain-scoped per merchant and use Chargify's longstanding .json suffix path style. It is a strong fit for usage-based billing, hybrid pricing, and SaaS workflows that need component-level granularity.

## For AI agents

Manage subscriptions, customers, products, invoices, components, and payment profiles for usage-based and B2B SaaS billing. Useful for finance ops, billing automation, and revenue management agents.

## Scope

Does not handle card processing on the network rails, fraud scoring, or chargeback representment - use for subscription, component, customer, and invoice billing logic only.

## Capabilities

- Manage the subscription lifecycle through the /subscriptions.json endpoints, including create, update, retrieve, and cancel operations
- Maintain customer records with /customers.json (list, create, retrieve, update, delete) and tie them to subscriptions
- Define products and product families via /products.json so subscriptions can reference a priced offering
- Pull invoice history with /invoices.json and retrieve a single invoice by ID for finance reporting
- Read and report metered usage components per subscription via `/subscriptions/{subscription_id}/components.json`
- Apply one-off charges to a subscription with POST `/subscriptions/{subscription_id}/charges.json`
- Manage stored payment methods through /payment_profiles.json including create, retrieve, and delete

## Use cases

### Usage-Based SaaS Billing

B2B SaaS companies with metered or hybrid pricing use Chargify components to bill on units consumed (API calls, seats, GB processed). The `/subscriptions/{subscription_id}/components.json` endpoint exposes per-subscription usage and component allocations, letting finance teams report and reconcile usage against the underlying subscription term.

Example prompt: GET `/subscriptions/{subscription_id}/components.json` for each active subscription and report the current usage totals

### Subscription Lifecycle Management

Finance and customer success teams manage subscriptions over their full life: POST /subscriptions.json to start, PUT `/subscriptions/{subscription_id}.json` to change plan or seat count, DELETE `/subscriptions/{subscription_id}.json` to cancel. Chargify handles proration and invoicing so the integrator does not have to compute partial-period adjustments manually.

Example prompt: PUT `/subscriptions/{subscription_id}.json` to change the plan and let Chargify generate the proration invoice

### One-Off Charges and Account Adjustments

Sales and support teams add one-off line items - onboarding fees, professional services, overage true-ups - to a subscription via POST `/subscriptions/{subscription_id}/charges.json.` The charge appears on the subscription's next invoice (or immediately, depending on settings) and is included in revenue reporting alongside recurring components.

Example prompt: POST `/subscriptions/{subscription_id}/charges.json` with an amount of 250.00 USD for a customer onboarding fee

### Payment Profile Hygiene

When a customer rotates cards or asks for their payment data to be removed, finance ops uses /payment_profiles.json to manage stored payment methods. POST creates a new profile, GET inspects the current state, and DELETE `/payment_profiles/{payment_profile_id}.json` removes the record cleanly so future charges fall back to a different method or fail predictably.

Example prompt: DELETE `/payment_profiles/{payment_profile_id}.json` when a customer requests their card on file be removed

### Agent-Driven Billing via Jentic

An AI agent given an instruction like 'add a $500 services charge to subscription 12345' can resolve the workflow through Jentic. It searches for the one-off charge operation, loads the schema for POST `/subscriptions/{subscription_id}/charges.json`, and submits the charge - without ever holding the merchant's Chargify credential directly.

Example prompt: Search Jentic for 'add a one-off charge to a subscription' and POST the charge with the agreed amount and description

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/subscriptions.json` | Create a subscription |
| PUT | `/subscriptions/{subscription_id}.json` | Update a subscription |
| DELETE | `/subscriptions/{subscription_id}.json` | Cancel a subscription |
| POST | `/subscriptions/{subscription_id}/charges.json` | Add a one-off charge |
| GET | `/subscriptions/{subscription_id}/components.json` | List components and usage for a subscription |
| POST | `/customers.json` | Create a customer |
| GET | `/invoices.json` | List invoices |
| POST | `/payment_profiles.json` | Create a stored payment profile |

## Key resources

- **Subscriptions** — Recurring subscription records with create, update, retrieve, and cancel operations
- **Customers** — Customer records associated with one or more subscriptions
- **Products** — Priced offerings that subscriptions reference
- **Invoices** — Issued invoices retrievable by ID for reporting
- **Components** — Metered and on-off entitlements that drive usage-based billing per subscription
- **Payment Profiles** — Stored payment methods that subscriptions charge against

## Why Jentic

- **Setup:** Wiring Chargify by hand means handling its HTTP Basic auth with the API key as the username, resolving your account subdomain into the host, and attaching credentials to every billing call yourself. Through Jentic you install once, import Chargify from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Chargify puts the subscription id in the URL path (`/subscriptions/{subscription_id}...`), so a rule can pin your agent to one subscription: it can add charges and read components for that subscription and nothing else. You choose the operations it may call, so subscription deletion is not included unless you add it.
- **Credential handling:** Your Chargify API key is stored once, encrypted, by your own Jentic One instance and used to sign the Basic auth header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a subscription' or 'add a one-off charge', and Jentic returns the matching Chargify operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Recurly API** — Recurly is a comparable SaaS subscription billing platform with broader native payment processor coverage; Chargify focuses on usage-based and B2B billing.
- **Zuora API** — Zuora is enterprise subscription billing with deep revenue recognition; Chargify is mid-market with a faster integration path.
- **Stripe API** — Stripe processes the underlying card payments while Chargify orchestrates subscriptions, components, and invoices on top.

## FAQ

### What authentication does the Chargify API use?

Chargify uses HTTP Basic authentication: pass your API key as the username and the literal string 'x' as the password. Through Jentic, the API key is held in your Jentic One instance and only injected server-side at execution time.

### Can I add a one-off charge to an existing subscription with the Chargify API?

Yes. POST `/subscriptions/{subscription_id}/charges.json` with an amount and memo. Chargify adds the line item to the subscription's next invoice or processes it immediately depending on the merchant's settings.

### How do I track metered usage for a subscription?

GET `/subscriptions/{subscription_id}/components.json` returns the components configured on the subscription with their current usage values. Chargify uses these counts at the next renewal to compute the metered portion of the invoice.

### What are the rate limits for the Chargify API?

Chargify does not publish a fixed public rate limit; production limits depend on your plan. Cache /products.json and /customers.json reads where possible and back off on HTTP 429 responses, especially during end-of-billing-period bursts.

### How do I create a subscription through Jentic?

Install jentic with pip install jentic, search for 'create a chargify subscription', load the schema for POST /subscriptions.json, and execute with the customer and product IDs. Run Jentic One, the self-hosted execution layer, to issue an agent API key.

### Does the Chargify API support storing multiple payment methods per customer?

Yes. POST /payment_profiles.json creates a new payment method tied to a customer, GET `/payment_profiles/{payment_profile_id}.json` inspects an individual record, and DELETE removes one. A customer can hold several stored profiles with one designated as the default for charges.

### Can I limit what my agent is allowed to do with the Chargify API?

Yes. Because Chargify puts the subscription id in the URL path, such as `/subscriptions/{subscription_id}/charges.json`, your self-hosted Jentic One instance lets you write rules that pin the agent to a single subscription so it can add one-off charges and read components for that subscription and nothing else. You choose which operations the agent may call, so destructive actions like DELETE `/subscriptions/{subscription_id}.json` stay off the table unless you explicitly allow them. Your own rules decide which operations and stored credentials the agent can use at execution time.