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.
The first step towards integration is finding your endpoint and credentials.
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/customerTo 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=15To 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
All API calls are made over a secure SSL/HTTPS connection. In addition to the point-to-point encryption SSL/HTTPS provides, ChargeOver offers two different options for authentication.
The easiest way to get started with the API is to use standard "HTTP Basic Auth". This uses the industry-standard HTTP authentication to authenticate access to the REST API.
If you need more security, ChargeOver also offers a signed, HMAC-SHA256 based authentication method. The advantages of the signature-based approach are:
We recommend you develop using HTTP basic auth, and then migrate to using signatures in production environments.
For more information on HTTP Basic Authentication, please visit the links below:
Make sure to visit the ChargeOver GitHub account. Feel free to contact us for additional sample code.
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.
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 nullTo 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)
// 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
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.
.Example: Using "offset" and "limit" to page a list of contactsGET http://dev.chargeover.com/api/v3/user?offset=8&limit=2
"offset=8&limit=2" means "starting at record 8, fetch the next 2 records (in this case, contacts)"
HTTP/1.0 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...
}
]
}
You can get a count of the number of objects by using the /_count endpoints.
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.
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:
Contact us to enable any optional external key policies for your account.
Adding external_key values to ChargeOver enables several "short-cuts" when working with the ChargeOver REST API.
external_key instead of using the customer_id, item_id, etc.
*_external_key instead of their *_id values
Refer to the examples to the right.
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.
You can reference objects within ChargeOver by their token value instead of the *_id value.
token instead of using the customer_id, item_id, etc.
*_token instead of their *_id values
Refer to the examples to the right.
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.
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
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": []
}
]
}
]
}
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.
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
|
| 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.
|
| 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.
POST your batch requests to the /api/v3/_bulk endpoint.
POST https://dev.chargeover.com/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"
}
}
]{
"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
}
]
}
}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".
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
}
]It is possible to pull reporting and aggregation data via the ChargeOver REST API.
Allows you to get a list of all reports with each report's name and report_id number.
GET /api/v3/_report
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Host: dev.chargeover.com
Content-Type: application/json
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
},
{
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.
POST /api/v3/_report/58?action=reportData
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Host: dev.chargeover.com
Content-Type: application/json
[
"transaction_transaction_date:GTE:2017-09-11",
"transaction_transaction_date:LTE:2017-10-11"
]
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
}
}
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.
The API follows these rules for HTTP requests:
POST.
PUT.
GET.
GET.
POST.
201 Created HTTP response. You'll also get back a Location: header with the URL of the new object.
202 Accepted HTTP response. You'll also get back a Location: header with the URL of the new object.
200 OK HTTP response.
404 Not Found HTTP response.
200 OK HTTP response.
200 OK HTTP response.
400 Bad Request HTTP response.
401 Unauthorized HTTP response.
429 Too Many Requests HTTP response.
500 Internal Server Error HTTP response.
The ChargeOver object model is documented below.
The primary key field for customers is customer_id.
Note that the response/id value will be the customer_id value for the newly created customer.
| Attribute | Type | Description | |
|---|---|---|---|
| parent_customer_id | integer | Parent customer ID # | 📎 |
| superuser_id | integer | Main contact 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 | 📎 |
| custtype_id | integer | Customer type 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 | 📎 |
| 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| custom_6 | string | Custom field #6 | 📎 |
| custom_7 | string | Custom field #7 | 📎 |
| custom_8 | string | Custom field #8 | 📎 |
| custom_9 | string | Custom field #9 | 📎 |
| custom_10 | string | Custom field #10 | 📎 |
| custom_11 | string | Custom field #11 | 📎 |
| custom_12 | string | Custom field #12 | 📎 |
| custom_13 | string | Custom field #13 | 📎 |
| custom_14 | string | Custom field #14 | 📎 |
| custom_15 | string | Custom field #15 | 📎 |
| custom_16 | string | Custom field #16 | 📎 |
| custom_17 | string | Custom field #17 | 📎 |
| custom_18 | string | Custom field #18 | 📎 |
| custom_19 | string | Custom field #19 | 📎 |
| custom_20 | string | 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 # | 📎 |
POST /api/v3/customer HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Host: dev.chargeover.com
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"
}
| 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 # | 📎 |
| custtype_id | integer | Customer type 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| custom_6 | string | Custom field #6 | 📎 |
| custom_7 | string | Custom field #7 | 📎 |
| custom_8 | string | Custom field #8 | 📎 |
| custom_9 | string | Custom field #9 | 📎 |
| custom_10 | string | Custom field #10 | 📎 |
| custom_11 | string | Custom field #11 | 📎 |
| custom_12 | string | Custom field #12 | 📎 |
| custom_13 | string | Custom field #13 | 📎 |
| custom_14 | string | Custom field #14 | 📎 |
| custom_15 | string | Custom field #15 | 📎 |
| custom_16 | string | Custom field #16 | 📎 |
| custom_17 | string | Custom field #17 | 📎 |
| custom_18 | string | Custom field #18 | 📎 |
| custom_19 | string | Custom field #19 | 📎 |
| custom_20 | string | 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 # | 📎 |
PUT https://dev.chargeover.com/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"
}Notes:
superuser_id field is the primary contact (user) for this customer
| 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 # | 📎 |
| custtype_id | integer | Customer type 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| custom_6 | string | Custom field #6 | 📎 |
| custom_7 | string | Custom field #7 | 📎 |
| custom_8 | string | Custom field #8 | 📎 |
| custom_9 | string | Custom field #9 | 📎 |
| custom_10 | string | Custom field #10 | 📎 |
| custom_11 | string | Custom field #11 | 📎 |
| custom_12 | string | Custom field #12 | 📎 |
| custom_13 | string | Custom field #13 | 📎 |
| custom_14 | string | Custom field #14 | 📎 |
| custom_15 | string | Custom field #15 | 📎 |
| custom_16 | string | Custom field #16 | 📎 |
| custom_17 | string | Custom field #17 | 📎 |
| custom_18 | string | Custom field #18 | 📎 |
| custom_19 | string | Custom field #19 | 📎 |
| custom_20 | string | 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 | 📎 |
| custtype_name | string | Customer type 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_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 # | 📎 |
HTTP/1.0 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"
},
...Available query parameters:
customer_status_state:
customer_status_str:
| 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 # | 📎 |
| custtype_id | integer | Customer type 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| custom_6 | string | Custom field #6 | 📎 |
| custom_7 | string | Custom field #7 | 📎 |
| custom_8 | string | Custom field #8 | 📎 |
| custom_9 | string | Custom field #9 | 📎 |
| custom_10 | string | Custom field #10 | 📎 |
| custom_11 | string | Custom field #11 | 📎 |
| custom_12 | string | Custom field #12 | 📎 |
| custom_13 | string | Custom field #13 | 📎 |
| custom_14 | string | Custom field #14 | 📎 |
| custom_15 | string | Custom field #15 | 📎 |
| custom_16 | string | Custom field #16 | 📎 |
| custom_17 | string | Custom field #17 | 📎 |
| custom_18 | string | Custom field #18 | 📎 |
| custom_19 | string | Custom field #19 | 📎 |
| custom_20 | string | 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 | 📎 |
| custtype_name | string | Customer type 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_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 # | 📎 |
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 using their customer_id.
| 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 # | 📎 |
| custtype_id | integer | Customer type 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| custom_6 | string | Custom field #6 | 📎 |
| custom_7 | string | Custom field #7 | 📎 |
| custom_8 | string | Custom field #8 | 📎 |
| custom_9 | string | Custom field #9 | 📎 |
| custom_10 | string | Custom field #10 | 📎 |
| custom_11 | string | Custom field #11 | 📎 |
| custom_12 | string | Custom field #12 | 📎 |
| custom_13 | string | Custom field #13 | 📎 |
| custom_14 | string | Custom field #14 | 📎 |
| custom_15 | string | Custom field #15 | 📎 |
| custom_16 | string | Custom field #16 | 📎 |
| custom_17 | string | Custom field #17 | 📎 |
| custom_18 | string | Custom field #18 | 📎 |
| custom_19 | string | Custom field #19 | 📎 |
| custom_20 | string | 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 | 📎 |
| custtype_name | string | Customer type 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_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 # | 📎 |
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,
"custtype_id": null,
"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": []
}
}
Allows you to delete a customer.
Note that you can only delete a customer if:
Specify the user you want to assign as the customer's primary contact using the user's user_id.
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.
The primary key field for a user is user_id
Notes:
| Attribute | Type | Description | |
|---|---|---|---|
| external_key | string | External key value | 📎 |
| 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.) | 📎 |
| title | string | Title | 📎 |
| string | E-mail address | 📎 | |
| phone | string | Phone number | 📎 |
| user_type_id | integer | User type ID # | 📎 |
| custom_1 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #3 | 📎 |
| custom_5 | string | Custom field #3 | 📎 |
POST /api/v3/user HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo...
Host: dev.chargeover.com
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"
}| Attribute | Type | Description | |
|---|---|---|---|
| external_key | string | External key value | 📎 |
| 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.) | 📎 |
| title | string | Title | 📎 |
| string | E-mail address | 📎 | |
| phone | string | Phone number | 📎 |
| user_type_id | integer | User type ID # | 📎 |
| custom_1 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #3 | 📎 |
| custom_5 | string | Custom field #3 | 📎 |
| 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 | 📎 |
| string | E-mail address | 📎 | |
| phone | string | Phone 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #3 | 📎 |
| custom_5 | string | Custom field #3 | 📎 |
| 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 | 📎 |
{
"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"
}
}| 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 | 📎 |
| string | E-mail address | 📎 | |
| phone | string | Phone 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #3 | 📎 |
| custom_5 | string | Custom field #3 | 📎 |
| 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 | 📎 |
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"
},
... Available query parameters:
user_id
external_key
first_name
last_name
email
phone
username
customers.customer_id - Get contacts belonging to a specific customer
| 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 | 📎 |
| string | E-mail address | 📎 | |
| phone | string | Phone 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #3 | 📎 |
| custom_5 | string | Custom field #3 | 📎 |
| 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 | 📎 |
{
"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"
},
...
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.
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.
The primary key field for an invoice is invoice_id.
customer_id, customer_token, or customer_external_key value.
item_id value.
Location: header will provide a direct API link to the newly created invoice.
| 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 # | 📎 |
| 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 | 📎 | |
| ship_addr1 | string | 📎 | |
| ship_addr2 | string | 📎 | |
| ship_addr3 | string | 📎 | |
| ship_city | string | 📎 | |
| ship_state | string | 📎 | |
| ship_postcode | string | 📎 | |
| ship_country | string | 📎 | |
| ship_notes | string | 📎 | |
| memo | string | Memo/notes to customer | 📎 |
| line_items | array | A list of line items for the invoice | 📎 |
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
}
]
}If you want to keep a line item unchanged, pass just the line_item_id value of the existing line item.
| Attribute | Type | Description | |
|---|---|---|---|
| refnumber | string | Invoice reference number | 📎 |
| 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 | 📎 | |
| ship_addr1 | string | 📎 | |
| ship_addr2 | string | 📎 | |
| ship_addr3 | string | 📎 | |
| ship_city | string | 📎 | |
| ship_state | string | 📎 | |
| ship_postcode | string | 📎 | |
| ship_country | string | 📎 | |
| ship_notes | string | 📎 | |
| memo | string | Memo/notes to customer | 📎 |
| line_items | array | A list of line items for the invoice | 📎 |
Returns a list of all invoices.
| 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 # | 📎 |
| 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 | 📎 |
| 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 | 📎 | |
| bill_block | string | Printable billing address | 📎 |
| ship_addr1 | string | 📎 | |
| ship_addr2 | string | 📎 | |
| ship_addr3 | string | 📎 | |
| ship_city | string | 📎 | |
| ship_state | string | 📎 | |
| ship_postcode | string | 📎 | |
| ship_country | string | 📎 | |
| ship_notes | string | 📎 | |
| ship_block | string | 📎 | |
| 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 | 📎 |
| declines | integer | # of times that payment was attempted and failed for this invoice | 📎 |
| sum_base | float | 📎 | |
| sum_usage | float | 📎 | |
| sum_onetime | float | 📎 | |
| 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| line_items | array | A list of line items for the invoice | 📎 |
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"invoice_id": 10160,
"currency_id": 1,
"brand_id": 1,
"terms_id": 3,
"admin_id": 0,
"external_key": null,
"token": "7s163e80302k",
"refnumber": "10160",
"cycle_pre_from_date": "2017-10-04",
"cycle_pre_to_date": "2017-11-03",
"cycle_this_date": "2017-10-03",
"cycle_post_from_date": "2017-08-28",
"cycle_post_to_date": "2017-10-03",
"bill_addr1": "56 Cowles Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Mt Pleasant",
"bill_state": "MI",
"bill_postcode": "48858",
"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,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-10-03 08:54:13",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "",
"invoice_status_name": "Paid",
"invoice_status_str": "closed-paid",
"invoice_status_state": "c",
"subtotal": 117.8,
"total": 117.8,
"taxes": 0,
"credits": 0,
"payments": 117.8,
"writeoffs": 0,
"declines": 0,
"applied": 117.8,
"sum_base": 112.9,
"sum_usage": 0,
"sum_onetime": 0,
"is_paid": true,
"paid_date": "2017-11-08",
"balance": 0,
"is_void": false,
"due_date": "2017-10-03",
"terms_name": "Due on Receipt",
"terms_days": 0,
"days_overdue": 76,
"is_overdue": false,
"date": "2017-10-03",
"bill_block": "56 Cowles Road\r\nMt Pleasant, MI 48858\r\nUnited States",
"ship_block": "",
"url_permalink": "https://dev.chargeover.com/r/invoice/view/7s163e80302k",
"url_paylink": "https://dev.chargeover.com/r/trans/pay/7s163e80302k",
"url_pdflink": "https://dev.chargeover.com/r/invoice/pdf/7s163e80302k",
"url_self": "https://dev.chargeover.com/admin/r/invoice/view/10160",
"package_id": 617,
"customer_id": 424
},
........
{
"invoice_id": 10203,
"currency_id": 1,
"brand_id": 1,
"terms_id": 3,
"admin_id": null,
"external_key": null,
"token": "e7a23gi4vhyc",
"refnumber": "10203",
"cycle_pre_from_date": "2017-12-03",
"cycle_pre_to_date": "2018-01-02",
"cycle_this_date": "2017-12-03",
"cycle_post_from_date": "2017-11-03",
"cycle_post_to_date": "2017-12-02",
"bill_addr1": "104 Abigail Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Brantford",
"bill_state": "MA",
"bill_postcode": "null",
"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,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-12-03 07:23:47",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "",
"invoice_status_name": "Overdue",
"invoice_status_str": "open-overdue",
"invoice_status_state": "o",
"subtotal": 45,
"total": 45,
"taxes": 0,
"credits": 0,
"payments": 0,
"writeoffs": 0,
"declines": 3,
"applied": 0,
"sum_base": 45,
"sum_usage": 0,
"sum_onetime": 0,
"is_paid": false,
"paid_date": null,
"balance": 45,
"is_void": false,
"due_date": "2017-12-03",
"terms_name": "Due on Receipt",
"terms_days": 0,
"days_overdue": 15,
"is_overdue": true,
"date": "2017-12-03",
"bill_block": "104 Abigail Road\r\nBrantford, MA\r\nUnited States",
"ship_block": "",
"url_permalink": "https://dev.chargeover.com/r/invoice/view/e7a23gi4vhyc",
"url_paylink": "https://dev.chargeover.com/r/trans/pay/e7a23gi4vhyc",
"url_pdflink": "https://dev.chargeover.com/r/invoice/pdf/e7a23gi4vhyc",
"url_self": "https://dev.chargeover.com/admin/r/invoice/view/10203",
"package_id": 618,
"customer_id": 414
}
]
}| 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 # | 📎 |
| 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 | 📎 |
| 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 | 📎 | |
| bill_block | string | Printable billing address | 📎 |
| ship_addr1 | string | 📎 | |
| ship_addr2 | string | 📎 | |
| ship_addr3 | string | 📎 | |
| ship_city | string | 📎 | |
| ship_state | string | 📎 | |
| ship_postcode | string | 📎 | |
| ship_country | string | 📎 | |
| ship_notes | string | 📎 | |
| ship_block | string | 📎 | |
| 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 | 📎 |
| declines | integer | # of times that payment was attempted and failed for this invoice | 📎 |
| sum_base | float | 📎 | |
| sum_usage | float | 📎 | |
| sum_onetime | float | 📎 | |
| 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| line_items | array | A list of line items for the invoice | 📎 |
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"invoice_id": 10643,
"currency_id": 1,
"terms_id": 2,
"admin_id": 3,
"token": "a1719w4r1ozc",
"refnumber": "10643",
"cycle_pre_from_date": "2015-12-20",
"cycle_pre_to_date": "2016-01-19",
"cycle_this_date": "2015-12-20",
"cycle_post_from_date": "2015-11-20",
"cycle_post_to_date": "2015-12-19",
"bill_addr1": "72 E Blue Grass Road",
"bill_addr2": "Suite D",
"bill_addr3": null,
"bill_city": "Willington",
"bill_state": "CT",
"bill_postcode": "06279",
"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,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2015-12-20 08:00:54",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "Ford Prefect",
"invoice_status_name": "Unpaid",
"invoice_status_str": "open-unpaid",
"invoice_status_state": "o",
"subtotal": 15.95,
"total": 15.95,
"taxes": 0,
"credits": 0,
"payments": 0,
"applied": 0,
"sum_base": 15.95,
"sum_usage": 0,
"sum_onetime": 0,
"is_paid": false,
"balance": 15.95,
"is_void": false,
"due_date": "2016-01-19",
"terms_name": "Net 30",
"terms_days": 30,
"days_overdue": 0,
"is_overdue": false,
"date": "2015-12-20",
"delay_datetime": null,
"bill_block": "72 E Blue Grass Road\r\nSuite D\r\nWillington, CT 06279\r\nUnited States",
"ship_block": "",
"url_permalink": "https:\/\/dev.chargeover.com\/r\/invoice\/view\/a1719w4r1ozc",
"url_paylink": "https:\/\/dev.chargeover.com\/r\/trans\/pay\/a1719w4r1ozc",
"url_pdflink": "https:\/\/dev.chargeover.com\/r\/invoice\/pdf\/a1719w4r1ozc",
"package_id": 708,
"customer_id": 179,
"line_items": [
{
"invoice_id": 10643,
"item_id": 295,
"tierset_id": 309,
"descrip": "Monthly mountain moving service",
"line_rate": 15.95,
"line_quantity": 1,
"line_prorate": 1,
"line_usage": 0,
"usage_from": 0,
"usage_to": 0,
"tax_id": null,
"tax_group_id": null,
"tax_taxable": 15.95,
"tax_taxed": 0,
"tax_total": 0,
"is_base": true,
"is_free": false,
"is_setup": false,
"is_usage": false,
"is_recurring": true,
"is_taxed": "0",
"custom_1": null,
"custom_2": null,
"custom_3": null,
"item_name": "Monthly Mountain Moving",
"item_external_key": null,
"item_token": "4zljsft146y0",
"item_accounting_sku": null,
"item_units": null,
"tax_name": null,
"tax_group_name": null,
"line_subtotal": 15.95,
"line_total": 15.95,
"line_item_id": 3280,
"package_line_id": 850
}
]
}
}Available query parameters:
invoice_id
refnumber
customer_id
bill_state
ship_state
bill_country
ship_country
invoice_status_str - See the list of valid values below
invoice_status_state - See the list of valid values below
package_token
package_id
date
currency_id
token
custom_1
custom_2
custom_3
line_items.item_id
line_items.custom_1
line_items.custom_2
line_items.custom_3
transaction.transaction_id - Get a list of invoices paid by this transaction
Valid values for invoice_status_str:
Valid values for invoice_status_state:
o (any “open” invoice, i.e. anything with money due)
c (any “closed” invoice, i.e. anything without money due)
By default, only the overview invoice details are returned (i.e. no individual line items). If you get a specific invoice by invoice id value
(e.g. GET /api/v3/invoice/1234) you’ll get back the invoice line items.
| 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 # | 📎 |
| 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 | 📎 |
| 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 | 📎 | |
| bill_block | string | Printable billing address | 📎 |
| ship_addr1 | string | 📎 | |
| ship_addr2 | string | 📎 | |
| ship_addr3 | string | 📎 | |
| ship_city | string | 📎 | |
| ship_state | string | 📎 | |
| ship_postcode | string | 📎 | |
| ship_country | string | 📎 | |
| ship_notes | string | 📎 | |
| ship_block | string | 📎 | |
| 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 | 📎 |
| declines | integer | # of times that payment was attempted and failed for this invoice | 📎 |
| sum_base | float | 📎 | |
| sum_usage | float | 📎 | |
| sum_onetime | float | 📎 | |
| 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 | string | Custom field #1 | 📎 |
| custom_2 | string | Custom field #2 | 📎 |
| custom_3 | string | Custom field #3 | 📎 |
| custom_4 | string | Custom field #4 | 📎 |
| custom_5 | string | Custom field #5 | 📎 |
| line_items | array | A list of line items for the invoice | 📎 |
GET /api/v3/invoice?where=customer_id:EQUALS:1,invoice_status_state:EQUALS:o&limit=1000 HTTP/1.1
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"invoice_id": "2688",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"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-11-09 18:10:03",
"void_datetime": null,
"invoice_status_name": "Unpaid",
"invoice_status_str": "open-unpaid",
"invoice_status_state": "o",
"total": 150,
"credits": 0,
"payments": 0,
"is_paid": false,
"balance": 150,
"is_void": false,
"bill_block": "",
"ship_block": "",
"url_permalink": "http:\/\/dev.chargeover.com\/signup\/\/index.php?stage=cocinvoices\/viewPublic&token=67889778d7a2b2e9e866fdaaddb1c84c",
"url_pdflink": "http:\/\/dev.chargeover.com\/signup\/\/index.php?stage=cocinvoices\/pdf&token=67889778d7a2b2e9e866fdaaddb1c84c",
"customer_id": "1"
}
]
}Allows you to add a late fee to an invoice. The late fee amount is dictated by the configuration of the Late Fees feature in your account.
ChargeOver allows you to schedule a full payment or several partial payments to one-time invoices via the REST API. You must specify the amount and date of the payment.
If desired, you can specify a certain credit card or ACH of the customer's to be used for the payment by providing the creditcard_id or ach_id in the paymethod field. Otherwise, you can use any to allow any of the customer's stored payment methods to be used.
You can also use crd to have the payment charged to any credit card stored for the customer, or ach to specify the payment method as any of the stored ACH accounts the customer has.
POST /api/v3/invoice/5052?action=schedule
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json"Comment: You can specify a specific creditcard or ach to use as the payment method:"
{
"schedule": [
{
"amount": 50,
"date": "2017-10-20",
"creditcard_id": 9
},
{
"amount": 25,
"date": "2017-10-25",
"creditcard_id": 9
}
]
}
"Comment: To schedule with ANY payment method the customer has on file:"
{
"schedule": [
{
"amount": 10,
"date": "2017-10-28",
"paymethod": "any"
}
]
}
"Comment: To schedule the payment(s) with ANY CREDITCARD the customer has on file:"
{
"schedule": [
{
"amount": 10,
"date": "2017-10-28",
"paymethod": "crd"
}
]
}
"Comment: To schedule the payment(s) with ANY ACH the customer has on file:"
{
"schedule": [
{
"amount": 10,
"date": "2017-10-28",
"paymethod": "ach"
}
]
}
This allows you to override the tax configurations in your account and specify a specific tax amount to charge when creating an invoice.
POST /api/v3/invoice
Content-Type: application/json{
"customer_id": 57,
"bill_addr1": "78 W Blue Grass Road",
"bill_city": "Willington",
"bill_state": "Connecticut",
"bill_postcode": "06279",
"line_items": [
{
"item_id": 247,
"descrip": "My description goes here",
"line_rate": 29.95,
"line_quantity": 12,
"tax_total": 34.56,
"tax_override": true,
"tax_name": "Connecticut"
}
]
} This will remove all scheduled payments from a specific one-time invoice.
POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json{
"number": "4111 1111 1111 1111",
"expdate_year": "2017",
"expdate_month": "08",
"name": "Keith Palmer",
"address": "72 E Blue Grass Road",
"city": "Willington",
"state": "CT",
"postcode": "06279",
"country": "United States"
}
POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json{
"number": "1234-1234-1234",
"routing": "072403004",
"name": "Keith Palmer",
"type": "chec"
}
If a customer has an available balance (due to credit given, or previous overpayment), you can use this to apply their open/available customer balance to an invoice.
Send an invoice via e-mail. You can specify an email template to use with the message_id, which is the id number you see in the URL when you edit an email template in ChargeOver.
POST /api/v3/invoice/13011?action=email{
// Each of these is OPTIONAL, and can be used to over-ride the default email templates, etc.
// "email": "johndoe@send-invoice-to.com",
// "subject": "Test subject",
// "body": "Override the default message body here",
// "from": "you@your-company.com",
// "template_name": "mandrill-template-name",
// "template_opts": "merge_language=handlebars"
}
// If you wish to use an existing template, specify the message_id:
{ "email": "johndoe@send-invoice-to.com",
"from": "you@your-company.com",
"message_id": "1"
}
Physically print a hard-copy of an invoice, and mail it (via USPS or other local carrier) to the customer.
This requires an active subscription with one of ChargeOver's supported print vendors (Docsaway, Postal Methods, etc.).
A payment transaction is used to indicate an invoice has been paid (either entirely paid, or partially paid for).
Note: This does not actually charge a credit card or an ACH account. If you're trying to do that, please see the attempt a payment endpoint.
Notes:
visa, mastercard, american-express, discover, check, paypal, credit, ach
| Attribute | Type | Description | |
|---|---|---|---|
| customer_id | integer | Customer ID # | 📎 |
| gateway_id | integer | Payment gateway ID # | 📎 |
| gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
| gateway_transid | string | Payment gateway transaction identifier | 📎 |
| gateway_method | string | Payment gateway method | 📎 |
| gateway_msg | string | An error message or note from the payment gateway | 📎 |
| external_key | string | Transaction external key value | 📎 |
| amount | float | Total transaction amount (refunds will be negative) | 📎 |
| transaction_date | date | Date of the transaction | 📎 |
| transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
| transaction_method | string | Transaction method | 📎 |
| transaction_detail | string | Transaction details | 📎 |
| transaction_datetime | datetime | Date/time of the transaction was created | 📎 |
| void_datetime | datetime | Date/time the transaction was voided | 📎 |
POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json{
"customer_id": 1,
"gateway_id": 1,
"gateway_status": 1,
"gateway_transid": "abcd1234",
"gateway_msg": "test gateway message",
"gateway_method": "check",
"amount": 15.95,
"transaction_type": "pay",
"transaction_detail": "here are some details",
"transaction_datetime": "2013-06-20 18:48:17",
"_comment": "You can specify which invoices to apply the payments to...",
"applied_to": [
{
"invoice_id": 16891
}
],
"_comment": "... or be even more specific, and tell ChargeOver what ",
"_comment": " invoices to apply the payments to, and what amounts/splits",
"_comment": " to apply to each of the invoices...",
"applied_to": [
{
"invoice_id": 10071,
"applied": 10.95
},
{
"invoice_id": 10072,
"applied": 5.0
}
],
"_comment": "... or just tell ChargeOver to auto-apply it to the oldest, ",
"_comment": " newest, or 'best fit' invoices (based on amount/date).",
"auto_apply": "oldest_first",
"auto_apply": "newest_first",
"auto_apply": "best_fit",
}| Attribute | Type | Description | |
|---|---|---|---|
| transaction_id | integer | Transaction ID # | 📎 |
| customer_id | integer | Customer ID # | 📎 |
| brand_id | integer | Brand ID # | 📎 |
| gateway_id | integer | Payment gateway ID # | 📎 |
| gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
| gateway_transid | string | Payment gateway transaction identifier | 📎 |
| gateway_method | string | Payment gateway method | 📎 |
| gateway_msg | string | An error message or note from the payment gateway | 📎 |
| gateway_err_code | integer | 📎 | |
| gateway_err_detail | string | 📎 | |
| gateway_opts | mixed | 📎 | |
| token | string | A unique token for the transaction | 📎 |
| external_key | string | Transaction external key value | 📎 |
| currency_id | integer | Currency ID # | 📎 |
| currency_iso4217 | string | Currency ISO 4217 code | 📎 |
| currency_symbol | string | Currency symbol | 📎 |
| amount | float | Total transaction amount (refunds will be negative) | 📎 |
| fee | float | Transaction fee (if gateway provides this data) | 📎 |
| applied | float | Amount that is applied to invoices | 📎 |
| unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 |
| transaction_date | date | Date of the transaction | 📎 |
| transaction_status_name | string | Human-friendly transaction status | 📎 |
| transaction_status_str | string | Status string | 📎 |
| transaction_status_state | string | State code | 📎 |
| transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
| transaction_type_name | string | Transaction type name | 📎 |
| transaction_method | string | Transaction method | 📎 |
| transaction_detail | string | Transaction details | 📎 |
| transaction_datetime | datetime | Date/time of the transaction was created | 📎 |
| transaction_ipaddr | string | IP address that created the transaction | 📎 |
| void_datetime | datetime | Date/time the transaction was voided | 📎 |
| url_self | string | URL for viewing the transaction in the GUI | 📎 |
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"transaction_id": 92,
"gateway_id": 204,
"currency_id": 1,
"token": "rx2oa38tpubq",
"transaction_date": "2015-03-02",
"gateway_status": 1,
"gateway_transid": "68fcht",
"gateway_msg": "",
"amount": 3.98,
"fee": 0,
"transaction_type": "pay",
"transaction_method": "Mastercard",
"transaction_detail": "x5454",
"transaction_datetime": "2015-03-02 18:40:16",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 1,
"applied_to": [
{
"invoice_id": "10004",
"applied": 3.98
}
]
}
}| Attribute | Type | Description | |
|---|---|---|---|
| transaction_id | integer | Transaction ID # | 📎 |
| customer_id | integer | Customer ID # | 📎 |
| brand_id | integer | Brand ID # | 📎 |
| gateway_id | integer | Payment gateway ID # | 📎 |
| gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
| gateway_transid | string | Payment gateway transaction identifier | 📎 |
| gateway_method | string | Payment gateway method | 📎 |
| gateway_msg | string | An error message or note from the payment gateway | 📎 |
| gateway_err_code | integer | 📎 | |
| gateway_err_detail | string | 📎 | |
| gateway_opts | mixed | 📎 | |
| token | string | A unique token for the transaction | 📎 |
| external_key | string | Transaction external key value | 📎 |
| currency_id | integer | Currency ID # | 📎 |
| currency_iso4217 | string | Currency ISO 4217 code | 📎 |
| currency_symbol | string | Currency symbol | 📎 |
| amount | float | Total transaction amount (refunds will be negative) | 📎 |
| fee | float | Transaction fee (if gateway provides this data) | 📎 |
| applied | float | Amount that is applied to invoices | 📎 |
| unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 |
| transaction_date | date | Date of the transaction | 📎 |
| transaction_status_name | string | Human-friendly transaction status | 📎 |
| transaction_status_str | string | Status string | 📎 |
| transaction_status_state | string | State code | 📎 |
| transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
| transaction_type_name | string | Transaction type name | 📎 |
| transaction_method | string | Transaction method | 📎 |
| transaction_detail | string | Transaction details | 📎 |
| transaction_datetime | datetime | Date/time of the transaction was created | 📎 |
| transaction_ipaddr | string | IP address that created the transaction | 📎 |
| void_datetime | datetime | Date/time the transaction was voided | 📎 |
| url_self | string | URL for viewing the transaction in the GUI | 📎 |
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"transaction_id": 1,
"gateway_id": 101,
"currency_id": 1,
"gateway_status": 1,
"gateway_transid": "*TEST CC* Mon, 23 Jun 2014 22:48:20 -0500",
"gateway_msg": "",
"amount": 25,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1111",
"transaction_datetime": "2014-06-23 22:48:20",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 1
},
{
"transaction_id": 2,
"gateway_id": 101,
"currency_id": 1,
"gateway_status": 1,
"gateway_transid": "*TEST CC* Mon, 23 Jun 2014 22:50:48 -0500",
"gateway_msg": "",
"amount": 75,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1427",
"transaction_datetime": "2014-06-23 22:50:48",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 2
},
...
]
}Available query parameters:
| Attribute | Type | Description | |
|---|---|---|---|
| transaction_id | integer | Transaction ID # | 📎 |
| customer_id | integer | Customer ID # | 📎 |
| brand_id | integer | Brand ID # | 📎 |
| gateway_id | integer | Payment gateway ID # | 📎 |
| gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
| gateway_transid | string | Payment gateway transaction identifier | 📎 |
| gateway_method | string | Payment gateway method | 📎 |
| gateway_msg | string | An error message or note from the payment gateway | 📎 |
| gateway_err_code | integer | 📎 | |
| gateway_err_detail | string | 📎 | |
| gateway_opts | mixed | 📎 | |
| token | string | A unique token for the transaction | 📎 |
| external_key | string | Transaction external key value | 📎 |
| currency_id | integer | Currency ID # | 📎 |
| currency_iso4217 | string | Currency ISO 4217 code | 📎 |
| currency_symbol | string | Currency symbol | 📎 |
| amount | float | Total transaction amount (refunds will be negative) | 📎 |
| fee | float | Transaction fee (if gateway provides this data) | 📎 |
| applied | float | Amount that is applied to invoices | 📎 |
| unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 |
| transaction_date | date | Date of the transaction | 📎 |
| transaction_status_name | string | Human-friendly transaction status | 📎 |
| transaction_status_str | string | Status string | 📎 |
| transaction_status_state | string | State code | 📎 |
| transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
| transaction_type_name | string | Transaction type name | 📎 |
| transaction_method | string | Transaction method | 📎 |
| transaction_detail | string | Transaction details |