Partner accounts

The Chargetree accounts you provision and manage. Creating an account also creates its login, its payment page, its first API key and, if you supply a webhook address, its webhook endpoint and signing secret.

List accounts

GET/partner/accounts

Returns your accounts, newest first.

Supplying external_id turns this into an exact lookup: the matching account is returned on its own, and a 404 is returned if you have no account with that identifier. The lookup response carries only data and total, without the limit and offset fields.

For speed, the email field is always null in list results. Fetch a single account to read it.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Query Parameters

external_id?string

Look up one account by your own identifier instead of listing.

limit?integer

How many accounts to return. Values above 100 are capped at 100.

Range1 <= value <= 100

Default25

offset?integer

How many accounts to skip.

Range0 <= value

Default0

Response Body

`application/json`

curl -X GET "https://example.com/partner/accounts"

{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "external_id": "string",      "status": "active",      "company_name": "string",      "first_name": "string",      "last_name": "string",      "email": "string",      "phone": "string",      "abn": "string",      "timezone": "string",      "address_line1": "string",      "address_city": "string",      "address_state": "string",      "address_postal_code": "string",      "address_country": "string",      "invoice_prefix": "string",      "payment_slug": "string",      "webhook_url": "string",      "logo_url": "string",      "brand_color": "string",      "communications_enabled": true,      "api_key_info": null,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "total": 0,  "limit": 0,  "offset": 0}

Create an account

POST/partner/accounts

Builds a complete, ready-to-use Chargetree account owned by you.

The response carries two values you can never read again: the account's own API key, and the webhook signing secret when a new webhook endpoint was created. Store both immediately.

Retrying safely

Send an external_id — your own identifier for this customer. If you call again with the same external_id, Chargetree returns the account it already made, with matched: true, instead of creating a duplicate. The secrets are not repeated in that response, because they cannot be read twice; rotate the key if you have lost it.

Without an external_id, a repeated call either creates a second account or fails with CONFLICT if the email is already taken.

Logos

If you pass a logo_url, Chargetree downloads the image and keeps its own copy, rather than linking to yours. The address must be public and served over https, the image must be a PNG or JPEG, and it must be under 1 MB. Anything else comes back as a validation error against logo_url.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The business details shared by the create and update calls.

first_name?string

Lengthlength <= 100

last_name?string

Lengthlength <= 100

phone?string

Lengthlength <= 50

abn?string

Australian Business Number.

Lengthlength <= 50

timezone?string

An IANA time zone name, for example Australia/Sydney.

Lengthlength <= 100

address_line1?string

Lengthlength <= 255

address_city?string

Lengthlength <= 100

address_state?string

Lengthlength <= 100

address_postal_code?string

Lengthlength <= 20

address_country?string

Lengthlength <= 100

invoice_prefix?string

Prefix for the account's invoice numbers.

Lengthlength <= 20

payment_slug?string

A suggestion for the account's payment page address. It is tidied into a URL-safe form and given a numeric suffix if already taken, so what you get back may differ from what you asked for. Falls back to the company name when omitted.

Lengthlength <= 60

webhook_url?string

Where the account's webhooks are delivered. Must be https, because event payloads carry customer details.

Formaturi

Lengthlength <= 2000

brand_color?string

A six digit hex colour, for example #46E9A3. Shorthand and named colours are rejected rather than guessed at.

Match^#[0-9A-Fa-f]{6}$

logo_url?string

A public https address for the account's logo. Chargetree downloads it and stores its own copy. PNG or JPEG only, under 1 MB. SVG is not accepted.

Formaturi

Lengthlength <= 2000

communications_enabled?boolean

Whether Chargetree chases this account's customers. Must be a real true or false, not a string.

company_name*string

Length1 <= length <= 255

email*string

The email of the person who will own the account. This becomes their login, and cannot be changed afterwards.

Formatemail

Lengthlength <= 255

external_id?string

Your own identifier for this customer. Supplying it makes the create call safe to retry.

Lengthlength <= 255

Response Body

`application/json`

curl -X POST "https://example.com/partner/accounts" \  -H "Content-Type: application/json" \  -d '{    "company_name": "Northside Electrical",    "email": "owner@northside.example"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "external_id": "string",  "status": "active",  "company_name": "string",  "first_name": "string",  "last_name": "string",  "email": "string",  "phone": "string",  "abn": "string",  "timezone": "string",  "address_line1": "string",  "address_city": "string",  "address_state": "string",  "address_postal_code": "string",  "address_country": "string",  "invoice_prefix": "string",  "payment_slug": "string",  "webhook_url": "string",  "logo_url": "string",  "brand_color": "string",  "communications_enabled": true,  "api_key_info": null,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "matched": true,  "secrets_note": "string"}

Retrieve an account

GET/partner/accounts/{id}

Returns one of your accounts in full, including the owner's email address.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Path Parameters

id*string

The account's Chargetree identifier.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/partner/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "external_id": "string",  "status": "active",  "company_name": "string",  "first_name": "string",  "last_name": "string",  "email": "string",  "phone": "string",  "abn": "string",  "timezone": "string",  "address_line1": "string",  "address_city": "string",  "address_state": "string",  "address_postal_code": "string",  "address_country": "string",  "invoice_prefix": "string",  "payment_slug": "string",  "webhook_url": "string",  "logo_url": "string",  "brand_color": "string",  "communications_enabled": true,  "api_key_info": null,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Update an account

PATCH/partner/accounts/{id}

Changes one of your accounts. Only the fields you send are changed, and you must send at least one, so a mistyped field name fails loudly rather than quietly doing nothing.

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

Changing webhook_url repoints the existing webhook endpoint and keeps its signing secret, so no new secret is returned.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Path Parameters

id*string

The account's Chargetree identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Send at least one field. email cannot be changed.

first_name?string

Lengthlength <= 100

last_name?string

Lengthlength <= 100

phone?string

Lengthlength <= 50

abn?string

Australian Business Number.

Lengthlength <= 50

timezone?string

An IANA time zone name, for example Australia/Sydney.

Lengthlength <= 100

address_line1?string

Lengthlength <= 255

address_city?string

Lengthlength <= 100

address_state?string

Lengthlength <= 100

address_postal_code?string

Lengthlength <= 20

address_country?string

Lengthlength <= 100

invoice_prefix?string

Prefix for the account's invoice numbers.

Lengthlength <= 20

payment_slug?string

Lengthlength <= 60

webhook_url?string

Where the account's webhooks are delivered. Must be https, because event payloads carry customer details.

Formaturi

Lengthlength <= 2000

brand_color?string

A six digit hex colour, for example #46E9A3. Shorthand and named colours are rejected rather than guessed at.

Match^#[0-9A-Fa-f]{6}$

logo_url?string

A public https address for the account's logo. Chargetree downloads it and stores its own copy. PNG or JPEG only, under 1 MB. SVG is not accepted.

Formaturi

Lengthlength <= 2000

communications_enabled?boolean

Whether Chargetree chases this account's customers. Must be a real true or false, not a string.

company_name?string

Length1 <= length <= 255

external_id?string

Lengthlength <= 255

status?string

Value in

"active"
"inactive"

Response Body

`application/json`

curl -X PATCH "https://example.com/partner/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "status": "inactive"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "external_id": "string",  "status": "active",  "company_name": "string",  "first_name": "string",  "last_name": "string",  "email": "string",  "phone": "string",  "abn": "string",  "timezone": "string",  "address_line1": "string",  "address_city": "string",  "address_state": "string",  "address_postal_code": "string",  "address_country": "string",  "invoice_prefix": "string",  "payment_slug": "string",  "webhook_url": "string",  "logo_url": "string",  "brand_color": "string",  "communications_enabled": true,  "api_key_info": null,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Deactivate an account

DELETE/partner/accounts/{id}

Switches the account off by setting its status to inactive. Nothing is erased, and the account can be switched back on with a PATCH.

Once inactive, that account's own API key stops working: its requests are refused with ACCOUNT_DISABLED.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Path Parameters

id*string

The account's Chargetree identifier.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/partner/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "external_id": "string",  "status": "active",  "company_name": "string",  "first_name": "string",  "last_name": "string",  "email": "string",  "phone": "string",  "abn": "string",  "timezone": "string",  "address_line1": "string",  "address_city": "string",  "address_state": "string",  "address_postal_code": "string",  "address_country": "string",  "invoice_prefix": "string",  "payment_slug": "string",  "webhook_url": "string",  "logo_url": "string",  "brand_color": "string",  "communications_enabled": true,  "api_key_info": null,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}

Rotate an account's API key

POST/partner/accounts/{id}/api-key

Issues a fresh API key for the account and immediately revokes every key it had before. There is no grace period, so anything still using the old key stops working the moment this returns. Plan rotations accordingly.

The new key is shown once, in this response.

Authorization

partnerKey

AuthorizationBearer <token>

A partner API key, in the form ct_partner_ followed by 32 characters, issued to you by Chargetree.

Send it as Authorization: Bearer ct_partner_.... An account key (ct_live_) will not work here, and a partner key will not work on the Public API.

In: header

Path Parameters

id*string

The account's Chargetree identifier.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/partner/accounts/497f6eca-6276-4993-bfeb-53cbbbba6f08/api-key"

{  "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",  "api_key": "ct_live_8x3kQp9zR2mN6vT4yL1bH7sW0jD5fA3c"}

200application/json

401application/json

403application/json

404application/json

429application/json

Retrying safely

Logos

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

429application/json

500application/json

200application/json

401application/json

403application/json

404application/json

429application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

200application/json

401application/json

403application/json

404application/json

429application/json

201application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`