Partner API

The Partner API is for platforms that embed Chargetree. It lets you create a fully set-up Chargetree account for one of your customers, keep its details in step with your own records, and issue the API key that customer's integration will use.

If you are raising invoices inside a single account, you want the Public API instead.

How partner access differs

A partner key manages account records. It does not act inside any account:

It can create, read, update and deactivate the accounts you own.
It cannot raise an invoice, read a contact, or see anything belonging to an account.

To act inside an account you use that account's own key (ct_live_…), which the create call hands you once.

Authorization: Bearer ct_partner_8x3kQp9zR2mN6vT4yL1bH7sW0jD5fA3c

Every request is scoped to your partnership, so you can only ever see and change your own accounts.

Creating an account

Accounts created this way never pass through Chargetree's onboarding screens, so the create call carries everything onboarding would otherwise collect. Only two fields are required:

curl -X POST https://manage.chargetree.co/api/v1/partner/accounts \
  -H "Authorization: Bearer ct_partner_..." \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Northside Electrical",
    "email": "owner@northside.example",
    "external_id": "crm-9931",
    "webhook_url": "https://partner.example/hooks/chargetree",
    "brand_color": "#46E9A3",
    "logo_url": "https://partner.example/logos/northside.png"
  }'

One call builds the login, the payment page, the first API key and — when you supply a webhook_url — the webhook endpoint and its signing secret.

Two values you can never read again

The create response carries secrets that are shown exactly once:

{
  "id": "9f8e7d6c-…",
  "company_name": "Northside Electrical",
  "matched": false,
  "api_key": "ct_live_8x3kQp9zR2mN6vT4yL1bH7sW0jD5fA3c",
  "webhook_signing_secret": "3pQ8vR2nM6tZ9wL1jH4fA7gE0uI5oP4qRsX2yB6cD8k"
}

Store both immediately

api_key and webhook_signing_secret cannot be retrieved later. The key can be replaced by rotating it; the signing secret can only be replaced by recreating the endpoint. Write both to your secret store in the same step that makes this call.

What you can read later is api_key_info — the prefix, last four characters and creation date. It tells you which key an account is using without being usable as a credential.

Making the create call safe to retry

Send external_id: your own identifier for the customer.

If you call again with the same external_id, Chargetree returns the account it already made rather than creating a duplicate:

{
  "id": "9f8e7d6c-…",
  "matched": true,
  "secrets_note": "This account already existed. Its API key cannot be re-read; rotate it if you no longer have it."
}

The difference is matched: false means you just created it, true means it already existed. Note the 200 rather than 201, and note that no secrets come back — they cannot be read twice.

Without an external_id a repeated call either creates a second account or fails with CONFLICT because the email is taken. Sending one is strongly recommended.

Finding an account again

curl "https://manage.chargetree.co/api/v1/partner/accounts?external_id=crm-9931" \
  -H "Authorization: Bearer ct_partner_..."

email is always null when listing

For speed, the list endpoint does not look up owner emails — email comes back as null for every record, including in an external_id lookup. Fetch the account on its own, GET /partner/accounts/{id}, when you need it.

Updating an account

PATCH changes only the fields you send, and you must send at least one — a mistyped field name fails loudly rather than quietly doing nothing.

The owner's email cannot be changed, because it is their login.

Changing webhook_url repoints the existing endpoint and keeps its signing secret, so no new secret comes back. Your handler keeps working.

Switching an account off

DELETE is a deactivation, not a deletion. The account's status becomes inactive and nothing is erased, so you can switch it back on with PATCH.

While inactive, that account's own API key stops working: its requests are refused with ACCOUNT_DISABLED, and the message names you as the party who switched it off.

Rotating an account's key

curl -X POST https://manage.chargetree.co/api/v1/partner/accounts/{id}/api-key \
  -H "Authorization: Bearer ct_partner_..."

This issues a fresh key and immediately revokes every previous one. There is no grace period, so anything still using the old key breaks the moment this returns. Deploy the new key before the next request goes out.

Field rules worth knowing

Field	Rule
`brand_color`	A six digit hex value such as `#46E9A3`. Shorthand and named colours are rejected rather than guessed at, because a colour we cannot read would silently drop the branding
`logo_url`	A public HTTPS address. We download the image and keep our own copy rather than linking to yours. PNG or JPEG, under 1 MB. SVG is not accepted
`webhook_url`	Must be HTTPS — payloads carry customer details
`payment_slug`	A suggestion. It is tidied into a URL-safe form and given a numeric suffix if taken, so what comes back may differ from what you asked for
`communications_enabled`	Must be a real `true` or `false`. A string that merely looks true is rejected, because a typo here would start contacting a customer's customers

Anything wrong with the logo comes back as a 400 against logo_url with a specific message — too large, not an image, unreachable, timed out — rather than a generic failure.

Webhooks for partner accounts

An account created with a webhook_url is automatically subscribed to:

invoice.payment_recorded
escalation.created
escalation.resolved

The payload, signature scheme and retry behaviour are identical to any other endpoint. See Webhooks.

Endpoint reference

Full request and response details for each endpoint are in the Partner accounts reference.

On this page