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.

  1. Log in to ChargeOver, and click the settings gear/cog in the top right
  2. Choose "Developer" from the left-side navigation menu
  3. Choose "REST API"
  4. Enable the API, and copy your API credentials and API endpoint
  5. 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:

Authentication

Getting started

First follow the steps outlined below:

Once you have a copy of your API Credentials, you are ready to supply it to an API platform (Postman, Insomnia, etc.)

Video walkthrough on how to obtain your API credentials:

Authentication

API Examples

// Username
PjID8u5VOCfJk3iYKzTMo7emstRLnEp9

// Password
xgEWspuItV7A2D6miwZFk94dTrBLSKQO
 

Postman

Configuring Postman to use your REST API credentials

  1. Open the Postman application
  2. Click on the "Collections" tab
  3. Click on the "+" to create a new Collection
  4. Add a request to the collection
  5. Click on the "Authorization" tab
  6. Select "Basic Auth" from the "Type" dropdown
  7. Input your API credentials (obtained previously from the steps above)
  8. Click on "Save" to save your API credentials to Postman

You are now ready to send API requests via Postman.

Postman

Insomnia

Configuring Insomnia to use your REST API credentials

  1. Open the Insomnia application
  2. On the "Auth" tab, click the dropdown arrow
  3. Select "Basic Auth"
  4. Input your API credentials (obtained previously from the steps above)

You are now ready to send API requests via Insomnia.

Insomnia

cURL

Sending basic auth credentials using cURL

  1. Open the Terminal application
  2. Type curl -u username:password https://CHANGE-THIS.chargeover.com/api/v3/CHANGE-THIS
    (substitute your own credentials/URL into the above string!)
  3. Hit the "Return" key on your keyboard

cURL

API Examples

// Get the Teapot response
curl -u PjID8u5VOCfJk3iYKzTMo7emstRLnEp9:xgEWspuItV7A2D6miwZFk94dTrBLSKQO https://dev1.chargeover.test/api/v3/teapot
 

API Response

{
	"code": 418,
	"status": "Teapot",
	"message": "The requested entity body is short and stout.",
	"details": {},
	"response": false
}

Header

Sending basic auth credentials using cURL PHP

An example is provided below:

$username = 'PjID8u5VOCfJk3iYKzTMo7emstRLnEp9';
$password = 'xgEWspuItV7A2D6miwZFk94dTrBLSKQO';

$curl = curl_init('https://CHANGE-THIS.chargeover.com/api/v3/teapot');

curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);

curl_exec($curl);
curl_close($curl);

Header

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."

Make note of the maximum number of records you can retrieve per page!


  • 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 500. You will not be able to retrieve more than 500 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
}

Object Revisions

You can get a list of revision overview details by using the /_revision endpoints.

Object Revisions

Refer to the examples on the right.

To get the recent revisions of objects within ChargeOver, add /_revision to the endpoint.

You can also limit the number of records to the most recent revisions by including ?limit=5 as a query parameter. You can only limit the number of returned records by 1-10.

Object Revisions

API Examples

// Get the most recent 10 revisions of a customer
GET /API/v3/customer/100/_revision

// Get the most recent x number of revisions for a customer (max 10)
GET /API/v3/customer/100/_revision?limit=5
 

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"response": [
		{
			"context_str": "customer",
			"context_id": 100,
			"admin_id": 1,
			"admin_name": "Paul Rossmann",
			"user_id": null,
			"user_name": null,
			"integration_id": null,
			"revision_datetime": "2023-03-03 10:36:22",
			"revision_ipaddr": "169.0.0.1",
			"revision_note": "Customer updated"
		},
		{
			"context_str": "customer",
			"context_id": 100,
			"admin_id": 1,
			"admin_name": "Paul Rossmann",
			"user_id": null,
			"user_name": null,
			"integration_id": null,
			"revision_datetime": "2023-03-03 09:56:17",
			"revision_ipaddr": "169.0.0.1",
			"revision_note": "Customer created"
		}
	]
}

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 ...
}
 

Dates and Times

ChargeOver returns datetime fields in ISO 8601 format.

For example, October 25th, 2022 at 8:50am Central Time is represented as:

    2022-10-25T08:50:45-05:00

Generally, the timestamps returned will be in America/Chicago timezone.

When sending date or datetime values to ChargeOver, you send dates in a few formats:

  • YYYY-MM-DD - a date, example: 2022-10-25
  • YYYY-MM-DD HH:II:SS - a date/time, example: 2022-10-25 08:50:00
  • YYYY-MM-DDTHH:II:SS-Z - a date/time with a timezone, example: 2022-10-25T08:50:45-05:00

Note: The date/time format and timezone returned by ChargeOver is configurable, so your ChargeOver account may return dates/times in an alternative format or timezone.

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
                }
            }
        ]
    }
}

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.

Code / Libraries

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

C# (C Sharp .NET)

Find C# (C Sharp .NET) examples on GitHub:

Java

Find Java examples on GitHub:

PHP

Find PHP examples on GitHub:

Python

Find Python examples on GitHub:

Ruby

Find Ruby examples on GitHub:

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 📎
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 # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
no_latefees boolean Flag to disable late fees 📎
no_procfees boolean Flag to disable processing fees 📎
invoice_delivery enum[print,email] Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum[print,email] 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  
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 # 📎
class_id integer Default class tracking ID # 📎
admin_id integer Admin/Worker ID # 📎
campaign_id integer Campaign/lead source ID # 📎
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 # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
no_latefees boolean Flag to disable late fees 📎
no_procfees boolean Flag to disable processing fees 📎
invoice_delivery enum[print,email] Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum[print,email] 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 # 📎
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 📎
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 their 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 integer 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) 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
no_latefees boolean Flag to disable late fees 📎
no_procfees boolean Flag to disable processing fees 📎
invoice_delivery enum[print,email] Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum[print,email] Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎
tax_ident string Tax ID #/VAT # 📎
total float The sum total amount of all invoices ever issued to this customer (lifetime value) 📎
balance float Balance due for this customer 📎
paid float The lifetime net total payments minus refunds this customer has made 📎
mrr float Current monthly recurring revenue of the customer 📎
arr float Current annual recurring revenue of the customer 📎

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
  • write_datetime - date/time created
  • mod_datetime - date/time last modified
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 # 📎
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 📎
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 their 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 integer 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) 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
no_latefees boolean Flag to disable late fees 📎
no_procfees boolean Flag to disable processing fees 📎
invoice_delivery enum[print,email] Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum[print,email] Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎
tax_ident string Tax ID #/VAT # 📎
total float The sum total amount of all invoices ever issued to this customer (lifetime value) 📎
balance float Balance due for this customer 📎
paid float The lifetime net total payments minus refunds this customer has made 📎
mrr float Current monthly recurring revenue of the customer 📎
arr float Current annual recurring revenue of the customer 📎

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 # 📎
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 📎
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 their 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 integer 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) 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
no_latefees boolean Flag to disable late fees 📎
no_procfees boolean Flag to disable processing fees 📎
invoice_delivery enum[print,email] Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum[print,email] Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎
tax_ident string Tax ID #/VAT # 📎
total float The sum total amount of all invoices ever issued to this customer (lifetime value) 📎
balance float Balance due for this customer 📎
paid float The lifetime net total payments minus refunds this customer has made 📎
mrr float Current monthly recurring revenue of the customer 📎
arr float Current annual recurring revenue of the customer 📎
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

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.

By default when the user is logged in, they will be dropped on the home page. You can optionally specify a destination attribute to send them to a specific page of the portal after login.

Possible values for destination:

  • subscriptions (for the list of subscriptions)
  • invoices (for the list of invoices)
  • payments (for the list of payments)
  • info (for the "My Info" page with the company/name/phone/etc.)
  • paymethods (for the "Payment Methods" tab with credit card info, etc.)
  • paymethods-creditcard (the "Payment Methods" tab, and prompt the user to save a new credit card)
  • paymethods-ach (the "Payment Methods" tab, and prompt the user to save a new bank account)
  • password (for the "Change My Password" tab)

Log in a user

API Request

POST /api/v3/user/389?action=getLoginURL
 
{
    "_comment": "This JSON payload is optional. If you do NOT specify a 'destination' attribute, the user will be dropped on the home page.",
    "destination": "home"
}

API Response

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

Delete a contact

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 # 📎
paycycle string Payment cycle 📎
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
paycycle string Payment cycle
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
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
tags array A list of tags 📎

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 📎
paycycle string Payment cycle 📎
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
paycycle string Payment cycle
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
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
tags array A list of tags 📎

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 📎
mod_datetime datetime Date/time this subscription was last updated 📎
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 📎
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 📎

Get a list of invoices

API Request

GET /api/v3/invoice
 

API Response

{
    "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
        }
    ]
}

Get a specific invoice

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 📎
mod_datetime datetime Date/time this subscription was last updated 📎
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 📎
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  
line_item_id integer Invoice line ID #
invoice_id integer Invoice ID #
admin_id integer Admin worker/sales rep ID #
item_id integer Item ID # for this line
item_name string Item name
item_accounting_sku string Item accounting SKU
item_external_key string Item external key
item_token string Item token
item_units string Item units
paycycle string Payment cycle
tierset_id integer Tierset ID # for this line
package_line_id integer Package line ID # that this line originated from
package_line_external_key string Subscription line external key
package_obligation_id int The contractual obligation this line counted towards
package_line_first_obligation_id int The ID # of the first contractual obligation for the subscription line that this line originated from
descrip string Description
line_prorate float If the line is prorated this value is the prorated percentage
line_rate float Rate
line_quantity float Quantity
line_usage float Usage value
line_subtotal float Line subtotal
line_total float Line total
usage_from float
usage_to float
number_of_recurs_this integer # of times this has recurred since the last up/downgrade
number_of_recurs_line integer # of times this line has recurred
tax_taxable float The total amount that was taxable
tax_taxed float The amount that tax was calculated from
tax_total float The tax amount for this line
tax_id string
tax_group_id string
tax_name string
tax_group_name string
is_usage bool Whether or not this line item was created from usage data
is_setup bool Whether or not this line was a one-time setup fee
is_base bool Whether or not this line is the base line item for other tiered/volume/unit lines
is_free bool Whether or not this line item was free (equal to $0.00)
is_recurring bool Whether or not this line is recurring
is_taxed bool Whether or not this line item was taxed/subject to VAT
is_latefee bool Whether or not this line item was a late fee
is_obligation bool Whether or not this line item was towards a contractual obligation
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
schedule - array

A list of scheduled payments for this invoice
Attribute Type Description  
invoice_schedule_id integer Scheduled ID #
invoice_id integer Invoice ID #
token string A unique token to identify this scheduled event
paymethod string The payment method (crd for credit card, ach for ACH/eCheck, inv for just sending an invoice
creditcard_id integer If the payment is scheduled against a credit card, the creditcard_id value
ach_id integer If a bank account payment, the ach_id value
tokenized_id integer If a tokenized payment method, the tokenized_id value
due_date date Payment due date
days_overdue integer Number of days overdue
amount float Amount to schedule payment for
amount_or_percent_formatted string A pretty-formatted amount or percent that was scheduled
balance float Balance (amount due) of this payment
date date Date to run the payment on
url_paylink string URL to pay for this scheduled payment
url_ttl_paylink string URL to pay for this scheduled payment
tags array A list of tags 📎

Get a specific invoice

API Request

GET /api/v3/invoice/98165
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "invoice_id": 98165,
        "currency_id": 1,
        "brand_id": 1,
        "terms_id": 2,
        "admin_id": 1,
        "external_key": null,
        "token": "1tslo5m9h51b",
        "refnumber": "98165",
        "cycle_pre_from_date": null,
        "cycle_pre_to_date": null,
        "cycle_this_date": null,
        "cycle_post_from_date": null,
        "cycle_post_to_date": null,
        "bill_addr1": "56 Cowles",
        "bill_addr2": "Suite 620",
        "bill_addr3": "",
        "bill_city": "Minneapolis",
        "bill_state": "MN",
        "bill_postcode": "55416",
        "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": "2019-09-26 10:16:43",
        "void_datetime": null,
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "admin_name": "ChargeOver Support",
        "invoice_status_name": "Unpaid",
        "invoice_status_str": "open-unpaid",
        "invoice_status_state": "o",
        "subtotal": 100,
        "total": 100,
        "taxes": 0,
        "credits": 0,
        "payments": 35,
        "writeoffs": 0,
        "declines": 0,
        "applied": 35,
        "sum_base": 0,
        "sum_usage": 0,
        "sum_onetime": 100,
        "is_paid": false,
        "paid_date": null,
        "balance": 65,
        "is_void": false,
        "due_date": "2019-12-20",
        "terms_name": "Net 30",
        "terms_days": 30,
        "days_overdue": 0,
        "is_overdue": false,
        "date": "2019-09-26",
        "bill_block": "56 Cowles\r\nSuite 620\r\nMinneapolis, MN 55416\r\nUnited States",
        "ship_block": "",
        "url_permalink": "https:\/\/example.chargeover.com\/r\/invoice\/view\/1tslo5m9h51b",
        "url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/pay\/1tslo5m9h51b",
        "url_pdflink": "https:\/\/example.chargeover.com\/r\/invoice\/pdf\/1tslo5m9h51b",
        "url_self": "https:\/\/example.chargeover.com\/admin\/r\/invoice\/view\/98165",
        "package_id": null,
        "customer_id": 3488,
        "line_items": [
            {
                "invoice_id": 98165,
                "item_id": 29,
                "tierset_id": null,
                "admin_id": null,
                "descrip": "1-month subscription to gold plan.",
                "line_rate": 100,
                "line_quantity": 1,
                "line_prorate": 1,
                "line_usage": 0,
                "usage_from": 0,
                "usage_to": 0,
                "tax_id": null,
                "tax_group_id": null,
                "tax_taxable": 100,
                "tax_taxed": 0,
                "tax_total": 0,
                "is_base": false,
                "is_free": false,
                "is_setup": false,
                "is_usage": false,
                "is_recurring": false,
                "is_latefee": false,
                "is_taxed": false,
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "custom_4": null,
                "custom_5": null,
                "item_name": "Gold Plan",
                "item_external_key": null,
                "item_token": "1kzl806611h1",
                "item_accounting_sku": null,
                "item_units": null,
                "tax_name": null,
                "tax_group_name": null,
                "line_subtotal": 100,
                "line_total": 100,
                "line_item_id": 234,
                "package_line_id": null,
                "package_line_external_key": null
            }
        ],
        "sent": [],
        "schedule": [
            {
                "invoice_schedule_id": 13,
                "invoice_id": 98165,
                "token": "199m59nc2k1p",
                "paymethod": "inv",
                "creditcard_id": null,
                "ach_id": null,
                "url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/sch\/1tslo5m9h51b\/199m59nc2k1p",
                "amount": 10,
                "balance": 0,
                "amount_or_percent_formatted": "$ 10.00",
                "date": "2019-09-30"
            },
            {
                "invoice_schedule_id": 16,
                "invoice_id": 98165,
                "token": "19nvqp56y146",
                "paymethod": "ach",
                "creditcard_id": null,
                "ach_id": 8,
                "url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/sch\/1tslo5m9h51b\/19nvqp56y146",
                "amount": 25,
                "balance": 25,
                "amount_or_percent_formatted": "25%",
                "date": "2019-11-20"
            }
        ]
    }
}

Query for invoices

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
  • quote.quote_id - Get the invoice that originated from a specific quote
  • write_datetime - date/time created
  • mod_datetime - date/time last modified

Valid values for invoice_status_str:

  • open-unpaid
  • open-overdue
  • open-collections
  • closed-void
  • closed-paid

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.

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 📎
mod_datetime datetime Date/time this subscription was last updated 📎
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 📎
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 📎

Query for invoices

API Request

GET /api/v3/invoice?where=customer_id:EQUALS:1,invoice_status_state:EQUALS:o&limit=1000 HTTP/1.1
 

API Response

{
    "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": "https:\/\/dev.chargeover.com\/r\/invoice\/view\/i17fq4huy2ar",
            "url_pdflink": "https:\/\/dev.chargeover.com\/r\/invoice\/pdf\/i17fq4huy2ar",
            "customer_id": "1"
        }
    ]
}

Add a late fee to an invoice

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.

Add a late fee to an invoice

API Request

POST /api/v3/invoice/11063?action=latefee
 

API Response

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

Scheduling payments for invoices

ChargeOver allows you to schedule a full payment or several partial payments to invoices via the REST API. You must specify the amount and date of the payment.

For invoices created from a subscription, the payment method used is always the payment method from the subscription itself.

For one-time invoices, you can specify a credit card, bank account, or tokenized payment method to be used for the payment by providing the creditcard_id, ach_id, or tokenized_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, ach to specify the payment method as any of the stored ACH bank accounts the customer has, or tok to specify the payment method as any of the stored tokenized payment methods the customer has.

Scheduling payments for invoices

API Request

POST /api/v3/invoice/5052?action=schedule
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
 
{
    "schedule": [
        {
            "_comment": "You can specify a specific creditcard or ach to use as the payment method:",
            "amount": 50,
            "date": "2021-10-20",
            "creditcard_id": 9
        },
        {
            "_comment": "To schedule with ANY payment method the customer has on file:",
            "amount": 10,
            "date": "2021-11-28",
            "paymethod": "any"
        },
        {
            "_comment": "To schedule the payment(s) with ANY CREDITCARD the customer has on file:",
            "amount": 10,
            "date": "2021-12-28",
            "paymethod": "crd"
        },
        {
            "_comment": "To schedule the payment(s) with ANY ACH the customer has on file:",
            "amount": 10,
            "date": "2022-01-28",
            "paymethod": "ach"
        }
    ]
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Removing scheduled payments from invoices

This will remove all scheduled payments from a specific invoice.

Removing scheduled payments from invoices

API Request

POST /api/v3/invoice/10154?action=unschedule
 

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Set the payment method for an invoice

Set the payment method for an invoice.

  • If the invoice was created from a subscription, this updates the subscription payment method.
  • If the invoice has scheduled payments attached, this updates the payment method for the attached scheduled payments.
  • If the invoice is not from an invoice, and has no attached scheduled payments, this method does nothing.

If you want to remove any payment methods from the scheduled payments/subscription, you can set a payment method of paymethod: "inv".

Set the payment method for an invoice

API Request

POST /api/v3/invoice/1260?action=setPayMethod
Content-Type: application/json
 
{
    "_comment": "Specify a paymethod of: crd, ach, tok, inv",
    "paymethod": "crd",
    "creditcard_id": 59
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Overriding tax calculations on an invoice

This allows you to override the tax configurations in your account and specify a specific tax amount to charge when creating an invoice.

Overriding tax calculations on an invoice

API Request

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"
        }
    ]
}

API Response

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

Credit card payment (specify card details)

Credit card payment (specify card details)

API Request

POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
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"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

ACH/eCheck payment (specify ACH details)

ACH/eCheck payment (specify ACH details)

API Request

POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "number": "1234-1234-1234",
    "routing": "072403004",
    "name": "Keith Palmer",
    "type": "chec"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Apply an open customer balance

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.

Apply an open customer balance

API Request

POST /api/v3/invoice/10006?action=pay
 
{
    "use_customer_balance": true
}

API Response

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

Void an invoice

Voiding an invoice effectively makes the total due/balance zero, and will halt all dunning attempts/payments against this invoice.

Void an invoice

API Request

POST /api/v3/invoice/13011?action=void
 

API Response

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

Email 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.

Email an invoice

API Request

POST /api/v3/invoice/13011?action=email
Content-Type: application/json
 
{
    "_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
    "email": "to@example.com",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com",
    "subject": "Override the default subject",
    "body": "Override the default plain-text body of the email",
    "html": "Override the default <b>HTML body<\/b> of the email",
    "from": "\"Example Company\" <from@example.com>",
    "_comment_message_id": "If you wish to use an existing template other than the default, specify the message_id of the template:",
    "message_id": 1
}

API Response

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

Transactions (Payments, Refunds, Credits)

Pay with credit card

Attempt to make a payment for a customer, using a credit card.

If you specify one or more paymethods then those specific payment methods will be used. If you do not specify, then:

  • If the invoice is from a subscription, the payment method for the subscription will be tried.
  • Otherwise, if the customer has a default payment method specified, the default payment method will be tried.
  • Otherwise, all payment methods for the customer will be tried.

Alternatively, you can specify an existing creditcard_id or ach_id within paymethods if you wish to attempt the transaction on an existing pay method.

Valid paymethods values:

  • New credit card
  • New ACH
  • Existing creditcard_id
  • Existing ach_id

The returned id value will be the transaction_id value of the resulting transaction.

Requirements

  • You must specify an existing customer_id, customer_token, or customer_external_key.
  • You must specify either an amount or at least one invoice_id to pay.

Pay with credit card

API Request

POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 4130,
    "_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
    "amount": 15.95,
    "applied_to": [
        {
            "invoice_id": 16891
        }
    ],
    "paymethods": [
        {
            "_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
            "creditcard_id": 1234
        },
        {
            "_comment": "... or the full credit card details...",
            "number": "4111 1111 1111 1111",
            "expdate_year": "2025",
            "expdate_month": "09",
            "cvv": "123"
        }
    ]
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {
        "transaction_id": 326,
        "gateway_status": 1,
        "gateway_err_code": 0,
        "gateway_err_detail": null,
        "gateway_msg": "",
        "creditcard_id": 1234
    },
    "response": {
        "id": 326
    }
}

Pay with bank account

Attempt to make a payment for a customer, using a bank account (ACH/direct debit/PAD).

Note that bank account payments (ACH/direct debit/PAD) do not return a real-time response from the bank. Payments will go to a "Pending" status, and take an average of 2-5 business days to settle (or be returned by the bank), at which time the status will update to either "Success" or "Failed (decline)".

If you specify one or more paymethods then those specific payment methods will be used. If you do not specify, then:

  • If the invoice is from a subscription, the payment method for the subscription will be tried.
  • Otherwise, if the customer has a default payment method specified, the default payment method will be tried.
  • Otherwise, all payment methods for the customer will be tried.

Alternatively, you can specify an existing creditcard_id or ach_id within paymethods if you wish to attempt the transaction on an existing pay method.

Valid paymethods values:

  • New credit card
  • New ACH
  • Existing creditcard_id
  • Existing ach_id

The returned id value will be the transaction_id value of the resulting transaction.

Requirements

  • You must specify an existing customer_id, customer_token, or customer_external_key.
  • You must specify either an amount or at least one invoice_id to pay.

Pay with bank account

API Request

POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 4130,
    "_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
    "amount": 15.95,
    "applied_to": [
        {
            "invoice_id": 16891
        }
    ],
    "paymethods": [
        {
            "_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
            "ach_id": 1234
        },
        {
            "_comment": "... or full ACH\/bank account details.",
            "type": "chec",
            "number": "856667",
            "routing": "072403004",
            "name": "Jane Doe"
        }
    ]
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {
        "transaction_id": 327,
        "gateway_status": 1,
        "gateway_err_code": 0,
        "gateway_err_detail": null,
        "gateway_msg": "",
        "ach_id": 1234
    },
    "response": {
        "id": 327
    }
}

Pay against a schedule / installment

Attempt to make a payment for a customer, against a scheduled payment or installment.

If you are using ChargeOver's scheduled payments features (scheduling payments or installments against an invoice) then you can take payments using the API, against a particular scheduled payment.

You will specify the invoice_schedule_id of the scheduled payment you want to pay against, along with the amount of the payment to apply to that scheduled payment.

Pay against a schedule / installment

API Request

POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 4130,
    "_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
    "amount": 15.95,
    "applied_to": [
        {
            "invoice_id": 16891,
            "invoice_schedule_id": 79,
            "applied": 15.95
        }
    ],
    "paymethods": [
        {
            "_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
            "creditcard_id": 1234
        },
        {
            "_comment": "... or the full credit card details...",
            "number": "4111 1111 1111 1111",
            "expdate_year": "2025",
            "expdate_month": "09",
            "cvv": "123"
        },
        {
            "_comment": "... or full ACH\/bank account details.",
            "type": "chec",
            "number": "856667",
            "routing": "072403004",
            "name": "Jane Doe"
        }
    ]
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {
        "transaction_id": 326,
        "gateway_status": 1,
        "gateway_err_code": 0,
        "gateway_err_detail": null,
        "gateway_msg": "",
        "creditcard_id": 92
    },
    "response": {
        "id": 326
    }
}

Create a Credit Memo

Create a credit memo for a customer.

Notes:

  • The transaction_type value MUST be "cre"
  • The gateway_method value MUST be "credit"
  • The gateway_status value should be either 1 (to indicate the payment was successful) or 0 (zero, to log a payment that failed/was declined)

Object Attributes

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 A customer-facing error message indicating why the transaction declined/failed 📎
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 📎
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 📎
memo string Transaction memo 📎

Create a Credit Memo

API Request

POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
	"customer_id": 1,
	"gateway_id": 1,
	"gateway_status": 1,
	"gateway_transid": "abcd1234",
	"gateway_msg": "test gateway message",
	"gateway_method": "credit",
	"amount": 15.95,
	"transaction_type": "cre",
	"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",
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/transaction/2367
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 2367
    }
}

Record offline payment

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:

  • The transaction_type value MUST be “pay”
  • The gateway_status value should be either 1 (to indicate the payment was successful) or 0 (zero, to log a payment that failed/was declined)
  • The gateway_method value MUST be one of: visa, mastercard, american-express, discover, check, paypal, credit, ach

Object Attributes

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 A customer-facing error message indicating why the transaction declined/failed 📎
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 📎
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 📎
memo string Transaction memo 📎

Record offline payment

API Request

POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
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", 
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/transaction/2367
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 2367
    }
}

Get a specific transaction

Getting a transaction (a payment, refund, credit, etc.) gives you the full transaction details.

A couple of notes about some specific attributes returned:

  • applied_to - if the payment is applied to any invoices, a list of invoices and the amount of the payment applied will be listed here
  • refunds - for payments, if any portion of the payment was refunded, a list of related refund transaction_id values will be here
  • payments - for refunds, the original payment transaction_id value will be here

Object Attributes

Attribute Type Description  
transaction_id integer Transaction ID # 📎
parent_transaction_id integer Parent transaction ID # 📎
transaction_batch_id integer Transaction batch ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_type string Payment gateway type 📎
gateway_nickname string Nickname for the payment gateway 📎
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 A customer-facing error message indicating why the transaction declined/failed 📎
gateway_err_code integer A merchant-facing specific error code indicating why the transaction declined/failed 📎
gateway_err_detail string A merchant-facing detailed error message indicating why the transaction declined/failed 📎
gateway_opts mixed Additional gateway-specific data 📎
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 📎
applied_to - array

Information about how the payment is applied
Attribute Type Description  
transaction_applied_id integer Line item ID #
transaction_id integer Transaction ID #
invoice_id integer Invoice ID #
invoice_schedule_id integer Invoice schedule ID #
applied float Amount applied to the invoice
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 📎
memo string Transaction memo 📎

Get a specific transaction

API Request

GET /api/v3/transaction/92
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeX...
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "transaction_id": 43,
        "gateway_id": 201,
        "currency_id": 1,
        "external_key": null,
        "token": "185g5984n91k",
        "transaction_date": "2019-07-24",
        "gateway_status": 1,
        "gateway_transid": "1563978556",
        "gateway_msg": "",
        "gateway_err_code": 0,
        "gateway_err_detail": null,
        "gateway_opts": {
            "time_stamp": "Wed, 24 Jul 2019 09:29:16 -0500",
            "auth_code": "ABC123"
        },
        "gateway_method": "visa",
        "amount": 75,
        "fee": 0,
        "transaction_type": "pay",
        "transaction_method": "Visa",
        "transaction_detail": "x1111",
        "transaction_datetime": "2019-07-24 09:29:16",
        "transaction_ipaddr": "10.80.1.1",
        "void_datetime": null,
        "transaction_status_name": "Success",
        "transaction_status_str": "ok-successful",
        "transaction_status_state": "o",
        "transaction_type_name": "Payment",
        "applied": 75,
        "brand_id": 1,
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "url_self": "https:\/\/dev1.chargeover.com\/admin\/r\/transaction\/view\/43",
        "customer_id": 48,
        "unapplied": 0,
        "applied_to": [
            {
                "invoice_id": 1027,
                "applied": 75
            }
        ],
        "refunds": [
            {
                "transaction_id": 44
            }
        ]
    }
}

List transactions

Object Attributes

Attribute Type Description  
transaction_id integer Transaction ID # 📎
parent_transaction_id integer Parent transaction ID # 📎
transaction_batch_id integer Transaction batch ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_type string Payment gateway type 📎
gateway_nickname string Nickname for the payment gateway 📎
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 A customer-facing error message indicating why the transaction declined/failed 📎
gateway_err_code integer A merchant-facing specific error code indicating why the transaction declined/failed 📎
gateway_err_detail string A merchant-facing detailed error message indicating why the transaction declined/failed 📎
gateway_opts mixed Additional gateway-specific data 📎
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 📎
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 📎
memo string Transaction memo 📎

List transactions

API Request

GET /api/v3/transaction
 

API Response

{
    "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
        },
        ...
    ]
}

Query for transactions

Available query parameters:

  • transaction_id
  • customer_id
  • gateway_id
  • currency_id
  • creditcard_id
  • ach_id
  • tokenized_id
  • token
  • external_key
  • gateway_status
  • gateway_transid
  • amount
  • fee
  • transaction_type
  • transaction_method
  • transaction_detail
  • transaction_datetime
  • transaction_status.state
  • transaction_status.str
  • applied_to.package_id (this will find transactions that are applied to invoices from a specific package)
  • applied_to.package_external_key (this will find transactions that are applied to invoices from a specific package)
  • applied_to.invoice_id (this will find transactions that are applied to a particular invoice)

Object Attributes

Attribute Type Description  
transaction_id integer Transaction ID # 📎
parent_transaction_id integer Parent transaction ID # 📎
transaction_batch_id integer Transaction batch ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_type string Payment gateway type 📎
gateway_nickname string Nickname for the payment gateway 📎
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 A customer-facing error message indicating why the transaction declined/failed 📎
gateway_err_code integer A merchant-facing specific error code indicating why the transaction declined/failed 📎
gateway_err_detail string A merchant-facing detailed error message indicating why the transaction declined/failed 📎
gateway_opts mixed Additional gateway-specific data 📎
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 📎
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 📎
memo string Transaction memo 📎

Query for transactions

API Request

GET /api/v3/transaction?where=transaction_type:EQUALS:pay
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "transaction_id": 65,
            "gateway_id": 201,
            "currency_id": 1,
            "token": "6by30nr7dxlh",
            "transaction_date": "2015-02-16",
            "gateway_status": 1,
            "gateway_transid": "*TEST CC* Mon, 16 Feb 2015 16:29:13 -0500",
            "gateway_msg": "",
            "amount": 10.95,
            "fee": -0.33,
            "transaction_type": "pay",
            "transaction_method": "Visa",
            "transaction_detail": "x1111",
            "transaction_datetime": "2015-02-16 20:29:13",
            "void_datetime": null,
            "transaction_type_name": "Payment",
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "customer_id": 1
        },
        {
            "transaction_id": 66,
            "gateway_id": 202,
            "currency_id": 1,
            "token": "flsxubzeao0t",
            "transaction_date": "2015-02-20",
            "gateway_status": 0,
            "gateway_transid": null,
            "gateway_msg": "-",
            "amount": 25.95,
            "fee": 0,
            "transaction_type": "pay",
            "transaction_method": "Visa",
            "transaction_detail": "x1111",
            "transaction_datetime": "2015-02-20 20:20:34",
            "void_datetime": null,
            "transaction_type_name": "Payment",
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "customer_id": 1
        },
    ...

Mark a transaction declined

If ChargeOver is unable to get informaton back about NSF payments from your ACH payment gateway, you can use this API call to manually mark a transaction as declined via the API.

Optionally, you can specify values for the gateway_msg, gateway_err_code, and gateway_err_detail fields to supply more information about the failed transaction.

For the gateway_msg field, you can put the message from your gateway about why the transaction failed. For instance, if a transaction failed because of insufficient funds, you could put "Insufficient Funds" in for this field.

If you are not sure what error code to use for the gateway_err_code field, you can view our list of payment processor error codes here.

Mark a transaction declined

API Request

POST /api/v3/transaction/869?action=decline
 
{
    "gateway_msg": "Your message here",
    "gateway_err_code": "Error code integer here",
    "gateway_err_detail": "Your message here"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Adjust applied amounts

Use this to adjust how much of a payment or credit is applied to specific invoices, or which invoices a payment or credit is applied to.

On every REST API request, you need to specify all of the invoices the payment is applied to. Any existing applications of the payment will be overwritten by the applications in this REST API request (e.g. if an invoice previously had this payment applied to it, and you don't specify that invoice in this request, the payment application will be removed from that invoice).

To unapply the payment entirely, specify an empty `applied_to` array.

Note: You can only adjust how payments and credits are applied.

Adjust applied amounts

API Request

POST /api/v3/transaction/68?action=changeAppliedAmounts HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "applied_to": [
        {
            "invoice_id": 1274,
            "applied": 10
        },
        {
            "invoice_id": 1287,
            "applied": 2.9
        }
    ]
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Void a transaction

Voiding a transaction through ChargeOver's API is for logging externally-voided transactions. Note that voiding a transaction through the API does not reach out to any payment gateways or credit card processors.

Void a transaction

API Request

POST /api/v3/transaction/13012?action=void
 

API Response

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

Email a receipt

Send a payment receipt, or payment failure notification, 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.

Email a receipt

API Request

POST /api/v3/transaction/65?action=email
Content-Type: application/json
 
{
    "_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
    "email": "to@example.com",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com",
    "subject": "Override the default subject",
    "body": "Override the default plain-text body of the email",
    "html": "Override the default <b>HTML body<\/b> of the email",
    "from": "\"Example Company\" <from@example.com>",
    "_comment_message_id": "You can optionally specify a message_id value to use a specific email template.",
    "message_id": 2
}

API Response

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

Quotes

The primary key field for a quote is quote_id.

Create a quote

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.
  • You must specify a paycycle:
    • one - a quote for a one-time invoice
    • mon - a quote for a monthly subscription
    • 2mn - a quote for a subscription that invoices the customer every 2 months
    • yrl - a quote for a yearly subscription
    • 2yr - a quote for a subscription that invoices the customer every 2 years
    • 3yr - a quote for a subscription that invoices the customer every 3 years
    • 1wk - a quote for a weekly subscription
    • 2wk - a quote for a subscription that invoices the customer every 2 weeks
    • qtr - a quote for a quarterly subscription
    • six - a quote for a subscription that invoices customers every 6 months
Notes
  • The id value in the response is the quote_id value of the newly created quote.
  • The "Location:" header will provide a direct API link to the newly created quote.

Object Attributes

Attribute Type Description  
refnumber string Quote reference number 📎
external_key string External key value 📎
paycycle string Payment cycle for the quote (e.g. monthly, etc.) 📎
nickname string Quote nickname 📎
customer_id integer Customer ID # 📎
date date Quote date 📎
validuntil_date date Quote valid until 📎
holduntil_datetime_str string Date/time invoicing for the resulting subscription to be delayed until 📎
currency_id integer Currency ID # 📎
terms_id integer Terms ID # 📎
class_id integer Class ID # for Quickbooks 📎
brand_id integer Brand 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) 📎
url_acceptredirect string URL the lead should be redirected to after accepting a quote 📎
url_rejectredirect string URL the lead should be redirected to after rejecting a quote 📎
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 quote
Attribute Type Description  
item_id integer Item ID # for this line
descrip string Description
line_rate float (Deprecated - see the "tierset" attribute)
line_quantity float Quantity
expire_recurs integer # of invoices to occur on before expiring
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
subscribe_prorate_from_datetime datetime
subscribe_prorate_to_datetime datetime
tierset array Pricing information

Create a quote

API Request

POST /api/v3/quote
Content-Type: application/json
 
{
    "customer_id": 5,
    "paycycle": "mon",
    "line_items": [
        {
            "item_id": 1,
            "descrip": "Here is a description for my line item.",
            "line_quantity": 15
        },
        {
            "item_id": 1,
            "descrip": "Here is a description for my line item.",
            "line_quantity": 15,
            "tierset": {
                "pricemodel": "fla",
                "base": 10.95,
                "setup": 199.99
            }
        }
    ]
}

API Response

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.chargeover.com/api/v3/quote/199
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 199
    }
}

Update a quote

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  
refnumber string Quote reference number 📎
external_key string External key value 📎
paycycle string Payment cycle for the quote (e.g. monthly, etc.) 📎
nickname string Quote nickname 📎
holduntil_datetime_str string Date/time invoicing for the resulting subscription to be delayed until 📎
terms_id integer Terms ID # 📎
class_id integer Class ID # for Quickbooks 📎
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 quote
Attribute Type Description  
item_id integer Item ID # for this line
descrip string Description
line_rate float (Deprecated - see the "tierset" attribute)
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
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
tierset array Pricing information

Update a quote

API Request

PUT /api/v3/quote/199
Content-Type: application/json
 
{
    "customer_id": 5,
    "paycycle": "mon",
    "line_items": [
        {
            "_comment": "To update an existing line item, pass it's line_item_id value:",
            "line_item_id": 369,
            "descrip": "Updated description.",
            "line_quantity": 25
        },
        {
            "_comment": "Custom pricing can be specified via the tierset attribute:",
            "item_id": 1,
            "line_quantity": 1,
            "tierset": {
                "pricemodel": "fla",
                "base": 10.95,
                "setup": 199.99
            }
        }
    ]
}

API Response

HTTP/1.1 202 Accepted
Content-Type: application/json
 
{
    "code": 202,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 199
    }
}

Get a list of quotes

Returns a list of ALL quotes

Object Attributes

Attribute Type Description  
quote_id integer Quote ID # 📎
refnumber string Quote reference number 📎
external_key string External key value 📎
paycycle string Payment cycle for the quote (e.g. monthly, etc.) 📎
nickname string Quote nickname 📎
customer_id integer Customer ID # 📎
write_datetime datetime Date/time the quote was created 📎
date date Quote date 📎
validuntil_date date Quote valid until 📎
holduntil_datetime_str string Date/time invoicing for the resulting subscription to be delayed until 📎
currency_id integer Currency ID # 📎
currency_symbol string Currency symbol 📎
currency_iso4217 string Currency ISO 4217 representation 📎
terms_id integer Terms ID # 📎
class_id integer Class ID # for Quickbooks 📎
terms_name string Terms name 📎
terms_days integer Terms # of days 📎
brand_id integer Brand ID # 📎
paycycle_name string Payment cycle name 📎
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 📎
url_permalink string URL to view the quote 📎
url_pdflink string URL to get a PDF of the quote 📎
url_self string URL for viewing the quote in the GUI 📎
url_acceptlink string URL to visit to accept the quote 📎
url_paylink string URL to visit to provide a payment method for the quote 📎
url_rejectlink string URL to visit to reject the quote 📎
url_acceptredirect string URL the lead should be redirected to after accepting a quote 📎
url_rejectredirect string URL the lead should be redirected to after rejecting a quote 📎
won_datetime string The Date/time that the quote was accepted 📎
lost_datetime string The Date/time that the quote was rejected 📎
due_date date Date the quote is due 📎
setup float Optional one time free charged for set up expenses 📎
total float Amount due after taxes and fees 📎
upfront float The amount due when you accept the quote  📎
subtotal float Amount due before taxes and fees 📎
taxes float Amount due for taxes 📎
quote_status_name string Human-friendly quote status 📎
quote_status_str string Status string 📎
quote_status_state string Status code 📎
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 📎

Get a list of quotes

API Request

GET /api/v3/quote
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "quote_id": 1,
            "terms_id": 2,
            "admin_id": 1,
            "currency_id": 1,
            "token": "14km8c4v7n06",
            "refnumber": "1",
            "paycycle": "mon",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "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,
            "write_datetime": "2019-07-25 15:58:48",
            "quote_status_name": "Accepted",
            "quote_status_str": "closed-won",
            "quote_status_state": "c",
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "total": 10.95,
            "setup": 0,
            "terms_name": "Net 30",
            "date": "2019-07-25",
            "due_date": "2019-08-24",
            "bill_block": "United States",
            "ship_block": "",
            "url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/14km8c4v7n06",
            "url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/14km8c4v7n06",
            "url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/1",
            "url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/14km8c4v7n06",
            "url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/14km8c4v7n06",
            "customer_id": 2
        },
        {
            "quote_id": 2,
            "terms_id": 2,
            "admin_id": 1,
            "currency_id": 1,
            "token": "5906g19516kf",
            "refnumber": "2",
            "paycycle": "one",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "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,
            "write_datetime": "2019-07-25 16:11:35",
            "quote_status_name": "Accepted",
            "quote_status_str": "closed-won",
            "quote_status_state": "c",
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "total": 10.95,
            "setup": 0,
            "terms_name": "Net 30",
            "date": "2019-07-25",
            "due_date": "2019-08-24",
            "bill_block": "United States",
            "ship_block": "",
            "url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/5906g19516kf",
            "url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/5906g19516kf",
            "url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/2",
            "url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/5906g19516kf",
            "url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/5906g19516kf",
            "customer_id": 2
        }
    ]
}

Query for quotes

Available query parameters:

  • quote_id
  • customer_id
  • brand_id
  • currency_id
  • refnumber
  • token
  • external_key
  • date
  • bill_state
  • ship_state
  • bill_country
  • ship_country
  • quote_status_str
  • quote_status_state

Valid values for quote_status_str:

  • open-new
  • open-sent
  • closed-won
  • closed-lost

Valid values for quote_status_state:

  • o (any “open” quote, i.e. any that have not been accepted or lost)
  • c (any “closed” quote, i.e. any that have been accepted or lost)

By default, only the overview quote details are returned (i.e. no individual line items). If you get a specific quote by quote id value (e.g. GET /api/v3/quote/1234) you'll get back the invoice line items

Object Attributes

Attribute Type Description  
quote_id integer Quote ID # 📎
refnumber string Quote reference number 📎
external_key string External key value 📎
paycycle string Payment cycle for the quote (e.g. monthly, etc.) 📎
nickname string Quote nickname 📎
customer_id integer Customer ID # 📎
write_datetime datetime Date/time the quote was created 📎
date date Quote date 📎
validuntil_date date Quote valid until 📎
holduntil_datetime_str string Date/time invoicing for the resulting subscription to be delayed until 📎
currency_id integer Currency ID # 📎
currency_symbol string Currency symbol 📎
currency_iso4217 string Currency ISO 4217 representation 📎
terms_id integer Terms ID # 📎
class_id integer Class ID # for Quickbooks 📎
terms_name string Terms name 📎
terms_days integer Terms # of days 📎
brand_id integer Brand ID # 📎
paycycle_name string Payment cycle name 📎
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 📎
url_permalink string URL to view the quote 📎
url_pdflink string URL to get a PDF of the quote 📎
url_self string URL for viewing the quote in the GUI 📎
url_acceptlink string URL to visit to accept the quote 📎
url_paylink string URL to visit to provide a payment method for the quote 📎
url_rejectlink string URL to visit to reject the quote 📎
url_acceptredirect string URL the lead should be redirected to after accepting a quote 📎
url_rejectredirect string URL the lead should be redirected to after rejecting a quote 📎
won_datetime string The Date/time that the quote was accepted 📎
lost_datetime string The Date/time that the quote was rejected 📎
due_date date Date the quote is due 📎
setup float Optional one time free charged for set up expenses 📎
total float Amount due after taxes and fees 📎
upfront float The amount due when you accept the quote  📎
subtotal float Amount due before taxes and fees 📎
taxes float Amount due for taxes 📎
quote_status_name string Human-friendly quote status 📎
quote_status_str string Status string 📎
quote_status_state string Status code 📎
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 📎

Query for quotes

API Request

GET /api/v3/quote?where=customer_id:EQUALS:35,quote_status_state:EQUALS:o&limit=1000 HTTP/1.1
 

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"details": {},
	"response": [
		{
			"quote_id": 9,
			"terms_id": 2,
			"admin_id": null,
			"external_key": "a0K3D000001Wv8cUAg",
			"currency_id": 1,
			"token": "i5d57esw422k",
			"refnumber": "9",
			"paycycle": "mon",
			"bill_addr1": null,
			"bill_addr2": null,
			"bill_addr3": null,
			"bill_city": null,
			"bill_state": null,
			"bill_postcode": null,
			"bill_country": 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_notes": null,
			"memo": null,
			"custom_1": null,
			"custom_2": null,
			"custom_3": null,
			"write_datetime": "2020-05-04 17:13:35",
			"quote_status_name": "New",
			"quote_status_str": "open-new",
			"quote_status_state": "o",
			"currency_symbol": "$",
			"currency_iso4217": "USD",
			"total": 100.83,
			"setup": 0,
			"terms_name": "Net 30",
			"date": "2020-05-04",
			"due_date": "2020-06-03",
			"paycycle_name": "Monthly",
			"bill_block": "",
			"ship_block": "",
			"url_permalink": "https://example.chargeover.com/r/quote/view/i5d57esw422k",
			"url_pdflink": "https://example.chargeover.com/r/quote/pdf/i5d57esw422k",
			"url_self": "https://example.chargeover.com/admin/r/quote/view/9",
			"url_acceptlink": "https://example.chargeover.com/r/quote/accept/i5d57esw422k",
			"url_rejectlink": "https://example.chargeover.com/r/quote/reject/i5d57esw422k",
			"customer_id": 35
		}
	]
}

Get a specific quote

If the quote has been turned into an invoice, there will be an invoices attribute which links to the related invoice.

If the quote has been turned into a subscription, there will be a packages attribute which links to the related subscription.

Object Attributes

Attribute Type Description  
quote_id integer Quote ID # 📎
refnumber string Quote reference number 📎
external_key string External key value 📎
paycycle string Payment cycle for the quote (e.g. monthly, etc.) 📎
nickname string Quote nickname 📎
customer_id integer Customer ID # 📎
write_datetime datetime Date/time the quote was created 📎
date date Quote date 📎
validuntil_date date Quote valid until 📎
holduntil_datetime_str string Date/time invoicing for the resulting subscription to be delayed until 📎
currency_id integer Currency ID # 📎
currency_symbol string Currency symbol 📎
currency_iso4217 string Currency ISO 4217 representation 📎
terms_id integer Terms ID # 📎
class_id integer Class ID # for Quickbooks 📎
terms_name string Terms name 📎
terms_days integer Terms # of days 📎
brand_id integer Brand ID # 📎
paycycle_name string Payment cycle name 📎
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 📎
url_permalink string URL to view the quote 📎
url_pdflink string URL to get a PDF of the quote 📎
url_self string URL for viewing the quote in the GUI 📎
url_acceptlink string URL to visit to accept the quote 📎
url_paylink string URL to visit to provide a payment method for the quote 📎
url_rejectlink string URL to visit to reject the quote 📎
url_acceptredirect string URL the lead should be redirected to after accepting a quote 📎
url_rejectredirect string URL the lead should be redirected to after rejecting a quote 📎
won_datetime string The Date/time that the quote was accepted 📎
lost_datetime string The Date/time that the quote was rejected 📎
due_date date Date the quote is due 📎
setup float Optional one time free charged for set up expenses 📎
total float Amount due after taxes and fees 📎
upfront float The amount due when you accept the quote  📎
subtotal float Amount due before taxes and fees 📎
taxes float Amount due for taxes 📎
quote_status_name string Human-friendly quote status 📎
quote_status_str string Status string 📎
quote_status_state string Status code 📎
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 quote
Attribute Type Description  
line_item_id integer Invoice line ID #
quote_id integer Invoice ID #
item_id integer Item ID # for this line
item_name string Item name
item_accounting_sku string Item accounting SKU
item_external_key string Item external key
item_token string Item token
tierset_id integer Tierset ID # for this line
descrip string Description
line_rate float (Deprecated - see the "tierset" attribute)
line_quantity float Quantity
line_subtotal float Line subtotal
line_total float Line total
expire_recurs integer # of invoices to occur on before expiring
tax_taxable float The total amount that was taxable
tax_taxed float The amount that tax was calculated from
tax_total float The tax amount for this line
tax_id string
tax_group_id string
is_setup bool (Deprecated)
is_base bool (Deprecated)
is_taxed bool
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
subscribe_prorate_from_datetime datetime
subscribe_prorate_to_datetime datetime
tierset array Pricing information

Get a specific quote

API Request

GET /api/v3/quote/198
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "quote_id": 198,
        "terms_id": 2,
        "admin_id": 1,
        "currency_id": 1,
        "token": "659m6ys792j0",
        "refnumber": "198",
        "paycycle": "mon",
        "bill_addr1": "72 E Blue Grass Road",
        "bill_addr2": null,
        "bill_addr3": null,
        "bill_city": "Minneapolis",
        "bill_state": "MN",
        "bill_postcode": "55416",
        "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,
        "write_datetime": "2019-08-14 10:38:50",
        "quote_status_name": "Accepted",
        "quote_status_str": "closed-won",
        "quote_status_state": "c",
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "total": 10.4,
        "setup": 100,
        "terms_name": "Net 30",
        "date": "2019-08-14",
        "due_date": "2019-09-13",
        "bill_block": "72 E Blue Grass Road\r\nMinneapolis, MN 55416\r\nUnited States",
        "ship_block": "",
        "url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/659m6ys792j0",
        "url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/659m6ys792j0",
        "url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/198",
        "url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/659m6ys792j0",
        "url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/659m6ys792j0",
        "customer_id": 294,
        "line_items": [
            {
                "quote_id": 198,
                "item_id": 1,
                "tierset_id": 175,
                "descrip": "This is a ChargeOver test item.",
                "line_rate": 10.95,
                "line_quantity": 1,
                "is_base": false,
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "item_name": "My Test Service Plan",
                "item_external_key": null,
                "item_token": "d70a9a880d95",
                "item_accounting_sku": null,
                "line_total": 10.95,
                "line_subtotal": 10.95,
                "line_item_id": 367,
                "tierset": {
                    "tierset_id": 175,
                    "currency_id": 1,
                    "setup": 100,
                    "base": 10.95,
                    "minimum": 0,
                    "percent": 0,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2019-08-14 10:38:45",
                    "mod_datetime": "2019-08-14 10:38:45",
                    "currency_symbol": "$",
                    "currency_iso4217": "USD",
                    "setup_formatted": "$ 100.00",
                    "base_formatted": "$ 10.95",
                    "minimum_formatted": "$ 0.00",
                    "percent_formatted": "0 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                }
            },
            {
                "quote_id": 198,
                "item_id": 2,
                "tierset_id": 174,
                "descrip": "Discount",
                "line_rate": 0,
                "line_quantity": 1,
                "is_base": false,
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "item_name": "Discount",
                "item_external_key": null,
                "item_token": "62ucb1dhemv3",
                "item_accounting_sku": null,
                "line_total": 0,
                "line_subtotal": 0,
                "line_item_id": 368,
                "tierset": {
                    "tierset_id": 174,
                    "currency_id": 1,
                    "setup": 0,
                    "base": 0,
                    "minimum": 0,
                    "percent": 5,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2019-08-14 10:38:40",
                    "mod_datetime": "2019-08-14 10:38:40",
                    "currency_symbol": "$",
                    "currency_iso4217": "USD",
                    "setup_formatted": "$ 0.00",
                    "base_formatted": "$ 0.00",
                    "minimum_formatted": "$ 0.00",
                    "percent_formatted": "5 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                }
            }
        ],
        "sent": [],
        "invoices": [],
        "packages": [
            {
                "package_id": 44
            }
        ]
    }
}

Email a quote

Send a quote via email. 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.

Email a quote

API Request

POST /api/v3/quote/9?action=email
Content-Type: application/json
 
{
    "_comment": "Each of these is OPTIONAL, and can be used to over-ride the default email templates, etc.",
    "email": "johndoe@send-quote-to.com",
    "subject": "Test subject",
    "body": "Override the default message body here",
    "from": "you@your-company.com"
}

API Response

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

Convert a quote by paycycle

Notes:
Convert a quote based on its paycycle.

  • A quote with a onetime paycycle will be converted into an invoice
  • Anything else will become a subscription (package)
  • "context_str" returns what the quote was converted into (invoice or package)

Convert a quote by paycycle

API Request

POST /api/v3/quote/9?action=convert
 

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"details": {
		"context_str": "package"
	},
	"response": {
		"id": 199
	}
}

Convert a quote to an invoice

Convert a quote into an invoice.

Convert a quote to an invoice

API Request

POST /api/v3/quote/9?action=convertToInvoice
 

API Response

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

Convert a quote to a package

Convert a quote into a subscription (package).

Convert a quote to a package

API Request

POST /api/v3/quote/9?action=convertToPackage
 

API Response

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

Subscriptions (Packages)

Create a subscription

Below is a simple example – the new billing package will use the default shipping and billing address from the customer, and the default pricing from the item (item #239). The first invoice won’t be sent until the holduntil_datetime date (October 1, 2013).

When adding a new package, you can specify the payment method by using paymethod field.

  • If you know the creditcard_id, ach_id, or tokenized_id value you want to use for payment, just specify that field and value - you do not need to specify paymethod at all in this case.
  • To use any credit card the customer already has on file, just specify "paymethod": "crd".
  • To use any ACH/eCheck account the customer already has on file, just specify "paymethod": "ach".
  • To use any payment method available for this customer, just specify "paymethod": "any".
  • If you do not specify a payment method at all, ChargeOver will default to sending an invoice to the customer.

Optionally, when adding a new package, you can specify the payment cycle (how often the customer gets invoiced and/or charged for the subscription) by using the paycycle field. There are several payment cycles you can set a package to run on:


  • dly - Daily
  • 1wk - Every week
  • 2wk - Every other week
  • 116 - 1st and the 16th
  • 4wk - Every four weeks
  • 8wk - Every eight weeks
  • 30d - Every 30 days
  • mon - Monthly
  • 2mn - Every other month
  • 12w - Every twelve weeks
  • qtr - Quarterly
  • six - Every six months
  • yrl - Yearly
  • 2yr - Every 2 years
  • 3yr - Every 3 years
  • 4yr - Every 4 years
  • 5yr - Every 5 years
  • 10y - Every 10 years

If you do not specify a paycycle, the payment cycle for the subscription will set to the default payment cycle configured in your account's General Settings.

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
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) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
line_items - array

A list of line items for the subscription
Attribute Type Description  
external_key string External key value
item_id integer Item ID #
admin_id integer Admin worker ID # (sales rep)
nickname string Nickname for this line of the subscription
descrip string Description
trial_recurs integer # of free trial cycles/cycles to skip
expire_recurs integer # of invoices to occur on before expiring
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
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
tags array A list of tags 📎

Create a subscription

API Request

POST /api/v3/package HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 5,
    "nickname": "Example nickname",
    "paycycle": "mon",
    "custom_1": "Example",
    "coupon": "Example Coupon",
    "holduntil_datetime": "2023-10-01",
    "line_items": [
        {
            "item_id": 1,
            "descrip": "Here is a description for my line item.",
            "line_quantity": 15
        }
    ]
}

API Response

HTTP/1.0 201 Created
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 1986
    }
}

Create a subscription (custom pricing)

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
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) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
line_items - array

A list of line items for the subscription
Attribute Type Description  
external_key string External key value
item_id integer Item ID #
admin_id integer Admin worker ID # (sales rep)
nickname string Nickname for this line of the subscription
descrip string Description
trial_recurs integer # of free trial cycles/cycles to skip
expire_recurs integer # of invoices to occur on before expiring
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
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
tags array A list of tags 📎

Create a subscription (custom pricing)

API Request

POST /api/v3/package HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 5,
    "holduntil_datetime": "2013-10-01",
    "paymethod": "crd",
    "creditcard_id": 38,
    "line_items": [
        {
            "item_id": 2,
            "descrip": "Here is a description for my line item.",
            "tierset": {
                "base": 35,
                "pricemodel": "fla",
                "paycycle": "evy"
            }
        }
    ]
}

API Response

HTTP/1.0 201 Created
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 2526
    }
}

Create a subscription (mixed payment cycles)

ChargeOver supports mixed payment cycle subscriptions, e.g. where part of the subscription is monthly, and part of it is yearly.

Each line item can have it's own payment cycle, as defined by the paycycle attribute. If you do not define a payment cycle for the line, it defaults to the payment cycle set on the product/discount being used.

Important: Invoices are created using the paycycle of the subscription itself. Generally, your subscription payment cycle should be equal to the shortest payment cycle your lines use. Examples:

  • Subscription paycycle=mon (monthly), Line paycycle=yrl (yearly) - invoices are created monthly, but the line will only occur once per year.
  • Subscription paycycle=yrl (yearly), Line paycycle=mon (monthly) - invoices are created yearly, and each invoice will contain 12 lines (one for each month).

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
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) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
line_items - array

A list of line items for the subscription
Attribute Type Description  
external_key string External key value
item_id integer Item ID #
admin_id integer Admin worker ID # (sales rep)
nickname string Nickname for this line of the subscription
descrip string Description
trial_recurs integer # of free trial cycles/cycles to skip
expire_recurs integer # of invoices to occur on before expiring
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
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
tags array A list of tags 📎

Create a subscription (mixed payment cycles)

API Request

POST /api/v3/package
Content-Type: application/json
Authorization: Basic RzhhdmlEbEsyNUhnc0wxakp0OXdFUGh6cEJVb3hxTlM6ZVVTQmJncjRtTHEwTlFUNXNPWnREZmt5Q0tZOHhNbGE
 
{
    "customer_id": 5,
    "paycycle": "mon",
    "line_items": [
        {
            "item_id": 1,
            "descrip": "Yearly product.",
            "tierset": {
                "base": 120,
                "pricemodel": "fla",
                "paycycle": "yrl"
            }
        },
        {
            "item_id": 1,
            "descrip": "Monthly product.",
            "tierset": {
                "base": 10.95,
                "pricemodel": "fla",
                "paycycle": "mon"
            }
        }
    ]
}

API Response

HTTP/1.1 201 Created
Location: https://example.chargeover.com/api/v3/package/41
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 41
    }
}

Create a subscription (prorated)

You can create prorated subscriptions which either generate a prorated invoice right away, or put the prorated charge on the next invoice.

The example to the right creates a new subscription, and generates a prorated invoice for the period March 12, to the end of March. The next invoice date will be April 1.

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
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) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
line_items - array

A list of line items for the subscription
Attribute Type Description  
external_key string External key value
item_id integer Item ID #
admin_id integer Admin worker ID # (sales rep)
nickname string Nickname for this line of the subscription
descrip string Description
trial_recurs integer # of free trial cycles/cycles to skip
expire_recurs integer # of invoices to occur on before expiring
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
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
tags array A list of tags 📎

Create a subscription (prorated)

API Request

POST /api/v3/package
 
{
    "customer_id": 19879,
    "paycycle": "mon",
    "line_items": [
        {
            "item_id": 1,
            "descrip": "Here is a description for my line item.",
            "line_quantity": 15,
            "subscribe_prorate": true,
            "subscribe_prorate_cycle": "now",
            "subscribe_prorate_when": "pre",
            "subscribe_prorate_from_datetime": "2023-03-12",
            "subscribe_prorate_to_datetime": "2023-03-31"
        }
    ]
}

API Response

HTTP/1.1 201 Created
Location: https://example.chargeover.com/api/v3/package/583
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {
        "prorated_invoice_id": 1910
    },
    "response": {
        "id": 583
    }
}

Update a subscription

Object Attributes

Attribute Type Description  
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the subscription 📎
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) 📎
terms_id integer Terms 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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
tags array A list of tags 📎

Update a subscription

API Request

PUT /api/v3/package/1234
 
{
    "nickname": "My new nickname"
}

API Response

HTTP/1.1 202 Accepted
 
{
    "code": 202,
    "status": "OK",
    "message": "",
    "response": {
        "id": 1234
    }
}

Get a list of subscriptions

Returns a list of all subscriptions

Object Attributes

Attribute Type Description  
package_id integer Subscription ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
brand_name string Brand name 📎
class_id integer Class ID # 📎
class_name string Class name 📎
external_key string External key value 📎
token string Unique token 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
paymethod_name string Payment method for the subscription (e.g. Credit Card) 📎
paymethod_detail string Payment method details (e.g. "Visa x1111") 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
admin_id integer Admin/worker ID # 📎
admin_name string Admin/worker name 📎
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) 📎
currency_id integer Currency ID # 📎
currency_iso4217 string Currency ISO 4217 code 📎
currency_symbol string Currency symbol 📎
amount_collected float Total amount collected so far for this subscription 📎
amount_invoiced float Total amount invoiced so far 📎
amount_due float Total amount due (invoiced - collected) 📎
amount_overdue float Total amount past due 📎
suspendfrom_datetime datetime Date/time this subscription was suspended from 📎
suspendto_datetime datetime Date/time this subscription was suspended to 📎
next_invoice_datetime datetime The date the next invoice will be generated 📎
is_overdue boolean Whether or not the subscription is overdue 📎
days_overdue integer # of days overdue the subscription is 📎
start_datetime datetime Date/time this subscription was started/effective 📎
cancel_datetime datetime Date/time this subscription was cancelled 📎
write_datetime datetime Date/time this subscription was created 📎
mod_datetime datetime Date/time this subscription was last updated, upgraded, downgraded, etc.) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
package_status_id integer Subscription status ID # 📎
package_status_name string Human-friendly subscription status 📎
package_status_str string Status string 📎
package_status_state string Status code 📎
mrr float Current monthly recurring revenue of the subscription 📎
arr float Current annual recurring revenue of the subscription 📎
cancel_reason string Reason for cancellation 📎
terms_id integer Terms ID # 📎
terms_name string Payment terms 📎
terms_days integer Terms # of days 📎
paycycle string Payment cycle 📎
paycycle_name string Payment cycle name 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
url_self string URL for viewing the subscription in the GUI 📎

Get a list of subscriptions

API Request

GET api/v3/package
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "terms_id": 3,
            "class_id": null,
            "admin_id": 4,
            "currency_id": 1,
            "brand_id": 1,
            "external_key": null,
            "token": "3u8419j8zq21",
            "nickname": "",
            "paymethod": "crd",
            "paycycle": "yrl",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "bill_postcode": null,
            "bill_country": 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_notes": null,
            "creditcard_id": 44,
            "ach_id": null,
            "tokenized_id": null,
            "custom_1": null,
            "custom_2": null,
            "custom_3": null,
            "custom_4": null,
            "custom_5": null,
            "write_datetime": "2017-06-30 08:37:41",
            "mod_datetime": "2017-06-30 08:37:41",
            "start_datetime": "2017-06-30 08:37:41",
            "suspendfrom_datetime": null,
            "suspendto_datetime": null,
            "cancel_datetime": null,
            "holduntil_datetime": null,
            "terms_name": "Due on Receipt",
            "terms_days": 0,
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "class_name": "",
            "amount_collected": 1030,
            "amount_invoiced": 1030,
            "amount_due": 0,
            "is_overdue": false,
            "days_overdue": 0,
            "next_invoice_datetime": "2018-06-30 06:00:01",
            "cancel_reason": null,
            "url_self": "https://dev.chargeover.com/admin/r/package/view/602",
            "package_id": 602,
            "customer_id": 10,
            "package_status_id": 2,
            "package_status_name": "Current",
            "package_status_str": "active-current",
            "package_status_state": "a"
        }, 
	
	......
 {
            "terms_id": 3,
            "class_id": null,
            "admin_id": null,
            "currency_id": 1,
            "brand_id": 1,
            "external_key": null,
            "token": "7ek3bodjzyg2",
            "nickname": "",
            "paymethod": "ach",
            "paycycle": "mon",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "bill_postcode": null,
            "bill_country": 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_notes": null,
            "creditcard_id": null,
            "ach_id": 4,
            "tokenized_id": null,
            "custom_1": null,
            "custom_2": null,
            "custom_3": null,
            "custom_4": null,
            "custom_5": null,
            "write_datetime": "2017-07-28 11:37:43",
            "mod_datetime": "2017-07-28 11:37:43",
            "start_datetime": "2017-07-28 11:37:43",
            "suspendfrom_datetime": null,
            "suspendto_datetime": null,
            "cancel_datetime": "2017-09-25 14:18:06",
            "holduntil_datetime": null,
            "terms_name": "Due on Receipt",
            "terms_days": 0,
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "class_name": "",
            "amount_collected": 500,
            "amount_invoiced": 500,
            "amount_due": 0,
            "is_overdue": false,
            "days_overdue": 0,
            "next_invoice_datetime": null,
            "cancel_reason": "Unknown or unspecified reason",
            "url_self": "https://dev.chargeover.com/admin/r/package/view/611",
            "package_id": 611,
            "customer_id": 27,
            "package_status_id": 5,
            "package_status_name": "Canceled manually",
            "package_status_str": "canceled-manual",
            "package_status_state": "c"
        }
    ]
}

Get a specific subscription

Object Attributes

Attribute Type Description  
package_id integer Subscription ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
brand_name string Brand name 📎
class_id integer Class ID # 📎
class_name string Class name 📎
external_key string External key value 📎
token string Unique token 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
paymethod_name string Payment method for the subscription (e.g. Credit Card) 📎
paymethod_detail string Payment method details (e.g. "Visa x1111") 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
admin_id integer Admin/worker ID # 📎
admin_name string Admin/worker name 📎
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) 📎
currency_id integer Currency ID # 📎
currency_iso4217 string Currency ISO 4217 code 📎
currency_symbol string Currency symbol 📎
amount_collected float Total amount collected so far for this subscription 📎
amount_invoiced float Total amount invoiced so far 📎
amount_due float Total amount due (invoiced - collected) 📎
amount_overdue float Total amount past due 📎
suspendfrom_datetime datetime Date/time this subscription was suspended from 📎
suspendto_datetime datetime Date/time this subscription was suspended to 📎
next_invoice_datetime datetime The date the next invoice will be generated 📎
is_overdue boolean Whether or not the subscription is overdue 📎
days_overdue integer # of days overdue the subscription is 📎
start_datetime datetime Date/time this subscription was started/effective 📎
cancel_datetime datetime Date/time this subscription was cancelled 📎
write_datetime datetime Date/time this subscription was created 📎
mod_datetime datetime Date/time this subscription was last updated, upgraded, downgraded, etc.) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
package_status_id integer Subscription status ID # 📎
package_status_name string Human-friendly subscription status 📎
package_status_str string Status string 📎
package_status_state string Status code 📎
mrr float Current monthly recurring revenue of the subscription 📎
arr float Current annual recurring revenue of the subscription 📎
cancel_reason string Reason for cancellation 📎
terms_id integer Terms ID # 📎
terms_name string Payment terms 📎
terms_days integer Terms # of days 📎
paycycle string Payment cycle 📎
paycycle_name string Payment cycle name 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
line_items - array

A list of line items for the subscription
Attribute Type Description  
line_item_id integer Line item ID #
package_id integer Package ID #
external_key string External key value
item_id integer Item ID #
admin_id integer Admin worker ID # (sales rep)
item_name string Item name
item_external_key string Item external key
item_accounting_sku string Item accounting SKU
item_token string Item token
item_units float
item_type string Item type
item_is_usage bool Whether or not the item is usage-based/metered
tierset_id integer
nickname string Nickname for this line of the subscription
descrip string Description
trial_days integer (Deprecated - see trial_recurs)
trial_units float
trial_recurs integer # of free trial cycles/cycles to skip
expire_datetime datetime
expire_recurs integer # of invoices to occur on before expiring
line_quantity float Quantity
subscribe_datetime datetime The date/time this line item was last upgraded, downgraded, or added
subscribe_prorate_from_datetime datetime
subscribe_prorate_to_datetime datetime
cancel_datetime datetime The date/time this line item was cancelled
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
tags array A list of tags 📎
url_self string URL for viewing the subscription in the GUI 📎

Get a specific subscription

API Request

GET /api/v3/package/21
 

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "terms_id": 2,
        "class_id": null,
        "admin_id": 3,
        "currency_id": 1,
        "brand_id": 1,
        "external_key": null,
        "token": "1tk5j5u2efhi",
        "nickname": "",
        "paymethod": "inv",
        "paycycle": "mon",
        "bill_addr1": null,
        "bill_addr2": null,
        "bill_addr3": null,
        "bill_city": null,
        "bill_state": null,
        "bill_postcode": null,
        "bill_country": 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_notes": null,
        "creditcard_id": null,
        "ach_id": null,
        "tokenized_id": null,
        "custom_1": null,
        "custom_2": null,
        "custom_3": null,
        "custom_4": null,
        "custom_5": null,
        "write_datetime": "2017-09-20 12:33:44",
        "mod_datetime": "2017-09-20 12:33:44",
        "start_datetime": "2017-09-20 12:33:44",
        "suspendfrom_datetime": null,
        "suspendto_datetime": null,
        "cancel_datetime": null,
        "holduntil_datetime": null,
        "terms_name": "Net 30",
        "terms_days": 30,
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "amount_collected": 0,
        "amount_invoiced": 250,
        "amount_due": 250,
        "is_overdue": false,
        "days_overdue": 0,
        "next_invoice_datetime": "2017-10-20 00:00:01",
        "cancel_reason": null,
        "url_self": "http:\/\/dev.chargeover.com\/admin\/r\/package\/view\/21",
        "package_id": 21,
        "customer_id": 22,
        "package_status_id": 2,
        "package_status_name": "Current",
        "package_status_str": "active-current",
        "package_status_state": "a",
        "line_items": [
            {
                "item_id": 254,
                "tierset_id": 16,
                "admin_id": null,
                "external_key": null,
                "nickname": "",
                "descrip": null,
                "line_quantity": 1,
                "trial_days": 0,
                "trial_recurs": "0",
                "trial_units": 0,
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "subscribe_datetime": "2017-09-20 12:33:44",
                "subscribe_prorate_from_datetime": null,
                "subscribe_prorate_to_datetime": null,
                "cancel_datetime": null,
                "expire_datetime": null,
                "expire_recurs": null,
                "item_name": "Premium Silver",
                "item_external_key": null,
                "item_accounting_sku": null,
                "item_token": "8225neo3wmp4",
                "item_type": "service",
                "item_units": null,
                "item_is_usage": false,
                "line_item_id": 23,
                "package_id": 21,
                "tierset": {
                    "tierset_id": 16,
                    "currency_id": 1,
                    "setup": 0,
                    "base": 250,
                    "percent": 0,
                    "paycycle": "evy",
                    "pricemodel": "fla",
                    "write_datetime": "2017-09-20 12:29:32",
                    "mod_datetime": "2017-09-20 12:29:32",
                    "currency_symbol": "$",
                    "currency_iso4217": "USD",
                    "setup_formatted": "$ 0.00",
                    "base_formatted": "$ 250.00",
                    "percent_formatted": "0 %",
                    "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                    "tiers": []
                }
            }
        ]
    }
}

Querying for subscriptions

Available query parameters:

  • package_id
  • customer_id
  • token
  • brand_id
  • custom_N - Example: custom_1, custom_2, etc.
  • paymethod
  • paycycle
  • nickname
  • bill_state
  • ship_state
  • package_status_str
  • package_status_state
  • external_key
  • write_datetime - date/time created
  • mod_datetime - date/time last modified
  • cancel_datetime
  • quote.quote_id - Get the subscription that originated from a specific quote
  • line_items.external_key
  • line_items.custom_1
  • line_items.item_id - Get subscriptions that contain a specific product/discount
  • customer.superuser_email - Get subscriptions for a specific primary contact email address
  • customer.users.email - Get subscriptions with this email address

Valid values for package_status_state:

  • a (for active packages)
  • c (for cancelled packages)
  • e (for expired packages)
  • s (for suspended packages)

Valid values for package_status_str:

  • active-trial
  • active-current
  • active-overdue
  • canceled-nonpayment
  • canceled-manual
  • expired-expired
  • expired-trial
  • suspended-suspended

Object Attributes

Attribute Type Description  
package_id integer Subscription ID # 📎
customer_id integer Customer ID # 📎
brand_id integer Brand ID # 📎
brand_name string Brand name 📎
class_id integer Class ID # 📎
class_name string Class name 📎
external_key string External key value 📎
token string Unique token 📎
nickname string Nickname for the subscription 📎
paymethod string Payment method for the subscription, one of: crd, inv, ach, tok 📎
paymethod_name string Payment method for the subscription (e.g. Credit Card) 📎
paymethod_detail string Payment method details (e.g. "Visa x1111") 📎
creditcard_id integer Credit card ID # (if the subscription is paid by credit card) 📎
ach_id integer ACH ID # (if the subscription is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the subscription is paid by an external service token) 📎
admin_id integer Admin/worker ID # 📎
admin_name string Admin/worker name 📎
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) 📎
currency_id integer Currency ID # 📎
currency_iso4217 string Currency ISO 4217 code 📎
currency_symbol string Currency symbol 📎
amount_collected float Total amount collected so far for this subscription 📎
amount_invoiced float Total amount invoiced so far 📎
amount_due float Total amount due (invoiced - collected) 📎
amount_overdue float Total amount past due 📎
suspendfrom_datetime datetime Date/time this subscription was suspended from 📎
suspendto_datetime datetime Date/time this subscription was suspended to 📎
next_invoice_datetime datetime The date the next invoice will be generated 📎
is_overdue boolean Whether or not the subscription is overdue 📎
days_overdue integer # of days overdue the subscription is 📎
start_datetime datetime Date/time this subscription was started/effective 📎
cancel_datetime datetime Date/time this subscription was cancelled 📎
write_datetime datetime Date/time this subscription was created 📎
mod_datetime datetime Date/time this subscription was last updated, upgraded, downgraded, etc.) 📎
holduntil_datetime datetime Date/time invoicing for this subscription is being delayed until 📎
package_status_id integer Subscription status ID # 📎
package_status_name string Human-friendly subscription status 📎
package_status_str string Status string 📎
package_status_state string Status code 📎
mrr float Current monthly recurring revenue of the subscription 📎
arr float Current annual recurring revenue of the subscription 📎
cancel_reason string Reason for cancellation 📎
terms_id integer Terms ID # 📎
terms_name string Payment terms 📎
terms_days integer Terms # of days 📎
paycycle string Payment cycle 📎
paycycle_name string Payment cycle name 📎
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 📎
first_invoice_schedule_template_id integer Payment schedule to use for the first invoice generated 📎
recurring_invoice_schedule_template_id integer Payment schedule to use for subsequent generated invoices 📎
url_self string URL for viewing the subscription in the GUI 📎

Querying for subscriptions

API Request

GET /api/v3/package?where=package_status_state:EQUALS:a,customer_id:EQUALS:16
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "terms_id": 3,
            "currency_id": 1,
            "external_key": "adlink_5901",
            "nickname": "",
            "paymethod": "crd",
            "paycycle": "mon",
            "bill_addr1": null,
            "bill_addr2": null,
            "bill_addr3": null,
            "bill_city": null,
            "bill_state": null,
            "bill_postcode": null,
            "bill_country": 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_notes": null,
            "creditcard_id": 53,
            "ach_id": null,
            "custom_1": null,
            "custom_2": null,
            "custom_3": null,
            "write_datetime": "2014-06-20 15:52:47",
            "mod_datetime": "2014-06-20 15:52:57",
            "suspendfrom_datetime": null,
            "suspendto_datetime": null,
            "cancel_datetime": null,
            "holduntil_datetime": null, 
            "currency_symbol": "$",
            "currency_iso4217": "USD",
            "amount_collected": 0,
            "amount_invoiced": 0,
            "amount_due": 0,
            "next_invoice_datetime": "2014-09-01 00:00:01",
            "package_id": 16,
            "customer_id": 16,
            "package_status_id": 2,
            "package_status_name": "Current",
            "package_status_str": "active-current",
            "package_status_state": "a"
        }
    ]
}

Upgrade/downgrade a subscription

When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:

  • Change a customer’s product to a different product
  • Change the amount a customer is charged each month
  • Add or remove products that are charged each month
Example of upgrading a package, changing a specific line item to a different product/service type:

Upgrade/downgrade a subscription

API Request

POST /api/v3/package/554?action=upgrade HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "line_items": [
        {
            "_comment": "If you want to change the quantity, specify the new quantity here",
            "line_item_id": 1953,
            "item_id": 239,
            "descrip": "A new description goes here",
            "line_quantity": 123
        }
    ]
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Upgrade/downgrade a subscription (and prorate amounts)

When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:

  • Change a customer’s product to a different product
  • Change the amount a customer is charged each month
  • Add or remove products that are charged each month
This example shows how to change a customer's subscription to a different product type, AND how to create a prorated invoice for the new amount / credit back the unused portion of the old product to the customer.

Upgrade/downgrade a subscription (and prorate amounts)

API Request

POST /api/v3/package/612?action=upgrade
 
{
    "line_items": [
        {
            "_comment": "This tells ChargeOver to credit back the unused portion of the old product.",
            "line_item_id": 729,
            "item_id": 14,
            "descrip": "Upgraded description goes here",
            "line_quantity": 1,
            "subscribe_prorate": true,
            "subscribe_prorate_cycle": "now",
            "subscribe_prorate_when": "pre",
            "cancel_prorate": true,
            "cancel_prorate_credit": true,
            "cancel_prorate_cycle": "now"
        }
    ]
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Upgrade a subscription by adding a line item (and prorate amounts)

When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:

  • Change a customer’s product to a different product
  • Change the amount a customer is charged each month
  • Add or remove products that are charged each month

This example shows how to add a line item to a customer's subscription AND how to create a prorated invoice for the new amount.

  • The subscribe_prorate_from_datetime and subscribe_prorate_to_datetime fields are optional -- if you don't specify dates, ChargeOver will assume the current date until the end of the current billing cycle
  • The subscribe_prorate_cycle options are: "now" (generate an invoice for the prorated amount right now) or "next"(add the prorated charge to the next invoice that will be generated at the end of the billing cycle)

Upgrade a subscription by adding a line item (and prorate amounts)

API Request

POST /api/v3/package/49?action=upgrade
 
{
    "line_items": [
        {
            "_comment": "This tells ChargeOver to create an invoice for the new prorated amount right away (billing in advance).",
            "item_id": 1,
            "descrip": "The description of the new line item",
            "line_quantity": 1,
            "subscribe_prorate": true,
            "subscribe_prorate_cycle": "now",
            "subscribe_prorate_when": "pre",
            "subscribe_prorate_from_datetime": "2018-04-20"
        }
    ]
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {
        "prorated_invoice_id": 1082
    },
    "response": true
}

Cancel a line item on a subscription

It is also possible to cancel a specific line item on a subscription so that the customer will no longer be billed for it on future invoices.

The example to the right shows how to cancel a line item on a subscription using the line_item_id of the line item(s) you want to cancel.

If you cancel all of the lines on the subscription, the default behavior is to leave the subscription itself active (but with no line items). If you want to cancel the subscription itself when all of the line items are cancelled, you can also specify: "cancel_package_if_last_line_item": true

Cancel a line item on a subscription

API Request

POST /api/v3/package/626?action=upgrade
 
{
    "line_items": [
        {
            "line_item_id": 679,
            "cancel": true
        }
    ]
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Change pricing on a subscription

Changing a subscription price is accomplished by going through the upgrade/downgrade REST API call.

The example to the right shows how to change the pricing on a subscription.

Change pricing on a subscription

API Request

POST /api/v3/package/585?action=upgrade
 
{
    "line_items": [
        {
            "line_item_id": 590,
            "item_id": 1,
            "descrip": "Upgraded description goes here",
            "tierset": {
                "setup": 10,
                "base": 135,
                "pricemodel": "uni",
                "tiers": [
                    {
                        "unit_from": 1,
                        "unit_to": 9999,
                        "amount": 60
                    }
                ]
            }
        }
    ]
}

API Response

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

Invoice a subscription now

The default behavior when creating a recurring package via the ChargeOver REST API is to generate the first invoice on the following day.

You can trigger the immediate generation of an invoice by calling this method. By default, the invoice created will be dated with today's date.

You can also immediately generate future-dated invoices by specifying a date attribute in YYYY-MM-DD format. There is also one special date, the string NEXT_SCHEDULED_INVOICE, which will generate an invoice dated with the date of the next normally scheduled invoice.

Invoice a subscription now

API Request

POST /api/v3/package/624?action=invoice
 
{
    "_comment1": "This payload is optional. By default, the invoice generated is dated with today's date.",
    "_comment2": "You can specify a date for the invoice like this:",
    "date": "2025-01-02"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "id": 10049
    }
}

Adjust the next invoice date for a subscription

This will change the date that the next invoice for a subscription is generated on.

For example, if you specify the holduntil_datetime to be "2019-10-03", the next date that an invoice will be generated on for that subscription will be changed to October 3, 2019.

Adjust the next invoice date for a subscription

API Request

POST /api/v3/package/636?action=hold
 
{
    "holduntil_datetime": "2019-10-03"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Suspend a subscription (indefinitely)

Suspending a billing package is useful when you want to skip billing a customer for a given period of time (e.g. if you deliver a weekly newspaper, and they are going on vacation a month, you may want to skip billing them and skip delivery while they are on vacation).

Suspend a subscription (indefinitely)

API Request

POST /api/v3/package/1965?action=suspend HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
 

API Response

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

Suspend a subscription (range)

Suspend a subscription (range)

API Request

POST /api/v3/package/1965?action=suspend HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "suspendfrom_datetime": "2013-04-25 00:00:01",
    "suspendto_datetime": "2013-05-25 00:00:01"
}

API Response

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

Unsuspend a subscription

Unsuspend a subscription

API Request

POST /api/v3/package/1965?action=unsuspend HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
 

API Response

HTTP/1.0 200 OK 
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Cancel a subscription

This allows you to cancel a subscription immediately, or to schedule a subscription to cancel on a future date.

To cancel immediately, do not specify a cancel_date value. To schedule a future cancellation, pass in a cancel_date value (formatted as YYYY-MM-DD) to specify the future cancellation date.

Cancel a subscription

API Request

POST /api/v3/package/600?action=cancel
 
{
    "_comment_reason": "The [cancel_reason_id] fields is optional; you do not need to include it.",
    "cancel_reason_id": 1,
    "_comment_date": "The [cancel_date] field is optional. Specify a date in the future to schedule the subscription for future cancellation.",
    "cancel_date": "2023-10-24"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Change the payment cycle

Valid values for specifying paycycle:

  • dly - daily
  • 1wk - weekly
  • 2wk - 2 weeks
  • 4wk - 4 weeks
  • 2mn - 2 months
  • mon - monthly
  • qtr - quarterly
  • yrl - yearly
  • 2yr - 2 years
  • 3yr - 3 years
  • 4yr - 4 years
  • 5yr - 5 years
  • 10y - 10 years
  • six - 6 months
  • 30d - 30 days
  • 8wk - 8 weeks
  • 12w - 12 weeks

Change the payment cycle

API Request

POST /api/v3/package/599?action=setPayCycle
 
{
    "paycycle": "1wk"
}

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Set the payment method

Valid values for specifying paymethod:

  • inv - Generate an invoice for the subscription but do not take an automatic payment
  • crd - Credit Card
  • ach - ACH/eCheck
  • tok - Tokenized payment method

Additionally:

  • If you specify crd you must specify the creditcard_id
  • If you specify ach you must specify the ach_id
  • If you specify tok you must specify the tokenized_id

Set the payment method

API Request

POST /api/v3/package/599?action=setPayMethod
 
{
    "paymethod": "crd",
    "creditcard_id": 64

    // If you wanted to specify an ACH account instead
    // "paymethod": "ach",
    // "ach_id": 65,

    // If you wanted to specify they should receive an invoice (no automatic payment)
    // "paymethod": "inv",
}

API Response

HTTP/1.0 200 OK 
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Send a welcome e-mail

This will send a welcome e-mail (using your welcome e-mail template) to the primary contact for the package/customer.

Send a welcome e-mail

API Request

POST /api/v3/package/616?action=sendWelcome
Content-Type: application/json
 
{
    "_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
    "email": "to@example.com",
    "cc": "cc@example.com",
    "bcc": "bcc@example.com",
    "subject": "Override the default subject",
    "body": "Override the default plain-text body of the email",
    "html": "Override the default <b>HTML body<\/b> of the email",
    "from": "\"Example Company\" <from@example.com>",
    "_comment_message_id": "You can optionally specify a message_id value to use a specific email template.",
    "message_id": 2
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Items (Products, Discounts)

Create an item

The response/id value will be the item_id value for the newly created item.

Valid values for paycycle
  • evy - Every billing cycle
  • dly - Daily
  • 1wk - Every week
  • 2wk - Every other week
  • 116 - 1st and the 16th
  • 4wk - Every four weeks
  • 8wk - Every eight weeks
  • 30d - Every 30 days
  • mon - Monthly
  • 2mn - Every other month
  • 12w - Every twelve weeks
  • qtr - Quarterly
  • six - Every six months
  • yrl - Yearly
  • 2yr - Every 2 years
  • 3yr - Every 3 years
  • 4yr - Every 4 years
  • 5yr - Every 5 years
  • 10y - Every 10 years
Valid values for pricemodel
  • fla - Flat Pricing (example: $X dollars every billing cycle)
  • uni - Unit Pricing (example: $X per unit every billing cycle)
  • vol - Volume Pricing (example: $X dollars every billing cycle, with different price levels depending on volume)
  • tie - Tiered Pricing (example: $X dollars every billing cycle for the first 10 units, then $Y dollars per month for the next 10 units, etc.)
  • pas - Pass-through from usage data (Pass-through pricing is for scenarios where the usage data and the pricing is already known)

Object Attributes

Attribute Type Description  
item_type string Item type 📎
name string Item name 📎
description string Description 📎
enabled boolean Enabled/disabled 📎
accounting_sku string Accounting SKU 📎
accounting_account_income string Accounting Income Account 📎
external_key string External key value 📎
units string Units string 📎
tax_group_id integer Tax group ID # 📎
expire_recurs integer Default # of times to recur 📎
trial_recurs integer Default # of times to skip/free trial cycles 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎

Create an item

API Request

POST /api/v3/item 
 
{
    "name": "Multi-Currency Test Product",
    "item_type": "service",
    "pricemodels": [
        {
            "currency_iso4217": "USD",
            "base": 195.95,
            "paycycle": "mon",
            "pricemodel": "fla"
        },
        {
            "currency_iso4217": "CAD",
            "base": 195.95,
            "paycycle": "mon",
            "pricemodel": "fla"
        }
    ]
}

API Response

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

Querying for items

Available query parameters

  • item_id
  • name
  • external_key
  • accounting_sku
  • item_type
  • custom_1
  • custom_2
  • custom_3
Valid values for item_type
  • service (for Services)
  • discount (for Discounts)

Object Attributes

Attribute Type Description  
item_id integer Item ID # 📎
item_type string Item type 📎
name string Item name 📎
description string Description 📎
enabled boolean Enabled/disabled 📎
accounting_sku string Accounting SKU 📎
accounting_account_income string Accounting Income Account 📎
external_key string External key value 📎
units string Units string 📎
units_plural string Units string pluralized 📎
tax_group_id integer Tax group ID # 📎
tax_group_name string Tax group name 📎
expire_recurs integer Default # of times to recur 📎
trial_recurs integer Default # of times to skip/free trial cycles 📎
token string Unique token 📎
tierset_id integer Default pricing tierset ID # 📎
write_datetime datetime Date/time the item was created 📎
mod_datetime datetime Date/time the item was last updated 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎

Querying for items

API Request

GET /api/v3/item?where=item_type:EQUALS:service
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "item_id": 1,
            "item_type": "service",
            "tierset_id": 1,
            "name": "My Test Service Plan",
            "description": "This is a ChargeOver test item.",
            "units": "",
            "accounting_sku": null,
            "external_key": null,
            "token": "d56c047651ec",
            "custom_1": "",
            "custom_2": "",
            "custom_3": "",
            "write_datetime": "2014-12-02 18:46:48",
            "mod_datetime": "2014-12-02 18:46:48",
            "units_plural": "",
            "tiersets": [
                {
                    "tierset_id": 1,
                    "setup": 0,
                    "base": 10.95,
                    "paycycle": "mon",
                    "pricemodel": "fla",
                    "write_datetime": "2014-12-02 18:46:48",
                    "mod_datetime": "2014-12-02 18:46:48",
                    "setup_formatted": "$ 0.00",
                    "base_formatted": "$ 10.95",
                    "pricemodel_desc": "Flat Pricing (e.g. $X dollars per month)",
                    "tiers": []
                }
            ]
        }
    ]
}

Get a specific item

Get a specific item using its item_id.

Object Attributes

Attribute Type Description  
item_id integer Item ID # 📎
item_type string Item type 📎
name string Item name 📎
description string Description 📎
enabled boolean Enabled/disabled 📎
accounting_sku string Accounting SKU 📎
accounting_account_income string Accounting Income Account 📎
external_key string External key value 📎
units string Units string 📎
units_plural string Units string pluralized 📎
tax_group_id integer Tax group ID # 📎
tax_group_name string Tax group name 📎
expire_recurs integer Default # of times to recur 📎
trial_recurs integer Default # of times to skip/free trial cycles 📎
token string Unique token 📎
tierset_id integer Default pricing tierset ID # 📎
write_datetime datetime Date/time the item was created 📎
mod_datetime datetime Date/time the item was last updated 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎

Get a specific item

API Request

GET /api/v3/item/12
 

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "item_id": 12,
        "item_type": "service",
        "tierset_id": 24,
        "name": "My Test Service Plan",
        "description": null,
        "units": null,
        "enabled": true,
        "accounting_sku": null,
        "external_key": null,
        "token": "c162794b20v7",
        "custom_1": null,
        "custom_2": null,
        "custom_3": null,
        "write_datetime": "2019-10-07 11:15:51",
        "mod_datetime": "2019-10-07 11:15:51",
        "units_plural": "",
        "expire_recurs": null,
        "trial_recurs": null,
        "service_data": {
            "trial_days": 0,
            "trial_units": 0,
            "is_usage": false
        },
        "tiersets": [
            {
                "tierset_id": 24,
                "currency_id": 1,
                "setup": 0,
                "base": 100,
                "minimum": 0,
                "percent": 0,
                "paycycle": "evy",
                "pricemodel": "fla",
                "write_datetime": "2019-10-07 11:15:51",
                "mod_datetime": "2019-10-07 11:15:51",
                "currency_symbol": "$",
                "currency_iso4217": "USD",
                "setup_formatted": "$ 0.00",
                "base_formatted": "$ 100.00",
                "minimum_formatted": "$ 0.00",
                "percent_formatted": "0 %",
                "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                "tiers": []
            },
            {
                "tierset_id": 24,
                "currency_id": 1,
                "setup": 0,
                "base": 100,
                "minimum": 0,
                "percent": 0,
                "paycycle": "evy",
                "pricemodel": "fla",
                "write_datetime": "2019-10-07 11:15:51",
                "mod_datetime": "2019-10-07 11:15:51",
                "currency_symbol": "$",
                "currency_iso4217": "USD",
                "setup_formatted": "$ 0.00",
                "base_formatted": "$ 100.00",
                "minimum_formatted": "$ 0.00",
                "percent_formatted": "0 %",
                "pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
                "tiers": []
            }
        ],
        "categories": []
    }
}

Update an item

This allows you to update an existing product. When updating a product, you can specify the pricing for multiple currencies if desired.

Object Attributes

Attribute Type Description  
name string Item name 📎
description string Description 📎
enabled boolean Enabled/disabled 📎
accounting_sku string Accounting SKU 📎
accounting_account_income string Accounting Income Account 📎
external_key string External key value 📎
units string Units string 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎

Update an item

API Request

PUT /api/v3/item/270
 
{
    "name": "Standard Plan",
    "item_type": "service",
    "pricemodels": [
        {
            "currency_iso4217": "USD",
            "base": 295.05,
            "paycycle": "mon",
            "pricemodel": "fla"
        },
        {
            "currency_iso4217": "CAD",
            "base": 195.95,
            "paycycle": "mon",
            "pricemodel": "fla"
        }
    ]
}

API Response

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

Delete an item

This allows you to delete a product that is not in use. You will only be able to delete a product if it is not on any invoices or subscriptions.

Delete an item

API Request

DELETE /api/v3/item/263
 

API Response

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

Credit Cards

Store a credit card

This method can be used to store a new card or update an existing card.
To update an existing card: Send a new POST request using an existing card number with its updated values. The stored card will then be updated.

Object Attributes

Attribute Type Description  
customer_id integer The customer id # 📎
external_key string Unique external key value 📎
name string Name on credit card 📎
number string Credit card number 📎
cvv string CVV/CSC security code (not stored, but may be used for validation/pre-auth) 📎
expdate string Expiration date (in YYYY-MM-DD format) 📎
expdate_year string Expiration year (4-digits, YYYY) (only required if you do not provide expdate) 📎
expdate_month string Expiration month (2-digits, MM) (only required if you do not provide expdate) 📎
address string Billing street address 📎
city string Billing city 📎
postcode string Billing postal code 📎
country string Billing country 📎

Store a credit card

API Request

POST /api/v3/creditcard HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "customer_id": 475,
    "number": "4111 1111 1111 1111",
    "expdate_year": "2015",
    "expdate_month": "11",
    "cvv": 123,
    "name": "Keith Palmer",
    "address": "72 E Blue Grass Road",
    "city": "Willington",
    "state": "CT",
    "postcode": "06279",
    "country": "United States"
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/creditcard/438
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 438
    }
}

Querying for credit cards

Available query parameters:

  • creditcard_id
  • customer_id
  • external_key
  • token

Object Attributes

Attribute Type Description  
customer_id integer The customer id # 📎
creditcard_id integer The credit card ID # 📎
external_key string Unique external key value 📎
type string Credit card type 📎
type_name string Credit card type user-friendly name 📎
token string Credit card token 📎
name string Name on credit card 📎
mask_number string Last 4 digits of the credit card 📎
mask_and_bin_number string First 6 digits and last 4 digits of the credit card 📎
expdate string Expiration date (in YYYY-MM-DD format) 📎
expdate_year string Expiration year (4-digits, YYYY) (only required if you do not provide expdate) 📎
expdate_month string Expiration month (2-digits, MM) (only required if you do not provide expdate) 📎
expdate_formatted string Expiration date (formatted) 📎
address string Billing street address 📎
city string Billing city 📎
postcode string Billing postal code 📎
country string Billing country 📎
url_updatelink string 📎
write_datetime datetime Date/time the credit card was stored 📎
write_ipaddr datetime IP address that created the card 📎

Querying for credit cards

API Request

GET /api/v3/creditcard?limit=10&where=customer_id:EQUALS:3
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "creditcard_id": 1,
            "external_key": null,
            "type": "visa",
            "token": "ly1j7wmginqp",
            "expdate": "2023-05-01",
            "write_datetime": "2019-07-25 10:24:52",
            "write_ipaddr": "10.80.1.1",
            "mask_number": "x1111",
            "mask_and_bin_number": "411111xxx1111",
            "name": "John LLC",
            "expdate_month": "5",
            "expdate_year": "2023",
            "expdate_formatted": "May 2023",
            "type_name": "Visa",
            "url_updatelink": "https:\/\/example.chargeover.com\/r\/paymethod\/i\/ru0895x81ht1",
            "address": null,
            "city": null,
            "postcode": null,
            "country": "United States",
            "customer_id": 2
        },
        {
            "creditcard_id": 2,
            "external_key": null,
            "type": "mast",
            "token": "4ei8py0h1x06",
            "expdate": "2022-05-01",
            "write_datetime": "2019-07-25 10:25:37",
            "write_ipaddr": "10.80.1.1",
            "mask_number": "x4444",
            "mask_and_bin_number": "555555xxx4444",
            "name": "John LLC",
            "expdate_month": "5",
            "expdate_year": "2022",
            "expdate_formatted": "May 2022",
            "type_name": "MasterCard",
            "url_updatelink": "https:\/\/example.chargeover.com\/r\/paymethod\/i\/ru0895x81ht1",
            "address": null,
            "city": null,
            "postcode": null,
            "country": "United States",
            "customer_id": 2
        }
    ]
}

Delete a credit card

Delete a credit card

API Request

DELETE /api/v3/creditcard/43
 

API Response

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

ACH/eCheck Accounts

Store an ACH account

This method can be used to store a new ACH or update an existing ACH.
To update an existing card: Send a new POST request using existing routing and number fields with its updated values. The stored ACH will then be updated.

Notes:
  • The type field must be one of: chec (personal checking account), busi (business checking account), or savi (savings account)
  • The number field should be a valid bank account number
Routing number formatting for Canadian bank accounts:
0(3-digit institution code)(5 digit transit number)
Example: 032012345

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
external_key string Unique external key value 📎
type string Bank account type (one of: chec, busi, savi) 📎
number string Bank account number 📎
routing string Bank account routing number 📎
name string Name on bank account 📎
bank string Bank name 📎

Store an ACH account

API Request

POST /api/v3/ach HTTP/1.1
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
 
{
    "customer_id": "8",
    "type": "chec",
    "routing": "072403004",
    "number": "856667",
    "name": "John Doe"
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/ach/3
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "id": 3
    }
}

Querying for ACH accounts

Available query parameters:

  • ach_id
  • customer_id
  • external_key
  • token

Object Attributes

Attribute Type Description  
ach_id integer ACH ID # 📎
customer_id integer Customer ID # 📎
external_key string Unique external key value 📎
type string Bank account type (one of: chec, busi, savi) 📎
type_name string Bank account type (pretty name) 📎
token string ACH account token 📎
mask_number string Last 4 digits of the bank account number 📎
mask_routing string Bank account routing number 📎
name string Name on bank account 📎
mask_bank string Bank name 📎
url_verifylink string ACH verification link 📎

Querying for ACH accounts

API Request

GET /api/v3/ach?limit=10&where=customer_id:EQUALS:36
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "ach_id": 6,
            "external_key": null,
            "type": "chec",
            "token": "zm960n26k14h",
            "type_name": "Checking",
            "customer_id": 36,
            "name": "Camille Bettencourt",
            "mask_bank": "Isabella Bank",
            "mask_number": "x6667",
            "mask_routing": "x3004"
        },
        {
            "ach_id": 7,
            "external_key": null,
            "type": "chec",
            "token": "31q03f11yw98",
            "type_name": "Checking",
            "customer_id": 36,
            "name": "Camille Bettencourt",
            "mask_bank": "Td Bank, Na",
            "mask_number": "x6670",
            "mask_routing": "x3093"
        }
    ]
}

Delete an ACH account

Delete an ACH account

API Request

DELETE /api/v3/ach/1
 

API Response

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

Tokenized Pay Methods

The tokenized card APIs are used for storing/retrieving credit cards that have already been tokenized by another service (e.g. customer or card tokens from other payment gateways such as Stripe or Braintree).

This is useful if you're migrating from Stripe or Braintree but want to still be able to use the credit cards you have stored there during migration.

Store a pay method token

Store an already tokenized credit card in ChargeOver.

Object Attributes

Attribute Type Description  
customer_id integer Customer ID # 📎
name string Descriptive name for token (e.g. "Visa x4111") 📎
type string Type of token (usually "customer") 📎
paymethod_hint string (Optional) Either "crd" (credit card) or "ach" (ACH/bank accounts) 📎
expdate date (Optional; only required for First Data/Payeezy) Expiration date (YYYY-MM-DD) of the tokenized credit card 📎
type_hint string (Optional; only required for First Data/Payeezy) A credit card type (one of "visa", "mast", "disc", or "amex") 📎
token string The token value 📎
gateway string (Optional; only required if providing tokens for multiple gateways) A hint for which gateway this is a token for 📎

Store a pay method token

API Request

POST /api/v3/tokenized HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo...
Content-Type: application/json
 
{
    "customer_id": 1,
    "token": "cus_5tSkoQ6mDrXOMQ",
    "type": "customer"
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/tokenized/7
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 7
    }
}

Querying for pay method tokens

Available query parameters:

  • customer_id
  • customer_external_key
  • customer_token

Object Attributes

Attribute Type Description  
tokenized_id integer Tokenized ID # 📎
customer_id integer Customer ID # 📎
name string Descriptive name for token (e.g. "Visa x4111") 📎
type string Type of token (usually "customer") 📎
paymethod_hint string (Optional) Either "crd" (credit card) or "ach" (ACH/bank accounts) 📎
expdate date (Optional; only required for First Data/Payeezy) Expiration date (YYYY-MM-DD) of the tokenized credit card 📎
type_hint string (Optional; only required for First Data/Payeezy) A credit card type (one of "visa", "mast", "disc", or "amex") 📎
token string The token value 📎
gateway string (Optional; only required if providing tokens for multiple gateways) A hint for which gateway this is a token for 📎
write_datetime datetime Date/time the tokenized payment method was stored 📎
mod_datetime datetime Date/time the tokenized payment method was edited 📎

Querying for pay method tokens

API Request

GET /api/v3/tokenized?limit=10&where=customer_id:EQUALS:2
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "tokenized_id": 1,
            "type": "customer",
            "name": null,
            "token": "cus_5tSkoQ6mDrXOMQ",
            "expdate": null,
            "type_hint": null,
            "paymethod_hint": null,
            "customer_id": 2
        }
    ]
}

Delete tokenized pay method

Delete tokenized pay method

API Request

DELETE /api/v3/tokenized/1
 

API Response

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

Brands

Retrieve brand list

Object Attributes

Attribute Type Description  
brand_id integer Brand ID # 📎
brand string Deprecated (use "name" instead) 📎
name string Brand name 📎
brand_addr1 string Street address 1 📎
brand_addr2 string Street address 1 📎
brand_city string City 📎
brand_state string State/province 📎
brand_postcode string Postal code 📎
brand_country string Country 📎
brand_block string Printable brand address 📎
brand_phone string Brand phone number 📎
brand_email string Brand email address 📎
brand_linkedin string Brand linkedin 📎
brand_twitter string Brand twitter 📎
brand_facebook string Brand facebook 📎
brand_yelp string Brand yelp 📎
brand_youtube string Brand youtube 📎
brand_instagram string Brand instagram 📎
brand_pinterest string Brand pinterest 📎
brand_tiktok string Brand tiktok 📎
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 📎
url_logosmall string URL to a small version of the brand logo 📎
url_logomedium string URL to a medium version of the brand logo 📎
url_logolarge string URL to a large version of the brand logo 📎
url_logohuge string URL to a huge version of the brand logo 📎
url_logooriginal string URL to the originally uploaded brand logo 📎

Retrieve brand list

API Request

GET /api/v3/brand
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "brand_id": 1,
            "brand": "Default"
        }
    ]
}

Usage

Storing Usage Data

Object Attributes

Attribute Type Description  
line_item_id string Line Item ID that the usage is for 📎
usage_value string Usage value 📎
type string Usage type (default "add", other options are "add", "max", "lat", "pia", "pas", "dlt") 📎
options array An array of usage options 📎
from datetime Starting date/time for the usage period 📎
to datetime Ending date/time for the usage period 📎
external_key string External key value 📎
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 📎

Storing Usage Data

API Request

POST /api/v3/usage HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "line_item_id": 609,
    "usage_value": 265.2,
    "from": "2013-10-16",
    "to": "2013-10-16"
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/usage/52
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 52
    }
}

Bulk Usage Data Upload

ChargeOver also has a dedicated bulk endpoint to push usage to. You can upload a maximum number of 1000 usage records per REST API call.

In addition to line_item_id, ChargeOver also supports sending usage data using the customer.external_key and line_item.item_external_key fields.

Object Attributes

Attribute Type Description  
line_item_id string Line Item ID that the usage is for 📎
usage_value string Usage value 📎
type string Usage type (default "add", other options are "add", "max", "lat", "pia", "pas", "dlt") 📎
options array An array of usage options 📎
from datetime Starting date/time for the usage period 📎
to datetime Ending date/time for the usage period 📎
external_key string External key value 📎
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 📎

Bulk Usage Data Upload

API Request

POST /api/v3/usage?action=bulk
Content-Type: application/json
 
[
    {
        "customer.external_key": "77889",
        "line_item.item_external_key": "item_key",
        "usage_value": 100
    },
    {
        "line_item_id": 720,
        "usage_value": 101
    },
    {
        "line_item_id": 722,
        "usage_value": 300
    },
    {
        "line_item_id": 723,
        "usage_value": 150
    }
]

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "id": 6,
            "message": null
        },
        {
            "id": 7,
            "message": null
        },
        {
            "id": 8,
            "message": null
        },
        {
            "id": 9,
            "message": null
        }
    ]
}

Categories

Available query parameters:

  • item_category_id
  • external_key
  • name
  • children_of_item_category_id (i.e. get the child categories of this category)
  • parent_of_item_category_id (i.e. get the parent category of this category)

Query for categories

Object Attributes

Attribute Type Description  
item_category_id integer Item category ID # 📎
name string Category name 📎
external_key string External key value 📎

Query for categories

API Request

GET /api/v3/item_category?where=
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "item_category_id": 1,
            "name": "Root",
            "external_key": null
        },
        {
            "item_category_id": 2,
            "name": "Cars",
            "external_key": ""
        },
        {
            "item_category_id": 3,
            "name": "Motorcycles",
            "external_key": ""
        },
        {
            "item_category_id": 4,
            "name": "Trucks",
            "external_key": ""
        },
        {
            "item_category_id": 8,
            "name": "SUVs",
            "external_key": ""
        },
        {
            "item_category_id": 7,
            "name": "Sports Cars",
            "external_key": ""
        },
        {
            "item_category_id": 9,
            "name": "Ducati",
            "external_key": ""
        },
        {
            "item_category_id": 10,
            "name": "Kawasaki",
            "external_key": ""
        },
        {
            "item_category_id": 11,
            "name": "Triumph",
            "external_key": ""
        }
    ]
}

Campaigns

Retrieve campaign list

Retrieve campaign list

API Request

GET /api/v3/campaign
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "campaign_id": 1,
            "campaign": "Some affiliate website or lead source"
        },
        {
            "campaign_id": 3,
            "campaign": "Another campaign"
        }
    ]
}

Classes

Retrieve a list of classes

Object Attributes

Attribute Type Description  
class_id integer Class ID # 📎
name string Class name 📎
accounting_sku string Accounting system SKU 📎

Retrieve a list of classes

API Request

GET /api/v3/class
 

API Response

{
  "code": 200,
  "status": "OK",
  "message": "",
  "details": {},
  "response": [
    {
      "class_id": 4,
      "name": "KMT-20",
      "accounting_sku": "KMT-20"
    },
    {
      "class_id": 8,
      "name": "PREM-BRZ",
      "accounting_sku": "PREM-03"
    },
    {
      "class_id": 6,
      "name": "PREM-GLD",
      "accounting_sku": "PREM-01"
    },
    {
      "class_id": 7,
      "name": "PREM-SLVR",
      "accounting_sku": "PREM-02"
    },
    {
      "class_id": 9,
      "name": "QT",
      "accounting_sku": "QT-01"
    },
    {
      "class_id": 3,
      "name": "TBT-03",
      "accounting_sku": "TBT-03"
    },
    {
      "class_id": 5,
      "name": "TBT-05",
      "accounting_sku": "TBT-05"
    },
    {
      "class_id": 1,
      "name": "Test -UGG-01",
      "accounting_sku": "UGG-01"
    },
    {
      "class_id": 2,
      "name": "VRG-02",
      "accounting_sku": "VRG-02"
    }
  ]
}

Retrieve a specific class

Allows you to retrieve a specific class based on its class_id.

Object Attributes

Attribute Type Description  
class_id integer Class ID # 📎
name string Class name 📎
accounting_sku string Accounting system SKU 📎

Retrieve a specific class

API Request

GET /api/v3/class/1
 

API Response

{
  "code": 200,
  "status": "OK",
  "message": "",
  "details": {},
  "response": {
    "class_id": 1,
    "name": "Test -UGG-01",
    "accounting_sku": "UGG-01"
  }
}

Countries

Retrieve country list

Retrieve country list

API Request

GET /api/v3/country
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "country_id": 16,
            "name": "Australia",
            "iso2": "AU",
            "iso3": "AUS",
            "cctld": ".au"
        },
        {
            "country_id": 2,
            "name": "Aland Islands",
            "iso2": "AX",
            "iso3": "ALA",
            "cctld": ".ax"
        },
        {
            "country_id": 42,
            "name": "Canada",
            "iso2": "CA",
            "iso3": "CAN",
            "cctld": ".ca"
        },
        {
            "country_id": 243,
            "name": "United States",
            "iso2": "US",
            "iso3": "USA",
            "cctld": ".us"
        }
    ]
}

Coupons

Retrieve a list of coupons

Object Attributes

Attribute Type Description  
coupon_id integer The coupon ID # 📎
code string Coupon code 📎
descrip string Description 📎
type string Coupon type 📎
discount_item_id integer Item ID # or related discount (if applicable) 📎
enabled boolean Enabled/disabled 📎
discount array Discount details 📎
freetrial array Free trial details 📎
write_datetime datetime Date/time the coupon was created 📎
write_ipaddr datetime IP address that created the coupon 📎

Retrieve a list of coupons

API Request

GET /api/v3/coupon HTTP/1.1
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "coupon_id": 1,
            "code": "TEST",
            "descrip": "t",
            "type": "give-a-discount",
            "enabled": true,
            "write_datetime": "2021-05-25 08:23:05",
            "write_ipaddr": "172.19.0.1",
            "discount_item_id": 673
        },
        {
            "coupon_id": 2,
            "code": "Coupon 2",
            "descrip": "test",
            "type": "give-a-discount",
            "enabled": true,
            "write_datetime": "2022-02-15 13:47:43",
            "write_ipaddr": "172.23.0.1",
            "discount_item_id": 1153
        },
        {
            "coupon_id": 3,
            "code": "Coupon 3",
            "descrip": "tset",
            "type": "free-trial",
            "enabled": true,
            "write_datetime": "2022-02-15 13:47:55",
            "write_ipaddr": "172.23.0.1",
            "discount_item_id": null
        }
    ]
}

Retrieve a specific coupon

Allows you to retrieve a specific coupon based on its coupon_id.

Object Attributes

Attribute Type Description  
coupon_id integer The coupon ID # 📎
code string Coupon code 📎
descrip string Description 📎
type string Coupon type 📎
discount_item_id integer Item ID # or related discount (if applicable) 📎
enabled boolean Enabled/disabled 📎
discount array Discount details 📎
freetrial array Free trial details 📎
write_datetime datetime Date/time the coupon was created 📎
write_ipaddr datetime IP address that created the coupon 📎

Retrieve a specific coupon

API Request

GET /api/v3/coupon/1 HTTP/1.1
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "coupon_id": 1,
        "code": "ABC123",
        "descrip": "10% off your next purchase",
        "type": "give-a-discount",
        "enabled": true,
        "write_datetime": "2021-05-25 08:23:05",
        "write_ipaddr": "172.19.0.1",
        "discount_item_id": 673
    }
}

Currencies

List currencies

Object Attributes

Attribute Type Description  
currency_id integer Currency ID # 📎
currency string Deprecated 📎
name string Currency name 📎
iso4217 string ISO 4217 currency code 📎
symbol string Currency symbol 📎
rounding integer Number of decimal places to round currency fractions to 📎

List currencies

API Request

GET /api/v3/currency
 

API Response

{
    "code":200,
    "status":"OK",
    "message":"",
    "response":[
        {
            "currency_id":1,
            "currency":"United States dollar",
            "iso4217":"USD",
            "symbol":"$",
            "rounding":"2"
        },
        {
            "currency_id":2,
            "currency":"Canadian dollar",
            "iso4217":"CAD",
            "symbol":"CAD$",
            "rounding":"2"
        },
        {
            "currency_id":3,
            "currency":"Pound sterling",
            "iso4217":"GBP",
            "symbol":"\u00c2\u00a3",
            "rounding":"2"
        },
        {
            "currency_id":4,
            "currency":"Euro",
            "iso4217":"EUR",
            "symbol":"\u00e2\u201a\u00ac",
            "rounding":"2"
        }
    ]
}

Set an exchange rate

By default, ChargeOver will automatically set the exchange rate between currencies for you each day.

You only need to manually set the exchange rate if you want to override the exchange rate that ChargeOver updates automatically every day.

Set an exchange rate

API Request

POST /api/v3/currency?action=setExchangeRate
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
 
{
    "from": "USD",
    "to": "CAD",
    "exchange": 1.45
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

Get an exchange rate

Allows you to see what the exchange rate is between two currencies in ChargeOver.

Get an exchange rate

API Request

POST /api/v3/currency?action=getExchangeRate
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
 
{
    "from": "USD",
    "to": "CAD"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": "1.45"
}

Languages

List languages

Object Attributes

Attribute Type Description  
language_id integer Language ID # 📎
language string Language 📎
iso639 string ISO 639 code 📎

List languages

API Request

GET /api/v3/language
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "language_id": 1,
            "language": "English",
            "iso639": "en"
        },
        {
            "language_id": 31,
            "language": "Chinese",
            "iso639": "zh"
        },
        {
            "language_id": 49,
            "language": "French",
            "iso639": "fr"
        },
        ...
    ]
}

Terms

Sales terms specify the number of days an invoice is expected to be paid after the goods are dispatched or service is completed. e.g. NET 30, NET 60, etc.

List terms

Object Attributes

Attribute Type Description  
terms_id integer Terms ID # 📎
name string Terms name 📎
days integer # of days 📎

List terms

API Request

GET /api/v3/terms
 

API Response

HTTP/1.0 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "terms_id": 3,
            "name": "Due on Receipt",
            "days": 0
        },
        {
            "terms_id": 1,
            "name": "Net 15",
            "days": 15
        },
        {
            "terms_id": 2,
            "name": "Net 30",
            "days": 30
        }
    ]
}

Notes

Create a note

Object Attributes

Attribute Type Description  
note string Note text 📎
context_str string The type of object the note is attached to 📎
context_id string The object ID # the note is attached to 📎

Create a note

API Request

POST /api/v3/note HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
 
{
    "note": "Here is my test note",
    "context_str": "customer",
    "context_id": 328
}

API Response

HTTP/1.0 201 Created
Location: https://example.chargeover.com/api/v3/note/126
Content-Type: application/json
 
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 126
    }
}

Querying for notes

Available query parameters:

  • context_str (this should be one of: customer, billing_package, invoice, user, quote, item)
  • context_id

Object Attributes

Attribute Type Description  
note_id integer Note ID # 📎
user_id integer User ID # 📎
admin_id integer Admin ID # 📎
note string Note text 📎
note_is_pinned boolean Whether or not the note was pinned 📎
context_str string The type of object the note is attached to 📎
context_id string The object ID # the note is attached to 📎
note_datetime datetime Date/time the note was created 📎

Querying for notes

API Request

GET /api/v3/note?where=context_str:EQUALS:customer,context_id:EQUALS:265
 

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"details": {},
	"response": [
		{
			"note_id": 3,
			"user_id": null,
			"admin_id": 1,
			"note_is_pinned": false,
			"note_datetime": "2024-02-16 07:46:58",
			"note": "Customer agreed to upgrade to PRO plan.",
			"context_str": "customer",
			"context_id": 265
		},
		{
			"note_id": 4,
			"user_id": null,
			"admin_id": 1,
			"note_is_pinned": false,
			"note_datetime": "2024-02-16 07:47:14",
			"note": "Customer requested billing date be changed from 14th of the month to 12th of the month; credit issues.",
			"context_str": "customer",
			"context_id": 265
		}
	]
}

Admin Workers

Admin workers are administrative users of the ChargeOver backend (e.g. your employees or workers).

The primary key field for admins is admin_id.

Get a list of admin workers

Notes:

Object Attributes

Attribute Type Description  
admin_id integer Admin ID # 📎
username string Username 📎
external_key string External key value 📎
timezone string Timezone 📎
name string Full name 📎
first_name string First Name 📎
last_name string Last Name 📎
initials string Initials 📎
nickname string Nickname 📎
email string Email address 📎
twitter string Twitter URL 📎
facebook string Facebook URL 📎
linkedin string LinkedIn URL 📎
login_count string The # of times the worker has logged in 📎
login_datetime string Last logged in 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎
custom_4 mixed Custom field value #4 📎
custom_5 mixed Custom field value #5 📎
write_datetime date Date/time the admin was created 📎
mod_datetime date Date/time the admin was modified 📎

Get a list of admin workers

API Request

GET /api/v3/admin
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "admin_id": 10,
            "external_key": null,
            "timezone": "America\/Detroit",
            "first_name": "Keith",
            "last_name": "Palmer",
            "initials": null,
            "email": "noreply@chargeover.com",
            "login_datetime": "2015-03-03 22:04:38",
            "write_datetime": "2015-03-03 22:02:37",
            "mod_datetime": "2015-03-03 22:04:36",
            "name": "Keith Palmer",
            "username": "noreply@chargeover.com"
        },
        ...
    ]
}

Query for admin workers

Valid query parameters:

  • admin_id
  • external_key
  • email
  • first_name
  • last_name

Object Attributes

Attribute Type Description  
admin_id integer Admin ID # 📎
username string Username 📎
external_key string External key value 📎
timezone string Timezone 📎
name string Full name 📎
first_name string First Name 📎
last_name string Last Name 📎
initials string Initials 📎
nickname string Nickname 📎
email string Email address 📎
twitter string Twitter URL 📎
facebook string Facebook URL 📎
linkedin string LinkedIn URL 📎
login_count string The # of times the worker has logged in 📎
login_datetime string Last logged in 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎
custom_4 mixed Custom field value #4 📎
custom_5 mixed Custom field value #5 📎
write_datetime date Date/time the admin was created 📎
mod_datetime date Date/time the admin was modified 📎

Query for admin workers

API Request

GET /api/v3/admin/?where=first_name:EQUALS:keith
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "admin_id": 10,
            "external_key": null,
            "timezone": "America\/Detroit",
            "first_name": "Keith",
            "last_name": "Palmer",
            "initials": null,
            "email": "noreply@chargeover.com",
            "login_datetime": "2015-03-03 22:04:38",
            "write_datetime": "2015-03-03 22:02:37",
            "mod_datetime": "2015-03-03 22:04:36",
            "name": "Keith Palmer",
            "username": "noreply@chargeover.com"
        }
    ]
}

Get a specific admin worker

Get an admin by admin_id.

Object Attributes

Attribute Type Description  
admin_id integer Admin ID # 📎
username string Username 📎
external_key string External key value 📎
timezone string Timezone 📎
name string Full name 📎
first_name string First Name 📎
last_name string Last Name 📎
initials string Initials 📎
nickname string Nickname 📎
email string Email address 📎
twitter string Twitter URL 📎
facebook string Facebook URL 📎
linkedin string LinkedIn URL 📎
login_count string The # of times the worker has logged in 📎
login_datetime string Last logged in 📎
custom_1 mixed Custom field value #1 📎
custom_2 mixed Custom field value #2 📎
custom_3 mixed Custom field value #3 📎
custom_4 mixed Custom field value #4 📎
custom_5 mixed Custom field value #5 📎
write_datetime date Date/time the admin was created 📎
mod_datetime date Date/time the admin was modified 📎

Get a specific admin worker

API Request

GET /api/v3/admin/10
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "admin_id": 10,
        "external_key": null,
        "timezone": "America\/Detroit",
        "first_name": "Keith",
        "last_name": "Palmer",
        "initials": null,
        "email": "noreply@chargeover.com",
        "login_datetime": "2015-03-03 22:04:38",
        "write_datetime": "2015-03-03 22:02:37",
        "mod_datetime": "2015-03-03 22:04:36",
        "name": "Keith Palmer",
        "username": "noreply@chargeover.com"
    }
}

ChargeOver.js

The ChargeOver.js REST API components allow you to take advantage of the store/review/commit mode that ChargeOver.js offers.

This provides the ability to hold ChargeOver.js requests in a "pending" state until reviewed further.

Incoming ChargeOver.js requests can be reviewed, and then either committed (saved to the database) or rejected (discarded).

Get a list of pending requests

Get a list of pending ChargeOver.js requests.

Each object will contain a JSON-encoded payload of data submitted via ChargeOver.js.

Get a list of pending requests

API Request

GET /api/v3/_chargeoverjs
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "action": "customer.create",
            "payload": "{\"customer\":{\"company\":\"Test Company, LLC\",\"bill_addr1\":\"56 Cowles Road\",\"bill_addr2\":\"\",\"bill_addr3\":\"\",\"bill_city\":\"Mt Pleasant\",\"bill_state\":\"MI\",\"bill_postcode\":\"48858\",\"bill_country\":\"United States\",\"custom_1\":\"\",\"custom_2\":\"\",\"custom_3\":\"\"},\"user\":{\"name\":\"John Doe\",\"phone\":\"888-924-2347\",\"email\":\"test@ChargeOver.com\"}}",
            "token": "9w5jdiqz1pf7h8ga",
            "chargeoverjs_id": 1
        },
       ...
    ]
}

Commit a ChargeOver.js request

Commit a pending ChargeOver.js request (i.e. actually accept and write the data to ChargeOver).

Commit a ChargeOver.js request

API Request

POST /api/v3/_chargeoverjs HTTP/1.1
Authorization: Basic VjF0dWZnOXZrbFV5d0gwRHFyRnMyNmJqQ1RtN0E4S0U6UEJSSWg4bXF6RXJUMmlrcHVkM1Z0THdYNlcxS283Sk4=
Content-Type: application/json
 
{
    "commit": "9w5jdiqz1pf7h8ga"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "code": 200,
        "errmsgs": [],
        "errfields": [],
        "response": {
            "customer": {
                "superuser_id": 0,
                "external_key": null,
                "token": "kpumnq0w7ec8",
                "company": "Test Company, LLC",
                "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,
                "terms_id": 2,
                "class_id": null,
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "admin_id": null,
                "campaign_id": null,
                "currency_id": 1,
                "no_taxes": false,
                "no_dunning": false,
                "write_datetime": "2015-06-08 11:18:23",
                "write_ipaddr": "172.16.16.11",
                "mod_datetime": "2015-06-08 11:18:23",
                "mod_ipaddr": "172.16.16.11",
                "terms_name": "Net 30",
                "terms_days": 30,
                "paid": 0,
                "total": 0,
                "balance": 0,
                "url_paymethodlink": "http:\/\/haproxy-dev.chargeover.com\/signup\/r\/paymethod\/i\/kpumnq0w7ec8",
                "currency_symbol": "$",
                "currency_iso4217": "USD",
                "display_as": "Test Company, LLC",
                "ship_block": "",
                "bill_block": "56 Cowles Road\nMt Pleasant MI 48858\nUnited States",
                "superuser_name": "",
                "superuser_first_name": "",
                "superuser_last_name": "",
                "superuser_phone": "",
                "superuser_email": "",
                "customer_id": 13
            },
            "user": {
                "user_id": 361,
                "external_key": null,
                "first_name": "John",
                "middle_name_glob": null,
                "last_name": "Doe",
                "name_suffix": null,
                "title": "",
                "email": "test@ChargeOver.com",
                "token": "o4jcubrmy1g2",
                "phone": "888-924-2347",
                "user_type_id": 1,
                "write_datetime": "2015-06-08 11:18:23",
                "mod_datetime": "2015-06-08 11:18:23",
                "name": "John Doe",
                "display_as": "John Doe",
                "user_type_name": "Billing",
                "username": "eb1auzqo0fjm"
            }
        }
    }
}

Reject a ChargeOver.js request

Reject a pending ChargeOver.js request (i.e. discard/do not process the ChargeOver.js request).

Reject a ChargeOver.js request

API Request

POST /api/v3/_chargeoverjs HTTP/1.1
Authorization: Basic VjF0dWZnOXZrbFV5d0gwRHFyRnMyNmJqQ1RtN0E4S0U6UEJSSWg4bXF6RXJUMmlrcHVkM1Z0THdYNlcxS283Sk4=
Content-Type: application/json
 
{
    "reject": "6m4npbichesodlur"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": true
}

Custom Fields

Use these endpoints to get information about custom fields that are defined within ChargeOver.

List custom fields

Possible values for type:

  • string - a single-line free-form text field
  • select - a dropdown/select box offering a specific set of choices
  • date - a date
  • number - a number

If the type is select, available choices will be returned in type_opts.

The field attribute is the API field name you can use to populate custom field data onto an object. For example, if context_str=customer and field=custom_2 then when you create a customer via the REST API, you would send:

POST /api/v3/customer 

{
  "company": "Sombra Corporation", 
  "custom_2": "The Dark Tower"
}

Custom fields are not required, so can be left out of API requests if you do not wish to provide a value.

List custom fields

API Request

GET /api/v3/_customfield
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "context_str": "customer",
            "field": "custom_2",
            "customfield_id": 417,
            "name": "Favorite Book",
            "enabled": true,
            "type": "select",
            "type_opts": [
                "Snow Crash",
                "Perdido Street Station",
                "The Dark Tower",
                "Other"
            ]
        },
        {
            "context_str": "quote",
            "field": "custom_1",
            "customfield_id": 418,
            "name": "Favorite Color",
            "enabled": true,
            "type": "string",
            "type_opts": null
        }
    ]
}

REST Hooks

REST Hooks <RESTHooks.org> is a collection of patterns that treat webhooks like subscriptions.

Your app can subscribe to an event (example: "A customer is created") via the ChargeOver REST API, and instantaneously receive notifications (JSON payloads) via HTTP POST requests whenever that event occurs within ChargeOver.

Viewing your rest hooks

Returns a list of all your subscribed REST Hooks

Viewing your rest hooks

API Request

GET /api/v3/_resthook
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Content-Type: application/json
 

API Response

{
	"code": 200,
	"status": "OK",
	"message": "",
	"details": {},
	"response": [
		{
			"resthook_id": 1,
			"target_url": "http://example.org/your_webhook_url",
			"event": "customer.insert"
		}
	]
}

Subscribing

Subscribing is the process of telling ChargeOver to send webhooks to you whenever a specific event occurs (example: "Send http://example.org/my_webhook_url data whenever a customer is created.").

Once you've subscribed, each time the event occurs within ChargeOver, ChargeOver will send a HTTP POST request to your URL with a JSON payload of the event data.

Please refer to our webhooks documentation to see the JSON payloads your webhook URL will receive.

Subscribing

API Request

POST /api/v3/_resthook
 
{
    "target_url": "http:\/\/example.org\/your_webhook_url",
    "event": "customer.insert"
}

API Response

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

Unsubscribing

Unsubscribing is the process of telling ChargeOver to stop sending webhooks to a specific URL.

Unsubscribing

API Request

DELETE /api/v3/_resthook/6
 

API Response

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

Integrations

Use these endpoints to push and pull data relating ChargeOver records to integrated application records.

Query for map values

Query for a list of mapped values (e.g. which Salesforce record corresponds to this ChargeOver record?)

Query for map values

API Request

GET http://dev1.chargeover.com/api/v3/_integration_map?where=integration:EQUALS:qbonline HTTP/1.1
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": [
        {
            "integration": "qbonline",
            "context_str": "customer",
            "context_id": 3759,
            "integration_guid": "{-1234}"
        },
        {
            "integration": "qbonline",
            "context_str": "invoice",
            "context_id": 3,
            "integration_guid": "{-2345}"
        },
        {
            "integration": "qbonline",
            "context_str": "customer",
            "context_id": 3760,
            "integration_guid": "{-123x}"
        }
    ]
}

Add a map record

Add a map record (e.g. map a specific Salesforce record to a specific ChargeOver record)

Add a map record

API Request

POST http://dev1.chargeover.com/api/v3/_integration_map?action=addMap HTTP/1.1
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
 
{
    "integration": "salesforce",
    "context_str": "customer",
    "context_id": 3760,
    "integration_guid": "5003000000D8cuI"
}

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": true
}

System Log

The ChargeOver system log contains warnings and other notifications about notable events happening within ChargeOver. This may include notifictaions about webhook URLs failing, usage URLs failing, etc.

Retrieve the system log

Retrieve a list of log entries.

Retrieve the system log

API Request

GET /api/v3/_log_system
 

API Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": [
        {
            "log_id": 1,
            "msg": "Webhook 2: http:\/\/www.example.com\/tasdgadg.php returned a non-200 OK response: 301",
            "log_datetime": "2015-10-31 15:02:47"
        },
        {
            "log_id": 2,
            "msg": "Webhook 2: http:\/\/www.example.com\/tasdgadg.php returned a non-200 OK response: 301",
            "log_datetime": "2015-10-31 15:02:48"
        }
    ]
}

Reports

Reporting

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

Get a specific report for more details on the available filters and columns in the report.

Get a Specific Report

API Request

GET /api/v3/_report/141
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
 

API Response

HTTP/1.1 200 OK
Content-Type: application/json
 
{
    "code": 200,
    "status": "OK",
    "message": "",
    "details": {},
    "response": {
        "name": "Example Report Name",
        "report_id": 141,
        "available_filters": {
            "invoice_invoice_date": {
                "ops": [
                    "GTE",
                    "LTE"
                ]
            },
            "customer_customer_id": {
                "ops": [
                    "EQUALS"
                ]
            }
        }
    }
}

Run a report / report data

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=customer_customer_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&order=customer_customer_id:ASC

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.

Run a report / report data

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
    }
}
0.015 (cache) on Mon, 18 Mar 2024 22:31:37 -0500