ChargeOver REST API Documentation

API

The ChargeOver API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.

Getting Started

Finding your API Endpoint

The first step towards integration is finding your endpoint and credentials.

Log in to ChargeOver, and click the settings gear/cog in the top right
Choose "Developer" from the left-side navigation menu
Choose "REST API"
Enable the API, and copy your API credentials and API endpoint
Click the save button to save the configuration

Visit this URL to make your first API request:

https://CHANGE-THIS.chargeover.com/api/v3/customer

(substitute your own application/domain name into the above string!)

To retrieve a list of data from ChargeOver, use a HTTP GET request:

https://CHANGE-THIS.chargeover.com/api/v3/customer

To retrieve a subset of the items in a list (e.g. records 10 to 25) you can use the offset and limit parameters (just like in an SQL database):

https://CHANGE-THIS.chargeover.com/api/v3/customer?offset=10&limit=15

To retrieve a specific record from ChargeOver, use a HTTP GET request and specify the record id:

https://CHANGE-THIS.chargeover.com/api/v3/customer/1

Authentication

All API calls are made over a secure TLS/HTTPS connection.

Authentication is via industry-standard HTTP basic authentication for the REST API.

For more information on HTTP Basic Authentication, please visit the links below:

Libraries/Code

Make sure to visit the ChargeOver GitHub account. Feel free to contact us for additional sample code.

Filter / Sort / Pagination

Many fields can be used to query/filter the list of objects retrieved from ChargeOver using a ?where=... query string in your GET request.

Refer to the examples below.

Filtering (Query)

Refer to the examples to the right.

To filter the result set, the following comparison operators can be used:

EQUALS (equals)
GT (greater than)
LT (less than)
GTE (greater than or equal to)
LTE (less than or equal to)
CONTAINS (find strings containing this string)
NOTEQUALS (not equals)
IS:NULL (is null/unset)
ISNOT:NULL (is NOT null

Filtering (Query)

API Examples

// Get customers with an e-mail address of "johndoe@example.com"
/api/v3/customer?where=superuser_email:EQUALS:johndoe@example.com

// Get customers with the word "test" in their company name
/api/v3/customer?where=company:CONTAINS:test	

// Get a list of invoices on "2015-02-05" (Feb 5, 2015)
/api/v3/invoice?where=date:EQUALS:2015-02-05

// Get a list of invoices between the two dates "2015-02-01" (Feb 1, 2015) and "2015-02-05" (Feb 5, 2015)
/v3/invoice?where=date:GTE:2015-02-01,date:LTE:2015-02-05

Sorting

To sort/order the result set, you can specify an additional query string parameter:

?order=customer_id:DESC
(specify the the_field_name:ASC or the_field_name:DESC to sort ascending or descending)

Sorting

API Request

GET /api/v3/invoice?order=total:ASC

API Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "invoice_id": 1764,
            "total": 500,
            "customer_id": 6245
        },
        {
            "invoice_id": 1668,
            "total": 1000,
            "customer_id": 6212
        },
        {
            "invoice_id": 1681,
            "total": 2000,
            "customer_id": 6215
        }
    ]
}

Paging (Limit/Offset)

To page your result set, you can specify limit=... and offset=....

offset= determines how far into the records you are querying for to start returning data. For example, if you are querying for customers and you have ten customers ranging from customer_id=1 and customer_id=10 and offset=0, then the returned set of customers will start with the customer whose customer_id = 1. However, if the offset=3 then the list of customers that is returned will start with the customer who has a customer_id = 4.

limit= determines the number of records returned. For example if limit=5 when querying for customers, you would get back the data for no more than five customers.

If your query contains ?offset=10&limit=15, then this is essentially saying, "starting at record 10, fetch the next 15 records."

NOTE: If not specified otherwise, your result set will page by default at 10 records. The maximum number of records you can return per page is 100. You will not be able to retrieve more than 100 records at one time.

.

Paging (Limit/Offset)

API Request

GET /api/v3/user?offset=8&limit=2

API Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "user_id": 356,
            "external_key": null,
            "first_name": "John",
            "middle_name_glob": null,
            "last_name": "Doe",
           ...other user data...
        },
        {
            "user_id": 357,
            "external_key": null,
            "first_name": "Jane",
            "middle_name_glob": null,
            "last_name": "Doe",
            ...other user data...
        }
    ]
}

Counting Objects

You can get a count of the number of objects by using the /_count endpoints.

Counting Objects

Refer to the examples on the right.

To get a count of the number of objects within ChargeOver, append /_count to the endpoint.

You can also count the number of objects matching a filter/query by using your ?where=... query on the /_count endpoint.

Counting Objects

API Examples

// Get the total number of customers
GET /api/v3/customer/_count

// Get the number of customers who have a company name containing "Test"
GET /api/v3/customer/_count?where=company:CONTAINS:test

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": 25
}

External Keys

ChargeOver has an external keys concept for all objects, to make it easier for you to integrate external systems with ChargeOver.

All objects (customers, users, invoices, billing packages, etc.) can be assigned a user-definable, unique external key value. This could be an internal identifier you use to identify a customer, the ID value from some other application, a reference to a primary key within one of your other systems, etc. When making API requests, you can always use the external key value instead of the ChargeOver id value.

External key policies:

Default behavior - external key values can NOT be re-used, even if the original object is deleted or cancelled
Optional - external key values can be cleared (and thus re-used) once a subscription is cancelled
Optional - external key values can be cleared (and thus re-used) if an object is deleted
Optional - external key values can be mangled (a random string will be added to the end of them) if a subscription is cancelled
Optional - external key values can be mangled (a random string added to the end of them) if an object is deleted

Contact us to enable any optional external key policies for your account.

External Key Examples

Adding external_key values to ChargeOver enables several "short-cuts" when working with the ChargeOver REST API.

You can get objects from ChargeOver by external_key instead of using the customer_id, item_id, etc.
When adding or updating objects, you can reference other objects by *_external_key instead of their *_id values

Refer to the examples to the right.

External Key Examples

API Examples

// Get a customer with external_key = abc123
GET /api/v3/customer/external_key:abc123


// Add an invoice for the customer with external_key = abc123
POST /api/v3/invoice 

{
	"customer_external_key": "abc123", 
	... other invoice data here ...
}

Object Tokens

ChargeOver assigns a unique random identifier to every object.

When making API requests, you can always use the object token value instead of the ChargeOver id value.

Object Token Examples

You can reference objects within ChargeOver by their token value instead of the *_id value.

You can get objects from ChargeOver by token instead of using the customer_id, item_id, etc.
When adding or updating objects, you can reference other objects by *_token instead of their *_id values

Refer to the examples to the right.

Object Token Examples

API Examples

// Get a customer with token = 0q7fx5652k18
GET /api/v3/customer/token:0q7fx5652k18


// Add an invoice for the customer with token = 0q7fx5652k18
POST /api/v3/invoice 

{
	"customer_token": "0q7fx5652k18", 
	... other invoice data here ...
}

Escape Syntax For Reserved Characters

Escape Syntax Example

If you are querying for an object that contains a reserved character such as a colon, you will need to escape the character using a slash.

Characters that need to be escaped:

: (colon)
, (comma)

For example, if you had an item with an external_key called Example:ID, then instead of using:

GET /api/v3/item?where=external_key:EQUALS:Example:ID

You would need to use:

GET /api/v3/item?where=external_key:EQUALS:Example\:ID

Escape Syntax Example

API Request

GET /api/v3/item?where=external_key:EQUALS:Example\:ID

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "item_id": 3,
            "item_type": "service",
            "tierset_id": 80,
            "name": "Test Product",
            "description": "",
            "units": "",
            "enabled": true,
            "accounting_sku": null,
            "external_key": "Example:ID",
            "token": "hm261y3xnzd6",
            "custom_1": "",
            "custom_2": null,
            "custom_3": null,
            "write_datetime": "2017-02-28 21:02:33",
            "mod_datetime": "2017-12-28 10:25:39",
            "units_plural": "",
            "expire_recurs": "6",
            "trial_recurs": "1",
            "tiersets": [
                {
                    "tierset_id": 78,
                    "currency_id": 1,
                    "setup": 0,
                    "base": 25.95,
                    "percent": 0,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2017-12-28 10:25:39",
                    "mod_datetime": "2017-12-28 10:25:39",
                    "currency_symbol": "$",
                    "currency_iso4217": "USD",
                    "setup_formatted": "$ 0.00",
                    "base_formatted": "$ 25.95",
                    "percent_formatted": "0 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                },
                {
                    "tierset_id": 79,
                    "currency_id": 2,
                    "setup": 0,
                    "base": 25.95,
                    "percent": 0,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2017-12-28 10:25:39",
                    "mod_datetime": "2017-12-28 10:25:39",
                    "currency_symbol": "CAD$",
                    "currency_iso4217": "CAD",
                    "setup_formatted": "CAD$ 0.00",
                    "base_formatted": "CAD$ 25.95",
                    "percent_formatted": "0 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                },
                {
                    "tierset_id": 80,
                    "currency_id": 6,
                    "setup": 0,
                    "base": 25.95,
                    "percent": 0,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2017-12-28 10:25:39",
                    "mod_datetime": "2017-12-28 10:25:39",
                    "currency_symbol": "A$",
                    "currency_iso4217": "AUD",
                    "setup_formatted": "A$ 0.00",
                    "base_formatted": "A$ 25.95",
                    "percent_formatted": "0 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                }
            ]
        }
    ]
}

On Behalf Of...

Pass your end-customer's IP address to ChargeOver for fraud control.

On Behalf Of...

If you are making REST API calls directly as a direct result of an end-customer interaction, (e.g. the customer is clicking a PAY NOW button in your application, or something similar) we encourage you to pass the end-customer's IP address and any identifying information (e.g. a username, email address, user ID, etc.) in your API calls.

Do not pass this information if you are initiating the action, and not the customer. (e.g. if you are triggering an automated payment without the customer's direct interaction, do not pass these parameters!)

This information can be used for by ChargeOver's fraud detection services, and also relayed to payment gateways and merchant accounts for use by their fraud detection routines.

Pass this information in these two fields, as query string parameters to your REST API request:

on_behalf_addr=(the end-customers IP address here)
on_behalf_details=(the end-customers username, email address, or user ID in your app here)

On Behalf Of...

API Request

POST /api/v3/transaction?action=pay&on_behalf_addr=173.132.15.83&on_behalf_details=johndoe@example.com

Versioning

Whenever we make backwards-incompatible changes to the ChargeOver API, we release a new sequenced version of the API. We always strive to maintain backwards compatibility with the older APIs, and older API versions are rarely (if ever) completely removed from service.

The current release is v3.

Bulk/Batch Requests

Batch requests allow developers to avoid multiple HTTP round-trips when performing multiple API actions or bulk uploading data to ChargeOver.

The basic format of an API batch request is a list of JSON-encoded request objects to process. Each request object must have the following attributes:

Attribute	Description
request_method	This HTTP request method for this request `GET` to retrieve/query for objects `POST` to create new objects `PUT` to update existing objects
uri	A relative URI for the API resource. For example, to get a specific customer, the URI would be `/api/v3/customer/2` (where `2` is the customer_id). To create a customer, the URI would be `/api/v3/customer`.
payload	If your request requires a payload, put the JSON-encoded payload here. For example, to create a customer, you'd pass in your JSON-encoded customer object.

The API response will contain a corresponding list of response objects - one response object for each request you sent. Each response object will have the following attributes:

Attribute	Description
code	A HTTP status code for the request. `200` for an OK response to gets, queries, etc. `201` for an OK response to something newly created `400` for bad requests See the HTTP Status Codes section for complete details
status	Either `OK` for success, or `Error` if an error occurred.
message	If an error occurred, the error message will appear here.
response	If your request warrented a response (e.g. a returned object) the JSON-encoded response will be here.

There is a maximum of 25 requests within a single batch/bulk request.

Batch Request

POST your batch requests to the /api/v3/_bulk endpoint.

Batch Request

API Request

POST /api/v3/_bulk

[
    {
        "request_method": "GET",
        "uri": "\/api\/v3\/customer\/2",
        "payload": null
    },
    {
        "request_method": "POST",
        "uri": "\/api\/v3\/customer",
        "payload": {
            "company": "My new bulk customer 928"
        }
    },
    {
        "request_method": "POST",
        "uri": "\/api\/v3\/customer",
        "payload": {
            "company": "Test Company 464",
            "external_key": "abcd1234"
        }
    }
]

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "_bulk": [
            {
                "code": 200,
                "status": "OK",
                "message": "",
                "response": {
                    "customer_id": 2,
                    "superuser_id": 349,
                    "external_key": null,
                    "token": "e6218b7c7b91a0121875a27a3a0ef9c5",
                    "company": "Test Customer 2",
                    ... (truncated for brevity) ... 
                }
            },
            {
                "code": 201,
                "status": "OK",
                "message": "",
                "response": {
                    "id": 14
                }
            },
            {
                "code": 400,
                "status": "Error",
                "message": "A customer already exists with the external_key value \"abcd1234\"",
                "response": false
            }
        ]
    }
}

JSONPath in Batches

ChargeOver supports using JSONPath for referencing one payload from within another payload, inside of a single batch/bulk request.

The classic use-case for JSONPath support in the bulk/batch API is trying to create a customer and an invoice for that customer in a single bulk/batch request. Without JSONPath references, this would not be possible to do in single bulk/batch request because you would need to know the id value returned from executing the first payload (adding the customer) so that you could use this id value in the second payload (adding the invoice).

JSONPath referencing support makes this possible by letting payloads refer to response values from other payloads.

In the example to the right, you can see that our second request (adding the invoice) uses a special key instead of the normal customer_id key. The invoice add payload refers to customer_jsonpath and the value is an identifier (the_customer), followed by a JSONPath expression ($.response.id).

The identifier serves to identify which previous batch/bulk object to refer to. The JSONPath expression tells us which value to fetch from that bulk/batch object response. In this case, customer_jsonpath will be replaced by the returned id value from the preceeding call to create the customer.

In other words, "customer_jsonpath": "the_customer:$.response.id" essentially means "replace this with the customer_id value returned from the payload named the_customer".

JSONPath in Batches

API Request

POST /api/v3/_bulk

[
    {
        "request_method": "POST",
        "uri": "\/api\/v3\/customer",
        "payload": {
            "company": "My test JSONPath customer"
        },
        "id": "the_customer"
    },
    {
        "request_method": "POST",
        "uri": "\/api\/v3\/invoice",
        "payload": {
            "customer_jsonpath": "the_customer:$.response.id",
            "line_items": [
                {
                    "item_id": 1,
                    "line_rate": 2.95,
                    "line_quantity": 2
                }
            ]
        },
        "id": null
    }
]

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "_bulk": [
            {
                "code": 201,
                "status": "OK",
                "message": "",
                "response": {
                    "id": 6
                }
            },
            {
                "code": 201,
                "status": "OK",
                "message": "",
                "response": {
                    "id": 10005
                }
            }
        ]
    }
}

Reporting/Aggregation

It is possible to pull reporting and aggregation data via the ChargeOver REST API.

Get a List of Reports

Allows you to get a list of all reports with each report's name and report_id number.

Get a List of Reports

API Request

GET /api/v3/_report
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
  "code": 200, 
  "status": "OK",
  "message": "",
  "details": {},
  "response": [
    {
      "name": "Open Customer Balances",
      "report_id": 3
    },
    {
      "name": "All Customer Balances",
      "report_id": 4
    },
    {
      "name": "Credits",
      "report_id": 6
    },
    {
     "name": "Failed Payments",
      "report_id": 7
    }
}

Get a Specific Report

You can also get the data from a specific report via the API by using the report's report_id.

Ordering and limiting report data:

It is possible to order or to limit the results you get back from the report if desired. For example, if you wanted to view the "All Customers" report with the list of customers in ascending order based off of customer_id, you could use:

/api/v3/_report/37?action=reportData&order=tenant_tenant_id:ASC

There are two parameters used for limiting the data that is returned: offset and limit.

offset determines how far into the report the data is returned from. For example, if you are calling for the "All Customers" report and have ten customers ranging from customer_id=1 and customer_id=10 and offset=0 then the returned report will start with the customer whose customer_id = 1. However, if the offset=3 then the report data that is returned will start with the customer who has a customer_id = 4.

Note: If you request an offset you MUST also specify an order with ASC for ascending or DESC for descending.

limit determines the number of objects returned from the report. For example if limit=5 for the "All Customers" report, you would get back the data for no more than five customers in the report. The maximum page size for report data is 1000.

One last example:

/api/v3/_report/37?action=reportData&offset=10&limit=50

If you used the above API call you would get back no more than 50 objects from the report, starting with the 10th object in the report.

Get a Specific Report

API Request

POST /api/v3/_report/58?action=reportData
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json

[
    "transaction_transaction_date:GTE:2017-09-11",
    "transaction_transaction_date:LTE:2017-10-11"
]

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "_report": [
            {
                "transaction_transaction_date": "Sep 14, 2017",
                "transaction_transaction_method": "ACH\/eCheck",
                "transaction_transaction_detail": "x6667",
                "transaction_amount": "$ 50.00",
                "transaction_gateway_transid": "*DEBIT: Test ACH\/eCheck* [1505398606]",
                "transaction_transaction_type": "Payment",
                "transaction_transaction_date_unformatted": "2017-09-14",
                "transaction_amount_unformatted": 50
            },
            {
                "transaction_transaction_date": "Sep 28, 2017",
                "transaction_transaction_method": "Visa",
                "transaction_transaction_detail": "x4444",
                "transaction_amount": "$ 100.00",
                "transaction_gateway_transid": "*CHARGE: Test Credit Card* [1506605204]",
                "transaction_transaction_type": "Payment",
                "transaction_transaction_date_unformatted": "2017-09-28",
                "transaction_amount_unformatted": 100
            },
            {
                "transaction_transaction_date": "Sep 28, 2017",
                "transaction_transaction_method": "Paid by Check",
                "transaction_transaction_detail": 56,
                "transaction_amount": "$ 550.00",
                "transaction_gateway_transid": 56,
                "transaction_transaction_type": "Payment",
                "transaction_transaction_date_unformatted": "2017-09-28",
                "transaction_amount_unformatted": 550
            },
            {
                "transaction_transaction_date": "Oct 11, 2017",
                "transaction_transaction_method": "Visa",
                "transaction_transaction_detail": "x1111",
                "transaction_amount": "$ 100.00",
                "transaction_gateway_transid": "*CHARGE: Test Credit Card* [1507740165]",
                "transaction_transaction_type": "Payment",
                "transaction_transaction_date_unformatted": "2017-10-11",
                "transaction_amount_unformatted": 100
            }
        ],
        "_count": 4
    }
}

Rate Limits

By default, ChargeOver limits REST API requests to a maximum of 250 requests per minute.

If you exceed this limit, you will receive an API response like this:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
    "code": 429,
    "status": "Error",
    "message": "Rate limit exceeded",
    "response": false
}

If you think you will routinely exceed or come close to the rate limits, please contact us to discuss your use-case.

You may be able to reduce the number of REST API requests you make using our bulk/batch request endpoint.

HTTP Status Codes

The API follows these rules for HTTP requests:

If you are creating new objects, use a POST.
If you are updating an existing object, use a PUT.
If you are trying to get a particular object by id, use a GET.
If you are trying to get a list of objects, or query for a list of objects, use a GET.
If you are calling an action (e.g. pay an invoice, reset a password, etc.), use a POST.

The API follows these rules for HTTP response codes:

If you successfully create an object, you'll get back a 201 Created HTTP response. You'll also get back a Location: header with the URL of the new object.
If you successfully update an object, you'll get back a 202 Accepted HTTP response. You'll also get back a Location: header with the URL of the new object.
If you successfully get a specific object, you'll get back a 200 OK HTTP response.
If you try to get a specific object that doesn't exist, you'll get back a 404 Not Found HTTP response.
If you query for objects, you'll get back a 200 OK HTTP response.
If you successfully call an action, you'll get back a 200 OK HTTP response.
If you do something wrong (e.g. send an invalid JSON request, hit an invalid endpoint, etc.) you will get back a 400 Bad Request HTTP response.
If your authentication parameters are incorrect, you will get back a 401 Unauthorized HTTP response.
If you exceed the REST API rate limits, you will get back a 429 Too Many Requests HTTP response.
If something goes wrong with ChargeOver itself, you will get back a 500 Internal Server Error HTTP response.

Objects

The ChargeOver object model is documented below.

Customers

The primary key field for customers is customer_id.

Create a customer

Note that the response/id value will be the customer_id value for the newly created customer.

Object Attributes

Attribute	Type	Description
parent_customer_id	integer	Parent customer ID #	📎
external_key	string	External key value	📎
company	string	Company/customer name	📎
language_id	integer	Language ID #	📎
currency_id	integer	Currency ID #	📎
class_id	integer	Default class tracking ID #	📎
admin_id	integer	Admin/Worker ID #	📎
campaign_id	integer	Campaign/lead source ID #	📎
campaign_details	string	Campaign/lead source details	📎
no_taxes	boolean	Flag to disable charging of taxes	📎
no_dunning	boolean	Flag to disable dunning	📎
superuser_username	string	Main contact username	📎
superuser_email	string	Main contact e-mail address	📎
superuser_name	string	Main contact name	📎
superuser_first_name	string	Main contact first name	📎
superuser_last_name	string	Main contact last name	📎
superuser_phone	string	Main contact phone number	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state/province	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
brand_id	integer	Brand ID #	📎
terms_id	integer	Default terms ID #	📎
invoice_delivery	enum	Delivery method for initial invoices ("email" or "print" for printed hard-copy)	📎
dunning_delivery	enum	Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.)	📎
tax_ident	string	Tax ID #/VAT #	📎
tags	array	A list of tags	📎

Create a customer

API Request

POST /api/v3/customer HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Content-Type: application/json

{
    "company": "Test Company Name",
    "bill_addr1": "16 Dog Lane",
    "bill_addr2": "Suite D",
    "bill_city": "Storrs",
    "bill_state": "CT",
    "superuser_name": "Karli Marie",
    "superuser_phone": "860-647-8567",
    "superuser_email": "karli@example.com",
    "tags": [
        "tag1",
        "tag2"
    ]
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/customer/1541
Content-Type: application/json

{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 1541
    }
}

Update a customer

Setting the parent_customer_id to null will effectively disconnect the child customer from its parent.

Note that a customer's parent_customer_id can only be updated if its parent has not made a payment for the customer.

Object Attributes

Attribute	Type	Description
superuser_id	integer	Main contact ID #	📎
external_key	string	External key value	📎
company	string	Company/customer name	📎
language_id	integer	Language ID #	📎
class_id	integer	Default class tracking ID #	📎
admin_id	integer	Admin/Worker ID #	📎
campaign_id	integer	Campaign/lead source ID #	📎
no_taxes	boolean	Flag to disable charging of taxes	📎
no_dunning	boolean	Flag to disable dunning	📎
superuser_email	string	Main contact e-mail address	📎
superuser_name	string	Main contact name	📎
superuser_first_name	string	Main contact first name	📎
superuser_last_name	string	Main contact last name	📎
superuser_phone	string	Main contact phone number	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state/province	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
terms_id	integer	Default terms ID #	📎
invoice_delivery	enum	Delivery method for initial invoices ("email" or "print" for printed hard-copy)	📎
dunning_delivery	enum	Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.)	📎
tax_ident	string	Tax ID #/VAT #	📎
tags	array	A list of tags	📎

Update a customer

API Request

PUT /api/v3/customer/3

{
    "company": "Test API Company, LLC",
    "bill_addr1": "220 ChargeOver Street",
    "bill_addr2": "Suite 10",
    "bill_city": "Minneapolis",
    "bill_state": "MN",
    "bill_postcode": "55416",
    "bill_country": "USA",
    "external_key": "abcd3325",
    "superuser_name": "David Palmer",
    "superuser_email": "david@palmer.com",
    "superuser_phone": "860-634-1111"
}

API Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "code": 202,
    "status": "OK",
    "message": "",
    "response": {
        "id": 3
    }
}

Get a list of customers

Notes:

The superuser_id field is the primary contact (user) for this customer

Object Attributes

Attribute	Type	Description
customer_id	integer	Customer ID #	📎
parent_customer_id	integer	Parent customer ID #	📎
token	string	Customer Token	📎
superuser_id	integer	Main contact ID #	📎
external_key	string	External key value	📎
display_as	string	Deprecated	📎
company	string	Company/customer name	📎
language_id	integer	Language ID #	📎
currency_id	integer	Currency ID #	📎
currency_iso4217	string	ISO 4217 currency code representation	📎
currency_symbol	string	Symbol for currency ($, £, etc.)	📎
class_id	integer	Default class tracking ID #	📎
admin_id	integer	Admin/Worker ID #	📎
campaign_id	integer	Campaign/lead source ID #	📎
no_taxes	boolean	Flag to disable charging of taxes	📎
no_dunning	boolean	Flag to disable dunning	📎
superuser_username	string	Main contact username	📎
superuser_email	string	Main contact e-mail address	📎
superuser_name	string	Main contact name	📎
superuser_first_name	string	Main contact first name	📎
superuser_last_name	string	Main contact last name	📎
superuser_phone	string	Main contact phone number	📎
superuser_token	string	Main contact token	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state/province	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
bill_block	string	Printable billing address	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
ship_block	string	Printable shipping address	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
total	float	The sum total amount of all invoices ever issued to this customer	📎
balance	float	Balance due for this customer	📎
paid	float	The sum total amount of all payments ever made by this customer	📎
write_datetime	string	Date/time this customer was created	📎
write_ipaddr	string	IP address that created this customer	📎
mod_datetime	string	Date/time this customer was updated	📎
mod_ipaddr	string	IP address that last updated this customer	📎
brand_id	integer	Brand ID #	📎
class_name	string	Class name	📎
terms_id	integer	Default terms ID #	📎
terms_name	string	Default payment terms	📎
terms_days	integer	# of days for the default payment terms	📎
url_statementlink	string	URL the customer can visit to view thier monthly statement	📎
url_paymethodlink	string	URL the customer can visit to update their payment method	📎
url_self	string	URL for viewing the customer in the GUI	📎
admin_name	string	Admin/Worker Name	📎
admin_email	string	Admin/Worker Email	📎
customer_status_id	string	Customer Status ID #	📎
customer_status_name	string	Human-friendly customer status	📎
customer_status_str	string	Status string	📎
customer_status_state	string	Status code	📎
default_paymethod	string	Default payment method type	📎
default_creditcard_id	integer	Default credit card ID # (if the default payment method is a credit card)	📎
default_ach_id	integer	Default ACH/eCheck ID # (if the default payment method is ACH)	📎
invoice_delivery	enum	Delivery method for initial invoices ("email" or "print" for printed hard-copy)	📎
dunning_delivery	enum	Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.)	📎
tax_ident	string	Tax ID #/VAT #	📎
mrr	float	Monthly recurring revenue $	📎
arr	float	Annual recurring revenue $	📎

Get a list of customers

API Request

GET /api/v3/customer

API Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "superuser_id": "348",
            "external_key": "test-key",
            "company": "Update This Record 755",
            "email": "keith@testjson.com",
            "phone": "",
            "bill_addr1": "16 Dog Lane",
            "bill_addr2": "Suite D",
            "bill_addr3": null,
            "bill_city": "Storrs",
            "bill_state": "CT",
            "bill_postcode": "",
            "bill_country": null,
            "bill_email": null,
            "bill_notes": null,
            "ship_addr1": null,
            "ship_addr2": null,
            "ship_addr3": null,
            "ship_city": null,
            "ship_state": null,
            "ship_postcode": null,
            "ship_country": null,
            "ship_email": null,
            "ship_notes": null,
            "write_datetime": "2012-08-16 16:18:47",
            "write_ipaddr": "172.16.16.104",
            "mod_datetime": "2013-03-21 20:32:57",
            "mod_ipaddr": "172.16.16.11",
            "customer_id": "1"
        }
    ]
}

Query for customers

Available query parameters:

customer_id
parent_customer_id
bill_state
ship_state
bill_country
ship_country
external_key
token
company
superuser_id
superuser_email
custom_1
custom_2
custom_3
custom_4
custom_5

Valid values for customer_status_state:

a (for active customers)
i (for customers who have manually been marked "inactive" or who have had no recent activity)

Valid values for customer_status_str:

active-current
active-overdue
inactive-manual
inactive-activity

Object Attributes

Attribute	Type	Description
customer_id	integer	Customer ID #	📎
parent_customer_id	integer	Parent customer ID #	📎
token	string	Customer Token	📎
superuser_id	integer	Main contact ID #	📎
external_key	string	External key value	📎
display_as	string	Deprecated	📎
company	string	Company/customer name	📎
language_id	integer	Language ID #	📎
currency_id	integer	Currency ID #	📎
currency_iso4217	string	ISO 4217 currency code representation	📎
currency_symbol	string	Symbol for currency ($, £, etc.)	📎
class_id	integer	Default class tracking ID #	📎
admin_id	integer	Admin/Worker ID #	📎
campaign_id	integer	Campaign/lead source ID #	📎
no_taxes	boolean	Flag to disable charging of taxes	📎
no_dunning	boolean	Flag to disable dunning	📎
superuser_username	string	Main contact username	📎
superuser_email	string	Main contact e-mail address	📎
superuser_name	string	Main contact name	📎
superuser_first_name	string	Main contact first name	📎
superuser_last_name	string	Main contact last name	📎
superuser_phone	string	Main contact phone number	📎
superuser_token	string	Main contact token	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state/province	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
bill_block	string	Printable billing address	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
ship_block	string	Printable shipping address	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
total	float	The sum total amount of all invoices ever issued to this customer	📎
balance	float	Balance due for this customer	📎
paid	float	The sum total amount of all payments ever made by this customer	📎
write_datetime	string	Date/time this customer was created	📎
write_ipaddr	string	IP address that created this customer	📎
mod_datetime	string	Date/time this customer was updated	📎
mod_ipaddr	string	IP address that last updated this customer	📎
brand_id	integer	Brand ID #	📎
class_name	string	Class name	📎
terms_id	integer	Default terms ID #	📎
terms_name	string	Default payment terms	📎
terms_days	integer	# of days for the default payment terms	📎
url_statementlink	string	URL the customer can visit to view thier monthly statement	📎
url_paymethodlink	string	URL the customer can visit to update their payment method	📎
url_self	string	URL for viewing the customer in the GUI	📎
admin_name	string	Admin/Worker Name	📎
admin_email	string	Admin/Worker Email	📎
customer_status_id	string	Customer Status ID #	📎
customer_status_name	string	Human-friendly customer status	📎
customer_status_str	string	Status string	📎
customer_status_state	string	Status code	📎
default_paymethod	string	Default payment method type	📎
default_creditcard_id	integer	Default credit card ID # (if the default payment method is a credit card)	📎
default_ach_id	integer	Default ACH/eCheck ID # (if the default payment method is ACH)	📎
invoice_delivery	enum	Delivery method for initial invoices ("email" or "print" for printed hard-copy)	📎
dunning_delivery	enum	Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.)	📎
tax_ident	string	Tax ID #/VAT #	📎
mrr	float	Monthly recurring revenue $	📎
arr	float	Annual recurring revenue $	📎

Query for customers

API Request

GET /api/v3/customer?where=bill_country:EQUALS:Canada

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "superuser_id": 357,
            "external_key": null,
            "company": "CA Test Customer 1",
            "email": "asgdadg@asdgaggd.com",
            "phone": "",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "bill_postcode": null,
            "bill_country": "Canada",
            "bill_email": null,
            "bill_notes": null,
            "ship_addr1": null,
            "ship_addr2": null,
            "ship_addr3": null,
            "ship_city": null,
            "ship_state": null,
            "ship_postcode": null,
            "ship_country": null,
            "ship_email": null,
            "ship_notes": null,
            "write_datetime": "2013-08-22 08:57:09",
            "write_ipaddr": "172.16.16.102",
            "mod_datetime": "2013-08-22 08:57:09",
            "mod_ipaddr": "172.16.16.102",
            "display_as": "CA Test Customer 1",
            "ship_block": "",
            "bill_block": "Canada",
            "customer_id": 7
        }
    ]
}

Get a specific customer

Get a specific customer using their customer_id.

Object Attributes

Attribute	Type	Description
customer_id	integer	Customer ID #	📎
parent_customer_id	integer	Parent customer ID #	📎
token	string	Customer Token	📎
superuser_id	integer	Main contact ID #	📎
external_key	string	External key value	📎
display_as	string	Deprecated	📎
company	string	Company/customer name	📎
language_id	integer	Language ID #	📎
currency_id	integer	Currency ID #	📎
currency_iso4217	string	ISO 4217 currency code representation	📎
currency_symbol	string	Symbol for currency ($, £, etc.)	📎
class_id	integer	Default class tracking ID #	📎
admin_id	integer	Admin/Worker ID #	📎
campaign_id	integer	Campaign/lead source ID #	📎
no_taxes	boolean	Flag to disable charging of taxes	📎
no_dunning	boolean	Flag to disable dunning	📎
superuser_username	string	Main contact username	📎
superuser_email	string	Main contact e-mail address	📎
superuser_name	string	Main contact name	📎
superuser_first_name	string	Main contact first name	📎
superuser_last_name	string	Main contact last name	📎
superuser_phone	string	Main contact phone number	📎
superuser_token	string	Main contact token	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state/province	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
bill_block	string	Printable billing address	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
ship_block	string	Printable shipping address	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
total	float	The sum total amount of all invoices ever issued to this customer	📎
balance	float	Balance due for this customer	📎
paid	float	The sum total amount of all payments ever made by this customer	📎
write_datetime	string	Date/time this customer was created	📎
write_ipaddr	string	IP address that created this customer	📎
mod_datetime	string	Date/time this customer was updated	📎
mod_ipaddr	string	IP address that last updated this customer	📎
brand_id	integer	Brand ID #	📎
class_name	string	Class name	📎
terms_id	integer	Default terms ID #	📎
terms_name	string	Default payment terms	📎
terms_days	integer	# of days for the default payment terms	📎
url_statementlink	string	URL the customer can visit to view thier monthly statement	📎
url_paymethodlink	string	URL the customer can visit to update their payment method	📎
url_self	string	URL for viewing the customer in the GUI	📎
admin_name	string	Admin/Worker Name	📎
admin_email	string	Admin/Worker Email	📎
customer_status_id	string	Customer Status ID #	📎
customer_status_name	string	Human-friendly customer status	📎
customer_status_str	string	Status string	📎
customer_status_state	string	Status code	📎
default_paymethod	string	Default payment method type	📎
default_creditcard_id	integer	Default credit card ID # (if the default payment method is a credit card)	📎
default_ach_id	integer	Default ACH/eCheck ID # (if the default payment method is ACH)	📎
invoice_delivery	enum	Delivery method for initial invoices ("email" or "print" for printed hard-copy)	📎
dunning_delivery	enum	Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.)	📎
tax_ident	string	Tax ID #/VAT #	📎
mrr	float	Monthly recurring revenue $	📎
arr	float	Annual recurring revenue $	📎
tags	array	A list of tags	📎

Get a specific customer

API Request

GET /api/v3/customer/16

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "superuser_id": 364,
        "external_key": null,
        "token": "fozdqj169569",
        "company": "Karli Marie",
        "bill_addr1": "56 Wintergreen Street",
        "bill_addr2": "",
        "bill_addr3": "",
        "bill_city": "Hamden",
        "bill_state": "CT",
        "bill_postcode": "06517",
        "bill_country": "United States",
        "bill_notes": null,
        "ship_addr1": null,
        "ship_addr2": null,
        "ship_addr3": null,
        "ship_city": null,
        "ship_state": null,
        "ship_postcode": null,
        "ship_country": null,
        "ship_notes": null,
        "terms_id": 3,
        "class_id": 0,
        "custom_1": "",
        "custom_2": null,
        "custom_3": null,
        "custom_4": null,
        "custom_5": null,
        "custom_6": null,
        "admin_id": 4,
        "campaign_id": 0,
        "currency_id": 1,
        "language_id": 1,
        "brand_id": 1,
        "default_paymethod": "crd",
        "default_creditcard_id": 51,
        "default_ach_id": null,
        "no_taxes": false,
        "no_dunning": false,
        "write_datetime": "2017-05-18 09:36:19",
        "write_ipaddr": "130.215.123.7",
        "mod_datetime": "2017-12-01 21:37:50",
        "mod_ipaddr": "192.168.21.14",
        "terms_name": "Due on Receipt",
        "terms_days": 0,
        "class_name": "",
        "paid": 1145.46,
        "total": 2656.11,
        "balance": 1510.65,
        "url_paymethodlink": "https:\/\/dev.chargeover.com\/r\/paymethod\/i\/fozdqj169569",
        "url_self": "https:\/\/dev.chargeover.com\/admin\/r\/customer\/view\/16",
        "admin_name": "ChargeOver Support",
        "admin_email": "support@chargeover.com",
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "display_as": "Karli Marie",
        "ship_block": "",
        "bill_block": "56 Wintergreen Street\nHamden CT 06517\nUnited States",
        "superuser_name": "Karli Marie",
        "superuser_first_name": "Karli",
        "superuser_last_name": "Marie",
        "superuser_phone": "860-249-1317",
        "superuser_email": "karli@chargeover.com",
        "superuser_token": "1892mske1j64",
        "customer_id": 16,
        "parent_customer_id": null,
        "invoice_delivery": "email",
        "dunning_delivery": "email",
        "customer_status_id": 2,
        "customer_status_name": "Over Due",
        "customer_status_str": "active-overdue",
        "customer_status_state": "a",
        "superuser_username": "QATPM1zD4CLE",
        "tags": [
            "tag1",
            "tag2"
        ]
    }
}

Delete a customer

Allows you to delete a customer.

Note that you can only delete a customer if:

They have no active subscriptions
They have no open/unpaid invoices

Delete a customer

API Request

DELETE /api/v3/customer/1553 HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSj...

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Set a customer as inactive

Allows you to set a customer as "Inactive".

Set a customer as inactive

API Request

POST /api/v3/customer/2?action=setInactive
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V...
Content-Type: application/json

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Set a customer as active

Allows you to set a specified customer as "Active".

Set a customer as active

API Request

POST /api/v3/customer/2?action=setActive
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V...
Content-Type: application/json

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Set the primary contact for a customer

Specify the user you want to assign as the customer's primary contact using the user's user_id.

Set the primary contact for a customer

API Request

POST /api/v3/customer/321?action=setSuperUser

{
    "user_id": 789
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Set the default payment method for a customer

Allows you to set the defaut payment method for a customer.

The update_subscriptions_and_scheduled_invoices field is optional. If you leave it off entirely OR set it to true, we will update any already existing subscriptions for that customer to use this payment method too. If you set it to false, we'll update the customer but NOT their already existing subscriptions.

Set the default payment method for a customer

API Request

POST /api/v3/customer/2?action=setPayMethod

{
    "creditcard_id": 74,
    "paymethod": "crd",
    "update_subscriptions_and_scheduled_invoices": true
}

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Email a customer

Allows you to send an email from a template to a customer.

The message_id field is optional. If left out, the default email will be a welcome message.

Email a customer

API Request

POST /api/v3/customer/9?action=email

{
    "_comment": "If you wish to use an existing template other than the default, specify the message_id of the template:",
    "message_id": 16
}

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"details": {},
	"response": true
}

Disconnect a customer from its parent customer

Allows you to disconnect a child customer from its parent customer via POST API Request.

A customer's parent can only be disconnected if its parent has not made a payment for the customer.

Note you can also disconnect a parent by updating the customer and setting its parent_customer_id to null

Disconnect a customer from its parent customer

API Request

POST /api/v3/customer/2?action=disconnectParent

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Users / Contacts

The primary key field for a user is user_id

Add a contact

Notes:

The response/id value will be the user_id value for the newly created user.

Object Attributes

Attribute	Type	Description
external_key	string	External key value	📎
username	string	Customer portal username	📎
password	string	Customer portal password	📎
name	string	First and last name of the contact	📎
first_name	string	First name of contact	📎
middle_name_glob	string	Middle name/initial	📎
last_name	string	Last name	📎
name_suffix	string	Suffix (e.g. "Jr.", "Sr.", "III", etc.)	📎
title	string	Title	📎
email	string	E-mail address	📎
phone	string	Phone number	📎
mobile	string	Mobile number	📎
user_type_id	integer	User type ID #	📎
customer_id	integer	The customer ID # this contact belongs to	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎

Add a contact

API Request

POST /api/v3/user HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo...
Content-Type: application/json

{
    "customer_id": 21,
    "username": "my_test_username_393",
    "password": "some test password",
    "name": "Ryan Bantz",
    "email": "ryan@adgadgagadg.com",
    "phone": "888-555-1212"
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/user/379
Content-Type: application/json

{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 379
    }
}

Update a contact

Object Attributes

Attribute	Type	Description
external_key	string	External key value	📎
username	string	Customer portal username	📎
password	string	Customer portal password	📎
name	string	First and last name of the contact	📎
first_name	string	First name of contact	📎
middle_name_glob	string	Middle name/initial	📎
last_name	string	Last name	📎
name_suffix	string	Suffix (e.g. "Jr.", "Sr.", "III", etc.)	📎
title	string	Title	📎
email	string	E-mail address	📎
phone	string	Phone number	📎
mobile	string	Mobile number	📎
user_type_id	integer	User type ID #	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎

Update a contact

API Request

PUT /api/v3/user/366

{
    "customer_id": 19,
    "username": "my_test_username",
    "password": "my_test_password",
    "name": "Jessica Maye",
    "email": "jmae@example.com",
    "phone": "888-222-3432"
}

API Response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "code": 202,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 366
    }
}

Get a specific contact

Object Attributes

Attribute	Type	Description
user_id	integer	The user/contact ID #	📎
external_key	string	External key value	📎
token	string	Unique token	📎
username	string	Customer portal username	📎
name	string	First and last name of the contact	📎
first_name	string	First name of contact	📎
middle_name_glob	string	Middle name/initial	📎
last_name	string	Last name	📎
name_suffix	string	Suffix (e.g. "Jr.", "Sr.", "III", etc.)	📎
display_as	string	(deprecated)	📎
title	string	Title	📎
email	string	E-mail address	📎
phone	string	Phone number	📎
mobile	string	Mobile number	📎
user_type_id	integer	User type ID #	📎
user_type_name	string	User type	📎
customer_id	integer	The customer ID # this contact belongs to	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
write_datetime	datetime	Date/time the user/contact was created	📎
mod_datetime	datetime	Date/time the user/contact was last modified	📎
url_self	string	URL for viewing the user/contact in the GUI	📎

Get a specific contact

API Request

GET /api/v3/user/362

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "user_id": 362,
        "external_key": null,
        "first_name": "Keith",
        "middle_name_glob": null,
        "last_name": "Palmer",
        "name_suffix": null,
        "title": "",
        "email": "keith@chargeover.com",
        "phone": "860-634-1602",
        "write_datetime": "2014-07-08 14:26:01",
        "mod_datetime": "2014-07-08 14:26:01",
        "name": "Keith Palmer",
        "display_as": "Keith Palmer",
        "user_type_id": 1, 
        "user_type_name": "Billing",
        "username": "7yanhoctj6qs"
    }
}

Get a list of contacts

Object Attributes

Attribute	Type	Description
user_id	integer	The user/contact ID #	📎
external_key	string	External key value	📎
token	string	Unique token	📎
username	string	Customer portal username	📎
name	string	First and last name of the contact	📎
first_name	string	First name of contact	📎
middle_name_glob	string	Middle name/initial	📎
last_name	string	Last name	📎
name_suffix	string	Suffix (e.g. "Jr.", "Sr.", "III", etc.)	📎
display_as	string	(deprecated)	📎
title	string	Title	📎
email	string	E-mail address	📎
phone	string	Phone number	📎
mobile	string	Mobile number	📎
user_type_id	integer	User type ID #	📎
user_type_name	string	User type	📎
customer_id	integer	The customer ID # this contact belongs to	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
write_datetime	datetime	Date/time the user/contact was created	📎
mod_datetime	datetime	Date/time the user/contact was last modified	📎
url_self	string	URL for viewing the user/contact in the GUI	📎

Get a list of contacts

API Request

GET /api/v3/user

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "user_id": 348,
            "external_key": null,
            "first_name": "John",
            "middle_name_glob": "",
            "last_name": "Doe",
            "name_suffix": null,
            "title": "",
            "email": "test1@test1.com",
            "phone": "",
            "write_datetime": "2014-07-02 09:58:37",
            "mod_datetime": "2014-07-02 06:05:24",
            "name": "John Doe",
            "display_as": "John Doe",
            "username": "test1@test1.com"
        },
        ...

Query for contacts

Available query parameters:

user_id
external_key
first_name
last_name
email
phone
user_type_id
username
customers.customer_id - Get contacts belonging to a specific customer

Object Attributes

Attribute	Type	Description
user_id	integer	The user/contact ID #	📎
external_key	string	External key value	📎
token	string	Unique token	📎
username	string	Customer portal username	📎
name	string	First and last name of the contact	📎
first_name	string	First name of contact	📎
middle_name_glob	string	Middle name/initial	📎
last_name	string	Last name	📎
name_suffix	string	Suffix (e.g. "Jr.", "Sr.", "III", etc.)	📎
display_as	string	(deprecated)	📎
title	string	Title	📎
email	string	E-mail address	📎
phone	string	Phone number	📎
mobile	string	Mobile number	📎
user_type_id	integer	User type ID #	📎
user_type_name	string	User type	📎
customer_id	integer	The customer ID # this contact belongs to	📎
custom_1	mixed	Custom field #1	📎
custom_2	mixed	Custom field #2	📎
custom_3	mixed	Custom field #3	📎
custom_4	mixed	Custom field #4	📎
custom_5	mixed	Custom field #5	📎
custom_6	mixed	Custom field #6	📎
custom_7	mixed	Custom field #7	📎
custom_8	mixed	Custom field #8	📎
custom_9	mixed	Custom field #9	📎
custom_10	mixed	Custom field #10	📎
custom_11	mixed	Custom field #11	📎
custom_12	mixed	Custom field #12	📎
custom_13	mixed	Custom field #13	📎
custom_14	mixed	Custom field #14	📎
custom_15	mixed	Custom field #15	📎
custom_16	mixed	Custom field #16	📎
custom_17	mixed	Custom field #17	📎
custom_18	mixed	Custom field #18	📎
custom_19	mixed	Custom field #19	📎
custom_20	mixed	Custom field #20	📎
write_datetime	datetime	Date/time the user/contact was created	📎
mod_datetime	datetime	Date/time the user/contact was last modified	📎
url_self	string	URL for viewing the user/contact in the GUI	📎

Query for contacts

API Request

GET /api/v3/user?where=first_name:EQUALS:Keith

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "user_id": 362,
            "external_key": null,
            "first_name": "Keith",
            "middle_name_glob": null,
            "last_name": "Palmer",
            "name_suffix": null,
            "title": "",
            "email": "keith@chargeover.com",
            "phone": "860-634-1602",
            "write_datetime": "2014-07-02 09:58:37",
            "mod_datetime": "2014-07-08 14:26:01",
            "name": "Keith Palmer",
            "display_as": "Keith Palmer",
            "username": "7yanhoctj6qs"
        },
        ...

Send a password reset

By default, calling the password action will send an e-mail to the end-user containing a link. The end-user will follow the link to reset their password.

If you’d instead prefer to explicitly set the password to something for the user, you can tell password to set the password to a passed in value. An email will be sent to the end-user containing the new password.

IMPORTANT: In either of the above two cases, the default behavior sends an e-mail. If you don’t want the e-mail to be sent, use the _flag_emails=0 advanced flag to suppress the outgoing e-mail.

Send a password reset

API Request

POST /api/v3/user/372?action=password HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Set a password

API Request

POST /api/v3/user/372?action=password HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=

{
    "password": "here is the new password"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Log in a user

This fetches a short-lived, one-time-use login URL that you can use to automatically log a user into the ChargeOver customer portal. This link is only valid for a very short amount of time, so you must forward the user to this URL immediately. The user will be immediately and automatically logged into the customer portal.

Log in a user

API Request

POST /api/v3/user/389?action=getLoginURL

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": "https:\/\/dev.chargeover.com\/signup\/r\/logintoken\/3170a017fbfcf660b5004e6e358fbdf9"
}

Delete a contact

API Request

DELETE /api/v3/user/362

API Response

HTTP/1.0 200 OK
Content-Type: application/json

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Invoices

The primary key field for an invoice is invoice_id.

Create an invoice

Requirements

You must specify an existing customer_id, customer_token, or customer_external_key value.
You must specify at least one line item.
Each line item must refer to an existing item_id value.

Notes

The response/id value is the invoice_id value of the newly created invoice.
The Location: header will provide a direct API link to the newly created invoice.

Object Attributes

Attribute

Type

Description

refnumber

string

Invoice reference number

📎

external_key

string

External key value

📎

customer_id

integer

Customer ID #

📎

date

date

Invoice date

📎

currency_id

integer

Currency ID #

📎

class_id

integer

Class ID #

📎

terms_id

integer

Terms ID #

📎

admin_id

integer

Admin/Worker ID #

📎

bill_addr1

string

Billing address line 1

📎

bill_addr2

string

Billing address line 2

📎

bill_addr3

string

Billing address line 3

📎

bill_city

string

Billing address city

📎

bill_state

string

Billing address state

📎

bill_postcode

string

Billing address postal code

📎

bill_country

string

Billing address country

📎

bill_notes

string

(deprecated)

📎

ship_addr1

string

Shipping address line 1

📎

ship_addr2

string

Shipping address line 2

📎

ship_addr3

string

Shipping address line 3

📎

ship_city

string

Shipping address city

📎

ship_state

string

Shipping address state

📎

ship_postcode

string

Shipping address postal code

📎

ship_country

string

Shipping address country

📎

ship_notes

string

(deprecated)

📎

memo

string

Memo/notes to customer

📎

custom_1

mixed

Custom field #1

📎

custom_2

mixed

Custom field #2

📎

custom_3

mixed

Custom field #3

📎

custom_4

mixed

Custom field #4

📎

custom_5

mixed

Custom field #5

📎

custom_6

mixed

Custom field #6

📎

custom_7

mixed

Custom field #7

📎

custom_8

mixed

Custom field #8

📎

custom_9

mixed

Custom field #9

📎

custom_10

mixed

Custom field #10

📎

custom_11

mixed

Custom field #11

📎

custom_12

mixed

Custom field #12

📎

custom_13

mixed

Custom field #13

📎

custom_14

mixed

Custom field #14

📎

custom_15

mixed

Custom field #15

📎

custom_16

mixed

Custom field #16

📎

custom_17

mixed

Custom field #17

📎

custom_18

mixed

Custom field #18

📎

custom_19

mixed

Custom field #19

📎

custom_20

mixed

Custom field #20

📎

line_items - array

A list of line items for the invoice

Attribute	Type	Description
item_id	integer	Item ID # for this line
descrip	string	Description
line_rate	float	Rate
line_quantity	float	Quantity
custom_1	mixed	Custom field #1
custom_2	mixed	Custom field #2
custom_3	mixed	Custom field #3
custom_4	mixed	Custom field #4
custom_5	mixed	Custom field #5

Create an invoice

API Request

POST /api/v3/invoice HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json

{
    "customer_id": 1,
    "bill_addr1": "72 E Blue Grass Road",
    "bill_city": "Willington",
    "bill_state": "Connecticut",
    "bill_postcode": "06279",
    "line_items": [
        {
            "item_id": 307,
            "descrip": "My description goes here",
            "line_rate": 29.95,
            "line_quantity": 12
        },
        {
            "item_id": 293,
            "descrip": "Another description",
            "line_rate": 12.95,
            "line_quantity": 2
        }
    ]
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/invoice/17073
Content-Type: application/json

{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 17073
    }
}

Update an invoice

If you want to keep a line item unchanged, pass just the line_item_id value of the existing line item.

Object Attributes

Attribute

Type

Description

external_key

string

External key value

📎

terms_id

integer

Terms ID #

📎

admin_id

integer

Admin/Worker ID #

📎

bill_addr1

string

Billing address line 1

📎

bill_addr2

string

Billing address line 2

📎

bill_addr3

string

Billing address line 3

📎

bill_city

string

Billing address city

📎

bill_state

string

Billing address state

📎

bill_postcode

string

Billing address postal code

📎

bill_country

string

Billing address country

📎

bill_notes

string

(deprecated)

📎

ship_addr1

string

Shipping address line 1

📎

ship_addr2

string

Shipping address line 2

📎

ship_addr3

string

Shipping address line 3

📎

ship_city

string

Shipping address city

📎

ship_state

string

Shipping address state

📎

ship_postcode

string

Shipping address postal code

📎

ship_country

string

Shipping address country

📎

ship_notes

string

(deprecated)

📎

memo

string

Memo/notes to customer

📎

custom_1

mixed

Custom field #1

📎

custom_2

mixed

Custom field #2

📎

custom_3

mixed

Custom field #3

📎

custom_4

mixed

Custom field #4

📎

custom_5

mixed

Custom field #5

📎

custom_6

mixed

Custom field #6

📎

custom_7

mixed

Custom field #7

📎

custom_8

mixed

Custom field #8

📎

custom_9

mixed

Custom field #9

📎

custom_10

mixed

Custom field #10

📎

custom_11

mixed

Custom field #11

📎

custom_12

mixed

Custom field #12

📎

custom_13

mixed

Custom field #13

📎

custom_14

mixed

Custom field #14

📎

custom_15

mixed

Custom field #15

📎

custom_16

mixed

Custom field #16

📎

custom_17

mixed

Custom field #17

📎

custom_18

mixed

Custom field #18

📎

custom_19

mixed

Custom field #19

📎

custom_20

mixed

Custom field #20

📎

line_items - array

A list of line items for the invoice

Attribute	Type	Description
item_id	integer	Item ID # for this line
descrip	string	Description
line_rate	float	Rate
line_quantity	float	Quantity
custom_1	mixed	Custom field #1
custom_2	mixed	Custom field #2
custom_3	mixed	Custom field #3
custom_4	mixed	Custom field #4
custom_5	mixed	Custom field #5

Update an invoice

API Request

PUT /api/v3/invoice/10009

{
    "date": "2015-06-08",
    "line_items": [
        {
            "item_id": 3,
            "line_rate": 29.95,
            "line_quantity": 3,
            "descrip": "Add this new line item to the invoice."
        },
        {
            "line_item_id": 2575
        }
    ]
}

API Response

HTTP/1.1 202 Accepted

{
    "code": 202,
    "status": "OK",
    "message": "",
    "response": {
        "id": 10009
    }
}

Get a list of invoices

Returns a list of all invoices.

Object Attributes

Attribute	Type	Description
invoice_id	integer	Invoice ID #	📎
refnumber	string	Invoice reference number	📎
external_key	string	External key value	📎
package_id	integer	Subscription ID # this invoice was generated from	📎
customer_id	integer	Customer ID #	📎
brand_id	integer	Brand ID #	📎
brand_name	string	Brand name	📎
write_datetime	datetime	Date/time the invoice was created	📎
void_datetime	datetime	Date/time the invoice was voided	📎
date	date	Invoice date	📎
currency_id	integer	Currency ID #	📎
currency_symbol	string	Currency symbol	📎
currency_iso4217	string	Currency ISO 4217 representation	📎
class_id	integer	Class ID #	📎
class_name	string	Class Name	📎
paycycle	string	Payment cycle	📎
paycycle_name	string	Payment cycle name	📎
terms_id	integer	Terms ID #	📎
terms_name	string	Terms name	📎
terms_days	integer	Terms # of days	📎
admin_id	integer	Admin/Worker ID #	📎
admin_name	string	Admin/Worker Name	📎
token	string	Unique token	📎
bill_addr1	string	Billing address line 1	📎
bill_addr2	string	Billing address line 2	📎
bill_addr3	string	Billing address line 3	📎
bill_city	string	Billing address city	📎
bill_state	string	Billing address state	📎
bill_postcode	string	Billing address postal code	📎
bill_country	string	Billing address country	📎
bill_notes	string	(deprecated)	📎
bill_block	string	Printable billing address	📎
ship_addr1	string	Shipping address line 1	📎
ship_addr2	string	Shipping address line 2	📎
ship_addr3	string	Shipping address line 3	📎
ship_city	string	Shipping address city	📎
ship_state	string	Shipping address state	📎
ship_postcode	string	Shipping address postal code	📎
ship_country	string	Shipping address country	📎
ship_notes	string	(deprecated)	📎
ship_block	string	Printable shipping address	📎
cycle_pre_from_date	date	For pre-billing, cycle start date	📎
cycle_pre_to_date	date	For pre-billing, cycle end date	📎
cycle_this_date	date	Cycle date (generally the invoice date)	📎
cycle_post_from_date	date	For post-billing (in arrears), cycle start date	📎
cycle_post_to_date	date	For post-billing (in arrears), cycle end date	📎
url_permalink	string	URL to view the invoice	📎
url_pdflink	string	URL to download the invoice PDF	📎
url_paylink	string	URL to pay for the invoice	📎
url_self	string	URL for viewing the invoice in the GUI	📎
is_paid	boolean	Whether or not the invoice has been paid	📎
is_void	boolean	Whether or not the invoice has been voided	📎
is_overdue	boolean	Whether or not the invoice is overdue	📎
due_date	date	Date the invoice is due	📎
days_overdue	integer	# of days overdue the invoice is	📎
paid_date	date	Date this invoice was paid	📎
balance	float	Balance of the invoice	📎
applied	float	Amount applied to the invoice	📎
total	float	Invoice total	📎
subtotal	float	Invoice subtotal	📎
taxes	float	Taxes	📎
credits	float	Amount of credits applied to the invoice	📎
payments	float	Amount of payments applied to the invoice	📎
writeoffs	float	Amount written off	📎
refunds	float	Amount refunded	📎
overdue	float	Amount overdue	📎
declines	integer	# of times that payment was attempted and failed for this invoice	📎
sum_base	float	Sum of the amounts of all base fees on the invoice	📎
sum_usage	float	Sum of the amounts of all usage-based/metered fees on the invoice	📎
sum_onetime	float	Sum of the amounts of all of the one-time charges on the invoice	📎
invoice_status_name	string	Human-friendly invoice status	📎
invoice_status_str	string	Status string	📎
invoice_status_state	string	Status code	📎
memo	string	Memo/notes to customer	📎
custom_1	mixed	Custom field #1	📎

API

Getting Started

Finding your API Endpoint

Authentication

Libraries/Code

PHP

Python

Java

C# / .NET

Filter / Sort / Pagination

Filtering (Query)

Filtering (Query)

API Examples

Sorting

Sorting

API Request

API Response

Paging (Limit/Offset)

Paging (Limit/Offset)

API Request

API Response

Counting Objects

Counting Objects

Counting Objects

API Examples

API Response

External Keys

External Key Examples

External Key Examples

API Examples

Object Tokens

Object Token Examples

Object Token Examples

API Examples

Escape Syntax For Reserved Characters

Escape Syntax Example

Escape Syntax Example

API Request

API Response

On Behalf Of...

On Behalf Of...

On Behalf Of...

API Request

Versioning

Bulk/Batch Requests

Batch Request

Batch Request

API Request

API Response

JSONPath in Batches

JSONPath in Batches

API Request

API Response

Reporting/Aggregation

Get a List of Reports

Get a List of Reports

API Request

API Response

Get a Specific Report

Get a Specific Report

API Request

API Response

Rate Limits

HTTP Status Codes

Objects

Customers

Create a customer

Object Attributes

Create a customer

API Request

API Response

PHP Example

CSHARP Example

Python Example

Update a customer

Object Attributes

Update a customer

API Request

API Response

PHP Example