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 navigate to this menu option:
  2. Configuration > API & Web Hooks
  3. Enable the API, and find your API endpoint at the bottom of the screen. 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 SSL/HTTPS connection. In addition to the point-to-point encryption SSL/HTTPS provides, ChargeOver offers two different options for authentication.

The easiest way to get started with the API is to use standard "HTTP Basic Auth". This uses the industry-standard HTTP authentication to authenticate access to the REST API.

If you need more security, ChargeOver also offers a signed, HMAC-SHA256 based authentication method. The advantages of the signature-based approach are:

  • Protection against replay attacks
  • Verification that the API request you sent was not altered during transport
  • No need to transmit your private API key over the wire

We recommend you develop using HTTP basic auth, and then migrate to using signatures in production environments.

Libraries/Code

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

PHP

Python

Java

C# / .NET

Querying/Filtering

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.

Querying/Filtering

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

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)

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

?offset=10&limit=15
(starting at record 10, fetch the next 15 records)

Querying/Filtering

JSON Request


// 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

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

JSON Request

// 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

JSON Response

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

External Keys

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

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

External Key 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

JSON Request


// 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

JSON Request


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

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

JSON Request

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

JSON 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

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

JSON Response

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

Reporting/Aggregation

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

Get a List of Reports

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

Get a List of Reports

JSON Request

GET /api/v3/_report
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Host: dev.chargeover.com
Content-Type: application/json

JSON 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

Allows you to get the data from a specific report using its report_id.

Get a Specific Report

JSON Request

POST /api/v3/_report/58?action=getData
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Host: dev.chargeover.com
Content-Type: application/json
  

[
    "transaction_transaction_date:GTE:2017-04-01",
    "transaction_transaction_date:LTE:2017-06-07"
]

JSON Response

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

{
  "code": 200,
  "status": "OK",
  "message": "",
  "details": {},
  "response": { 
    "_report": [
     
 {
        "transaction_transaction_date": "2017-04-11",
        "transaction_transaction_method": "ACH/eCheck",
        "transaction_transaction_detail": "x6667",
        "transaction_amount": 32.85,
        "transaction_gateway_transid": "*DEBIT: Test ACH/eCheck* [1491944216]",
        "transaction_transaction_type": "pay"
      },
      {
        "transaction_transaction_date": "2017-04-11",
        "transaction_transaction_method": "ACH/eCheck",
        "transaction_transaction_detail": "x6667",
        "transaction_amount": 10.95,
        "transaction_gateway_transid": "*DEBIT: Test ACH/eCheck* [1491945325]",
        "transaction_transaction_type": "pay"
      },
      {
        "transaction_transaction_date": "2017-06-07",
        "transaction_transaction_method": "Visa",
        "transaction_transaction_detail": "x1111",
        "transaction_amount": 21.9,
        "transaction_gateway_transid": "*CHARGE: Test Credit Card* [1496858593]",
        "transaction_transaction_type": "pay"
     
      }
    ]
  }
}

Rate Limits

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

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

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

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

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

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

HTTP Status Codes

The API follows these rules for HTTP requests:

  • If you are creating new objects, use a POST.
  • If you are updating an existing object, use a PUT.
  • If you are trying to get a particular object by id, use a GET.
  • If you are trying to get a list of objects, or query for a list of objects, use a GET.
  • If you are calling an action (e.g. pay an invoice, reset a password, etc.), use a POST.
The API follows these rules for HTTP response codes:
  • If you successfully create an object, you'll get back a 201 Created HTTP response. You'll also get back a Location: header with the URL of the new object.
  • If you successfully update an object, you'll get back a 202 Accepted HTTP response. You'll also get back a Location: header with the URL of the new object.
  • If you successfully get a specific object, you'll get back a 200 OK HTTP response.
  • If you try to get a specific object that doesn't exist, you'll get back a 404 Not Found HTTP response.
  • If you query for objects, you'll get back a 200 OK HTTP response.
  • If you successfully call an action, you'll get back a 200 OK HTTP response.
  • If you do something wrong (e.g. send an invalid JSON request, hit an invalid endpoint, etc.) you will get back a 400 Bad Request HTTP response.
  • If your authentication parameters are incorrect, you will get back a 401 Unauthorized HTTP response.
  • If you exceed the REST API rate limits, you will get back a 429 Too Many Requests HTTP response.
  • If something goes wrong with ChargeOver itself, you will get back a 500 Internal Server Error HTTP response.

Objects

The ChargeOver object model is documented below.

Customers

The primary key field for customers is customer_id.

Create a customer

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

Object Attributes

Attribute Type Description  
parent_customer_id integer Parent customer ID # 📎
superuser_id integer Main contact ID # 📎
external_key string External key value 📎
company string Company/customer name 📎
language_id integer Language ID # 📎
currency_id integer Currency ID # 📎
terms_id integer Default terms ID # 📎
class_id integer Default class tracking ID # 📎
admin_id integer Admin/Worker ID # 📎
campaign_id integer Campaign/lead source ID # 📎
campaign_details string Campaign/lead source details 📎
custtype_id integer Customer type ID # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
superuser_username string Main contact username 📎
superuser_email string Main contact e-mail address 📎
superuser_name string Main contact name 📎
superuser_first_name string Main contact first name 📎
superuser_last_name string Main contact last name 📎
superuser_phone string Main contact phone number 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state/province 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
ship_addr1 string Shipping address line 1 📎
ship_addr2 string Shipping address line 2 📎
ship_addr3 string Shipping address line 3 📎
ship_city string Shipping address city 📎
ship_state string Shipping address state 📎
ship_postcode string Shipping address postal code 📎
ship_country string Shipping address country 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
custom_6 string Custom field #6 📎
brand_id integer Brand ID # 📎
invoice_delivery enum Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎

Create a customer

JSON Request

POST /api/v3/customer HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Host: dev.chargeover.com
Content-Type: application/json
  
{
    "company": "Test Company Name",
    "bill_addr1": "16 Dog Lane",
    "bill_addr2": "Suite D",
    "bill_city": "Storrs",
    "bill_state": "CT"
}

JSON Response

HTTP/1.0 201 Created
Location: http://dev.chargeover.com/api/v3/customer/1541
Content-Type: application/json
  
{
    "code": 201,
    "status": "OK",
    "message": "",
    "response": {
        "id": 1541
    }
}

Update a customer

Object Attributes

Attribute Type Description  
superuser_id integer Main contact ID # 📎
external_key string External key value 📎
company string Company/customer name 📎
language_id integer Language ID # 📎
terms_id integer Default terms ID # 📎
class_id integer Default class tracking ID # 📎
admin_id integer Admin/Worker ID # 📎
campaign_id integer Campaign/lead source ID # 📎
custtype_id integer Customer type ID # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
superuser_email string Main contact e-mail address 📎
superuser_name string Main contact name 📎
superuser_first_name string Main contact first name 📎
superuser_last_name string Main contact last name 📎
superuser_phone string Main contact phone number 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state/province 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
ship_addr1 string Shipping address line 1 📎
ship_addr2 string Shipping address line 2 📎
ship_addr3 string Shipping address line 3 📎
ship_city string Shipping address city 📎
ship_state string Shipping address state 📎
ship_postcode string Shipping address postal code 📎
ship_country string Shipping address country 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
custom_6 string Custom field #6 📎
invoice_delivery enum Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎

Update a customer

JSON Request

PUT https://dev.chargeover.com/api/v3/customer/3
  
{
  "company": "Test API Company, LLC",
  
  "bill_addr1": "220 ChargeOver Street",
  "bill_addr2": "Suite 10",
  "bill_city": "Minneapolis",
  "bill_state": "MN",
  "bill_postcode": "55416",
  "bill_country": "USA",

  "external_key": "abcd3325",
  
  "superuser_name": "David Palmer",
  "superuser_email": "david@palmer.com",
  "superuser_phone": "860-634-1111"
}

JSON 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.) 📎
terms_id integer Default terms ID # 📎
class_id integer Default class tracking ID # 📎
admin_id integer Admin/Worker ID # 📎
campaign_id integer Campaign/lead source ID # 📎
custtype_id integer Customer type ID # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
superuser_username string Main contact username 📎
superuser_email string Main contact e-mail address 📎
superuser_name string Main contact name 📎
superuser_first_name string Main contact first name 📎
superuser_last_name string Main contact last name 📎
superuser_phone string Main contact phone number 📎
superuser_token string Main contact token 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state/province 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_block string Printable billing address 📎
ship_addr1 string Shipping address line 1 📎
ship_addr2 string Shipping address line 2 📎
ship_addr3 string Shipping address line 3 📎
ship_city string Shipping address city 📎
ship_state string Shipping address state 📎
ship_postcode string Shipping address postal code 📎
ship_country string Shipping address country 📎
ship_block string Printable shipping address 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
custom_6 string Custom field #6 📎
total float The sum total amount of all invoices ever issued to this customer 📎
balance float Balance due for this customer 📎
paid float The sum total amount of all payments ever made by this customer 📎
write_datetime string Date/time this customer was created 📎
write_ipaddr string IP address that created this customer 📎
mod_datetime string Date/time this customer was updated 📎
mod_ipaddr string IP address that last updated this customer 📎
brand_id integer Brand ID # 📎
terms_name string Default payment terms 📎
terms_days integer # of days for the default payment terms 📎
url_paymethodlink string URL the customer can visit to update their payment method 📎
url_self string URL for viewing the customer in the GUI 📎
admin_name string Admin/Worker Name 📎
admin_email string Admin/Worker Email 📎
customer_status_id string 📎
customer_status_name string Human-friendly customer status 📎
customer_status_str string Status string 📎
customer_status_state string Status code 📎
invoice_delivery enum Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎

Get a list of customers

JSON Request

GET /api/v3/customer

JSON Response

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

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
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.) 📎
terms_id integer Default terms ID # 📎
class_id integer Default class tracking ID # 📎
admin_id integer Admin/Worker ID # 📎
campaign_id integer Campaign/lead source ID # 📎
custtype_id integer Customer type ID # 📎
no_taxes boolean Flag to disable charging of taxes 📎
no_dunning boolean Flag to disable dunning 📎
superuser_username string Main contact username 📎
superuser_email string Main contact e-mail address 📎
superuser_name string Main contact name 📎
superuser_first_name string Main contact first name 📎
superuser_last_name string Main contact last name 📎
superuser_phone string Main contact phone number 📎
superuser_token string Main contact token 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state/province 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_block string Printable billing address 📎
ship_addr1 string Shipping address line 1 📎
ship_addr2 string Shipping address line 2 📎
ship_addr3 string Shipping address line 3 📎
ship_city string Shipping address city 📎
ship_state string Shipping address state 📎
ship_postcode string Shipping address postal code 📎
ship_country string Shipping address country 📎
ship_block string Printable shipping address 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
custom_6 string Custom field #6 📎
total float The sum total amount of all invoices ever issued to this customer 📎
balance float Balance due for this customer 📎
paid float The sum total amount of all payments ever made by this customer 📎
write_datetime string Date/time this customer was created 📎
write_ipaddr string IP address that created this customer 📎
mod_datetime string Date/time this customer was updated 📎
mod_ipaddr string IP address that last updated this customer 📎
brand_id integer Brand ID # 📎
terms_name string Default payment terms 📎
terms_days integer # of days for the default payment terms 📎
url_paymethodlink string URL the customer can visit to update their payment method 📎
url_self string URL for viewing the customer in the GUI 📎
admin_name string Admin/Worker Name 📎
admin_email string Admin/Worker Email 📎
customer_status_id string 📎
customer_status_name string Human-friendly customer status 📎
customer_status_str string Status string 📎
customer_status_state string Status code 📎
invoice_delivery enum Delivery method for initial invoices ("email" or "print" for printed hard-copy) 📎
dunning_delivery enum Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) 📎

Query for customers

JSON Request

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

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

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

JSON Request

DELETE /api/v3/customer/1553 HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSj...
Host: dev.chargeover.com

JSON 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

JSON Request

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

JSON 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

JSON Request

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

JSON 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 📎
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 📎
user_type_id integer User type ID # 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎

Add a contact

JSON Request

POST /api/v3/user HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo...
Host: dev.chargeover.com
Content-Type: application/json
  
{
  "customer_id": 21,
  "username": "my_test_username_393",
  "password": "some test password",
  "name": "Ryan Bantz",
  "email": "ryan@adgadgagadg.com",
  "phone": "888-555-1212"
}

JSON Response

HTTP/1.0 201 Created
Location: http://dev.chargeover.com/api/v3/user/379
Content-Type: application/json
  
{
        "code": 201,
        "status": "OK",
        "message": "",
        "response": {
            "id": 379
        }
    }

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 📎
user_type_id integer User type ID # 📎
user_type_name string User type 📎
customer_id integer The customer ID # this contact belongs to 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
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

JSON Request

GET /api/v3/user/362

JSON 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 📎
user_type_id integer User type ID # 📎
user_type_name string User type 📎
customer_id integer The customer ID # this contact belongs to 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
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

JSON Request

GET /api/v3/user

JSON 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
  • 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 📎
user_type_id integer User type ID # 📎
user_type_name string User type 📎
customer_id integer The customer ID # this contact belongs to 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
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

JSON Request

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

JSON 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

JSON Request

POST /api/v3/user/372?action=password HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: CHANGE-THIS.chargeover.com

JSON Response

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

Set a password

Set a password

JSON Request

POST /api/v3/user/372?action=password HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: CHANGE-THIS.chargeover.com
  
{
        "password": "here is the new password"
}

JSON Response

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

Log in a user

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

Log in a user

JSON Request

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

JSON Response

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

Delete a contact

Delete a contact

JSON Request

DELETE /api/v3/user/362

JSON 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 # 📎
terms_id integer Terms ID # 📎
admin_id integer Admin/Worker ID # 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_notes string 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
memo string Memo/notes to customer 📎
line_items array A list of line items for the invoice 📎

Create an invoice

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

JSON Response

HTTP/1.0 201 Created
Location: http://dev.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  
refnumber string Invoice reference number 📎
external_key string External key value 📎
terms_id integer Terms ID # 📎
admin_id integer Admin/Worker ID # 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_notes string 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
memo string Memo/notes to customer 📎
line_items array A list of line items for the invoice 📎

Update an invoice

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

JSON Response

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

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 # 📎
write_datetime datetime Date/time the invoice was created 📎
void_datetime datetime Date/time the invoice was voided 📎
date date Invoice date 📎
currency_id integer Currency ID # 📎
currency_symbol string Currency symbol 📎
currency_iso4217 string Currency ISO 4217 representation 📎
terms_id integer Terms ID # 📎
terms_name string Terms name 📎
terms_days integer Terms # of days 📎
admin_id integer Admin/Worker ID # 📎
admin_name string Admin/Worker Name 📎
token string Unique token 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_notes string 📎
bill_block string Printable billing address 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
ship_block string 📎
cycle_pre_from_date date For pre-billing, cycle start date 📎
cycle_pre_to_date date For pre-billing, cycle end date 📎
cycle_this_date date Cycle date (generally the invoice date) 📎
cycle_post_from_date date For post-billing (in arrears), cycle start date 📎
cycle_post_to_date date For post-billing (in arrears), cycle end date 📎
url_permalink string URL to view the invoice 📎
url_pdflink string URL to download the invoice PDF 📎
url_paylink string URL to pay for the invoice 📎
url_self string URL for viewing the invoice in the GUI 📎
is_paid boolean Whether or not the invoice has been paid 📎
is_void boolean Whether or not the invoice has been voided 📎
is_overdue boolean Whether or not the invoice is overdue 📎
due_date date Date the invoice is due 📎
days_overdue integer # of days overdue the invoice is 📎
paid_date date Date this invoice was paid 📎
balance float Balance of the invoice 📎
applied float Amount applied to the invoice 📎
total float Invoice total 📎
subtotal float Invoice subtotal 📎
taxes float Taxes 📎
credits float Amount of credits applied to the invoice 📎
payments float Amount of payments applied to the invoice 📎
writeoffs float Amount written off 📎
declines integer # of times that payment was attempted and failed for this invoice 📎
sum_base float 📎
sum_usage float 📎
sum_onetime float 📎
invoice_status_name string Human-friendly invoice status 📎
invoice_status_str string Status string 📎
invoice_status_state string Status code 📎
memo string Memo/notes to customer 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
line_items array A list of line items for the invoice 📎

Get a specific invoice

JSON Request

GET /api/v3/invoice/10643

JSON Response

{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "invoice_id": 10643,
        "currency_id": 1,
        "terms_id": 2,
        "admin_id": 3,
        "token": "a1719w4r1ozc",
        "refnumber": "10643",
        "cycle_pre_from_date": "2015-12-20",
        "cycle_pre_to_date": "2016-01-19",
        "cycle_this_date": "2015-12-20",
        "cycle_post_from_date": "2015-11-20",
        "cycle_post_to_date": "2015-12-19",
        "bill_addr1": "72 E Blue Grass Road",
        "bill_addr2": "Suite D",
        "bill_addr3": null,
        "bill_city": "Willington",
        "bill_state": "CT",
        "bill_postcode": "06279",
        "bill_country": "United States",
        "bill_notes": null,
        "ship_addr1": null,
        "ship_addr2": null,
        "ship_addr3": null,
        "ship_city": null,
        "ship_state": null,
        "ship_postcode": null,
        "ship_country": null,
        "ship_notes": null,
        "custom_1": null,
        "custom_2": null,
        "custom_3": null,
        "write_datetime": "2015-12-20 08:00:54",
        "void_datetime": null,
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "admin_name": "Ford Prefect",
        "invoice_status_name": "Unpaid",
        "invoice_status_str": "open-unpaid",
        "invoice_status_state": "o",
        "subtotal": 15.95,
        "total": 15.95,
        "taxes": 0,
        "credits": 0,
        "payments": 0,
        "applied": 0,
        "sum_base": 15.95,
        "sum_usage": 0,
        "sum_onetime": 0,
        "is_paid": false,
        "balance": 15.95,
        "is_void": false,
        "due_date": "2016-01-19",
        "terms_name": "Net 30",
        "terms_days": 30,
        "days_overdue": 0,
        "is_overdue": false,
        "date": "2015-12-20",
        "delay_datetime": null,
        "bill_block": "72 E Blue Grass Road\r\nSuite D\r\nWillington, CT 06279\r\nUnited States",
        "ship_block": "",
        "url_permalink": "https:\/\/dev.chargeover.com\/r\/invoice\/view\/a1719w4r1ozc",
        "url_paylink": "https:\/\/dev.chargeover.com\/r\/trans\/pay\/a1719w4r1ozc",
        "url_pdflink": "https:\/\/dev.chargeover.com\/r\/invoice\/pdf\/a1719w4r1ozc",
        "package_id": 708,
        "customer_id": 179,
        "line_items": [
            {
                "invoice_id": 10643,
                "item_id": 295,
                "tierset_id": 309,
                "descrip": "Monthly mountain moving service",
                "line_rate": 15.95,
                "line_quantity": 1,
                "line_prorate": 1,
                "line_usage": 0,
                "usage_from": 0,
                "usage_to": 0,
                "tax_id": null,
                "tax_group_id": null,
                "tax_taxable": 15.95,
                "tax_taxed": 0,
                "tax_total": 0,
                "is_base": true,
                "is_free": false,
                "is_setup": false,
                "is_usage": false,
                "is_recurring": true,
                "is_taxed": "0",
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "item_name": "Monthly Mountain Moving",
                "item_external_key": null,
                "item_token": "4zljsft146y0",
                "item_accounting_sku": null,
                "item_units": null,
                "tax_name": null,
                "tax_group_name": null,
                "line_subtotal": 15.95,
                "line_total": 15.95,
                "line_item_id": 3280,
                "package_line_id": 850
            }
        ]
    }
}

Query for invoices

Available query parameters:

  • 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

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 # 📎
write_datetime datetime Date/time the invoice was created 📎
void_datetime datetime Date/time the invoice was voided 📎
date date Invoice date 📎
currency_id integer Currency ID # 📎
currency_symbol string Currency symbol 📎
currency_iso4217 string Currency ISO 4217 representation 📎
terms_id integer Terms ID # 📎
terms_name string Terms name 📎
terms_days integer Terms # of days 📎
admin_id integer Admin/Worker ID # 📎
admin_name string Admin/Worker Name 📎
token string Unique token 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_notes string 📎
bill_block string Printable billing address 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
ship_block string 📎
cycle_pre_from_date date For pre-billing, cycle start date 📎
cycle_pre_to_date date For pre-billing, cycle end date 📎
cycle_this_date date Cycle date (generally the invoice date) 📎
cycle_post_from_date date For post-billing (in arrears), cycle start date 📎
cycle_post_to_date date For post-billing (in arrears), cycle end date 📎
url_permalink string URL to view the invoice 📎
url_pdflink string URL to download the invoice PDF 📎
url_paylink string URL to pay for the invoice 📎
url_self string URL for viewing the invoice in the GUI 📎
is_paid boolean Whether or not the invoice has been paid 📎
is_void boolean Whether or not the invoice has been voided 📎
is_overdue boolean Whether or not the invoice is overdue 📎
due_date date Date the invoice is due 📎
days_overdue integer # of days overdue the invoice is 📎
paid_date date Date this invoice was paid 📎
balance float Balance of the invoice 📎
applied float Amount applied to the invoice 📎
total float Invoice total 📎
subtotal float Invoice subtotal 📎
taxes float Taxes 📎
credits float Amount of credits applied to the invoice 📎
payments float Amount of payments applied to the invoice 📎
writeoffs float Amount written off 📎
declines integer # of times that payment was attempted and failed for this invoice 📎
sum_base float 📎
sum_usage float 📎
sum_onetime float 📎
invoice_status_name string Human-friendly invoice status 📎
invoice_status_str string Status string 📎
invoice_status_state string Status code 📎
memo string Memo/notes to customer 📎
custom_1 string Custom field #1 📎
custom_2 string Custom field #2 📎
custom_3 string Custom field #3 📎
custom_4 string Custom field #4 📎
custom_5 string Custom field #5 📎
line_items array A list of line items for the invoice 📎

Query for invoices

JSON Request

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

JSON 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": "http:\/\/dev.chargeover.com\/signup\/\/index.php?stage=cocinvoices\/viewPublic&token=67889778d7a2b2e9e866fdaaddb1c84c",
            "url_pdflink": "http:\/\/dev.chargeover.com\/signup\/\/index.php?stage=cocinvoices\/pdf&token=67889778d7a2b2e9e866fdaaddb1c84c",
            "customer_id": "1"
        }
    ]
}

Credit card payment (specify card details)

Credit card payment (specify card details)

JSON Request

POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json
  
{
    "number": "4111 1111 1111 1111",
    "expdate_year": "2017",
    "expdate_month": "08",
    "name": "Keith Palmer",
    "address": "72 E Blue Grass Road",
    "city": "Willington",
    "state": "CT",
    "postcode": "06279",
    "country": "United States"
}

JSON 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)

JSON Request

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

JSON 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

JSON Request

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

JSON 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

JSON Request

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

JSON Response

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

Email an invoice

Send an invoice via e-mail.

Email an invoice

JSON Request

POST /api/v3/invoice/13011?action=email
  
{
    // Each of these is OPTIONAL, and can be used to over-ride the default email templates, etc.

    // "email": "johndoe@send-invoice-to.com",
    // "subject": "Test subject",
    // "body": "Override the default message body here",
    // "from": "you@your-company.com",

    // "template_name": "mandrill-template-name",
    // "template_opts": "merge_language=handlebars"    
}

JSON Response

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

Transactions (Payments, Refunds, Credits)

Create a 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 An error message or note from the payment gateway 📎
external_key string Transaction external key value 📎
amount float Total transaction amount (refunds will be negative) 📎
transaction_date date Date of the transaction 📎
transaction_type string Transaction type (one of: pay, ref, cre) 📎
transaction_method string Transaction method 📎
transaction_detail string Transaction details 📎
transaction_datetime datetime Date/time of the transaction was created 📎
void_datetime datetime Date/time the transaction was voided 📎

Create a payment

JSON Request

POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json
  
{
	"customer_id": 1,
	"gateway_id": 1,
	"gateway_status": 1,
	"gateway_transid": "abcd1234",
	"gateway_msg": "test gateway message",
	"gateway_method": "check",
	"amount": 15.95,
	"transaction_type": "pay",
	"transaction_detail": "here are some details",
	"transaction_datetime": "2013-06-20 18:48:17",


	"_comment": "You can specify which invoices to apply the payments to...",
	"applied_to": [
		{
			"invoice_id": 16891
		}
	],


	"_comment": "... or be even more specific, and tell ChargeOver what ",
	"_comment": "    invoices to apply the payments to, and what amounts/splits",
	"_comment": "    to apply to each of the invoices...",
	"applied_to": [
		{
			"invoice_id": 10071,
			"applied": 10.95
		},
		{
			"invoice_id": 10072,
			"applied": 5.0
		}
	],


	"_comment": "... or just tell ChargeOver to auto-apply it to the oldest, ", 
	"_comment": "	newest, or 'best fit' invoices (based on amount/date).",
	"auto_apply": "oldest_first", 
	"auto_apply": "newest_first", 
	"auto_apply": "best_fit", 
}

JSON Response

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

Get a specific transaction

Object Attributes

Attribute Type Description  
transaction_id integer Transaction ID # 📎
customer_id integer Customer ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_status integer Payment gateway status (1 for success, 0 for failure) 📎
gateway_transid string Payment gateway transaction identifier 📎
gateway_method string Payment gateway method 📎
gateway_msg string An error message or note from the payment gateway 📎
gateway_err_code integer 📎
gateway_err_detail string 📎
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) 📎
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 📎

Get a specific transaction

JSON Request

GET /api/v3/transaction/92

JSON Response

HTTP/1.1 200 OK
Content-Type: application/json
  
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "transaction_id": 92,
        "gateway_id": 204,
        "currency_id": 1,
        "token": "rx2oa38tpubq",
        "transaction_date": "2015-03-02",
        "gateway_status": 1,
        "gateway_transid": "68fcht",
        "gateway_msg": "",
        "amount": 3.98,
        "fee": 0,
        "transaction_type": "pay",
        "transaction_method": "Mastercard",
        "transaction_detail": "x5454",
        "transaction_datetime": "2015-03-02 18:40:16",
        "void_datetime": null,
        "transaction_type_name": "Payment",
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "customer_id": 1,
        "applied_to": [
            {
                "invoice_id": "10004",
                "applied": 3.98
            }
        ]
    }
}

List transactions

Object Attributes

Attribute Type Description  
transaction_id integer Transaction ID # 📎
customer_id integer Customer ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_status integer Payment gateway status (1 for success, 0 for failure) 📎
gateway_transid string Payment gateway transaction identifier 📎
gateway_method string Payment gateway method 📎
gateway_msg string An error message or note from the payment gateway 📎
gateway_err_code integer 📎
gateway_err_detail string 📎
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) 📎
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 📎

List transactions

JSON Request

GET /api/v3/transaction

JSON 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
  • 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 # 📎
customer_id integer Customer ID # 📎
gateway_id integer Payment gateway ID # 📎
gateway_status integer Payment gateway status (1 for success, 0 for failure) 📎
gateway_transid string Payment gateway transaction identifier 📎
gateway_method string Payment gateway method 📎
gateway_msg string An error message or note from the payment gateway 📎
gateway_err_code integer 📎
gateway_err_detail string 📎
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) 📎
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 📎

Query for transactions

JSON Request

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

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

Attempt a payment

Attempt to make a payment for a customer.

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.

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.

Attempt a payment

JSON Request

POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json
  
{
    "customer_id": 1,

    "_comment": "Optional: You can optionally supply an 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,
    
    "_comment": "Optional: You can optionally supply a list of invoice_id values to apply this payment to",
    "applied_to": [
        {
            "invoice_id": 16891
        }
    ],

    "_comment": "Optional: You can optionally specify a list of payment methods to attempt, otherwise the already stored credit cards/bank accounts for the customer will be used",
    "paymethods": [
        
        {
            "creditcard_id": 1234
        },
        {
            "ach_id": 1235
        }
    ]
}

JSON Response

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

Create a refund

A refund transaction is used to indicate a payment has been refunded.

Note: This does not actually refund a credit card or an ACH account. If you're trying to do that, please see the attempt a refund endpoint.

Notes:

  • The transaction_type value MUST be ref
  • The gateway_status value should be either 1 (to indicate the refund was successful) or 0 (zero, to log a refund that failed)

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 An error message or note from the payment gateway 📎
external_key string Transaction external key value 📎
amount float Total transaction amount (refunds will be negative) 📎
transaction_date date Date of the transaction 📎
transaction_type string Transaction type (one of: pay, ref, cre) 📎
transaction_method string Transaction method 📎
transaction_detail string Transaction details 📎
transaction_datetime datetime Date/time of the transaction was created 📎
void_datetime datetime Date/time the transaction was voided 📎

Create a refund

JSON Request

POST http://dev.chargeover.com/api/v3/transaction
  
{
  "customer_id": 83,
  "gateway_status": 1,
  "gateway_transid": "abcd1234",
  "gateway_msg": "My test message",
  "gateway_method": "visa",
  "amount": -50,
  "transaction_type": "ref",
  "transaction_method": "Visa",
  "transaction_detail": "",
  "transaction_date": "2016-08-16",
  "applied_to": [
    {
      "invoice_id": 10099,
      "applied": -50
    }
  ]
}

JSON Response

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

Refund a payment

Attempt to refund a previously made payment.

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

Refund a payment

JSON Request

POST /api/v3/transaction/206?action=refund HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Host: dev.chargeover.com
Content-Type: application/json
  
{
    "_comment": "You can optionally supply an amount (if you don't specify an amount, the full amount of the original payment will be refunded)",
    "amount": 15.95,
}

JSON Response

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

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

JSON Request

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

JSON Response

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

Email a receipt

Send a payment receipt, or payment failure notification, via e-mail.

Email a receipt

JSON Request

POST /api/v3/transaction/65?action=email
  
{
    // Each of these is OPTIONAL, and can be used to over-ride the default email templates, etc.

    // "email": "johndoe@send-invoice-to.com",
    // "subject": "Test subject",
    // "body": "Override the default message body here",
    // "from": "you@your-company.com",

    // "template_name": "mandrill-template-name",
    // "template_opts": "merge_language=handlebars"
}

JSON Response

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

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.

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 package 📎
paymethod string Payment method for the package, one of: cre, inv, ach 📎
creditcard_id integer Credit card ID # (if the package is paid by credit card) 📎
ach_id integer ACH ID # (if the package is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the package 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 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
holduntil_datetime datetime Date/time invoicing for this package is being held until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
custom_1 string Custom field value #1 📎
custom_2 string Custom field value #2 📎
custom_3 string Custom field value #3 📎
custom_4 string Custom field value #4 📎
custom_5 string Custom field value #5 📎
line_items array 📎

Create a subscription

JSON Request

POST /api/v3/package HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
  
{
    "customer_id": 5,       // The customer the package is for 
    //"customer_token": ...
    //"customer_external_key": ...
    
    //"external_key": ...     // (optional) An external key for the package
    //"nickname": ...         // (optional) An optional nick-name
    //"terms_id": ...
             
    //"paycycle": ...         // (optional) A "paycycle" choice: 
    //      "mon"             //   monthly
    //      "yrl"             //   yearly
    //      "1wk"             //   weekly
    //      "2wk"             //   every 2 weeks
    //      "qtr"             //   quarterly
    
    //"custom_1": ...         // (optional) Custom field value
    //"custom_2": ...         // (optional) Custom field value
    //"custom_3": ...         // (optional) Custom field value
    
    "holduntil_datetime": "2013-10-01",
    
    "line_items": [
        {
            "item_id": 239,
            "descrip": "Here is a description for my line item.",
            "line_quantity": 15
        }
    ]
}

JSON 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 package 📎
paymethod string Payment method for the package, one of: cre, inv, ach 📎
creditcard_id integer Credit card ID # (if the package is paid by credit card) 📎
ach_id integer ACH ID # (if the package is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the package 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 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
holduntil_datetime datetime Date/time invoicing for this package is being held until 📎
terms_id integer Terms ID # 📎
paycycle string Payment cycle 📎
custom_1 string Custom field value #1 📎
custom_2 string Custom field value #2 📎
custom_3 string Custom field value #3 📎
custom_4 string Custom field value #4 📎
custom_5 string Custom field value #5 📎
line_items array 📎

Create a subscription (custom pricing)

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

JSON Response

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

Update a subscription

Object Attributes

Attribute Type Description  
class_id integer Class ID # 📎
external_key string External key value 📎
nickname string Nickname for the package 📎
admin_id integer Admin/worker ID # 📎
bill_addr1 string Billing address line 1 📎
bill_addr2 string Billing address line 2 📎
bill_addr3 string Billing address line 3 📎
bill_city string Billing address city 📎
bill_state string Billing address state 📎
bill_postcode string Billing address postal code 📎
bill_country string Billing address country 📎
bill_notes string 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
terms_id integer Terms ID # 📎
custom_1 string Custom field value #1 📎
custom_2 string Custom field value #2 📎
custom_3 string Custom field value #3 📎
custom_4 string Custom field value #4 📎
custom_5 string Custom field value #5 📎

Update a subscription

JSON Request

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

JSON Response

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

Get a specific subscription

Object Attributes

Attribute Type Description  
package_id integer Package ID # 📎
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
token string Unique token 📎
nickname string Nickname for the package 📎
paymethod string Payment method for the package, one of: cre, inv, ach 📎
creditcard_id integer Credit card ID # (if the package is paid by credit card) 📎
ach_id integer ACH ID # (if the package is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the package 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 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
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 package 📎
amount_invoiced float Total amount invoiced so far 📎
amount_due float Total amount due (invoiced - collected) 📎
suspendfrom_datetime datetime Date/time this package was suspended from 📎
suspendto_datetime datetime Date/time this package was suspended to 📎
next_invoice_datetime datetime The date the next invoice will be generated 📎
is_overdue boolean Whether or not the invoice is overdue 📎
days_overdue integer # of days overdue the package is 📎
start_datetime datetime Date/time this package was started/effective 📎
cancel_datetime datetime Date/time this package was cancelled 📎
write_datetime datetime Date/time this package was created 📎
mod_datetime datetime Date/time this package was last updated 📎
holduntil_datetime datetime Date/time invoicing for this package is being held until 📎
package_status_id string 📎
package_status_name string User-friendly subscription status 📎
package_status_str string 📎
package_status_state string 📎
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 📎
custom_1 string Custom field value #1 📎
custom_2 string Custom field value #2 📎
custom_3 string Custom field value #3 📎
custom_4 string Custom field value #4 📎
custom_5 string Custom field value #5 📎
line_items array 📎
url_self string URL for viewing the subscription in the GUI 📎

Get a specific subscription

JSON Request

GET /api/v3/package/554

JSON Response

HTTP/1.0 200 OK
Content-Type: application/json
  
{
    "code": 200,
    "status": "OK",
    "message": "",
    "response": {
        "terms_id": 2,
        "currency_id": 1,
        "external_key": null,
        "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,
        "custom_1": null,
        "custom_2": null,
        "custom_3": null,
        "write_datetime": "2014-06-04 11:56:09",
        "mod_datetime": null,
        "suspendfrom_datetime": null,
        "suspendto_datetime": null,
        "cancel_datetime": "2014-06-04 11:57:44",
        "holduntil_datetime": null,
        "currency_symbol": "$",
        "currency_iso4217": "USD",
        "amount_collected": 10.95,
        "amount_invoiced": 10.95,
        "amount_due": 0,
        "next_invoice_datetime": "",
        "package_id": 554,
        "customer_id": 1,
        "package_status_id": 5,
        "package_status_name": "Canceled manually",
        "package_status_str": "canceled-manual",
        "package_status_state": "c",
        "line_items": [
            {
                "item_id": 1,
                "tierset_id": 1,
                "external_key": null,
                "nickname": "",
                "descrip": "This is a ChargeOver test item.",
                "custom_1": null,
                "custom_2": null,
                "custom_3": null,
                "subscribe_datetime": "2014-06-04 11:56:09",
                "cancel_datetime": null,
                "expire_datetime": null,
                "expire_recurs": null,
                "license": "",
                "item_name": "My Test Service Plan",
                "item_external_key": null,
                "item_accounting_sku": null,
                "item_units": "",
                "line_item_id": 554,
                "tierset": {
                    "tierset_id": 1,
                    "setup": 0,
                    "base": 10.95,
                    "paycycle": "mon",
                    "pricemodel": "fla",
                    "write_datetime": "2014-06-02 12:29:30",
                    "mod_datetime": "2014-06-02 12:29:30",
                    "setup_formatted": "$ 0.00",
                    "base_formatted": "$ 10.95",
                    "pricemodel_desc": "Flat Pricing (e.g. $X dollars per month)",
                    "tiers": []
                }
            }
        ]
    }
}

Querying for subscriptions

Available query parameters

  • customer_id
  • package_status_state
  • package_status_str
  • bill_state
  • ship_state
  • nickname
  • external_key
  • paymethod
  • line_items.external_key
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 Package ID # 📎
customer_id integer Customer ID # 📎
class_id integer Class ID # 📎
external_key string External key value 📎
token string Unique token 📎
nickname string Nickname for the package 📎
paymethod string Payment method for the package, one of: cre, inv, ach 📎
creditcard_id integer Credit card ID # (if the package is paid by credit card) 📎
ach_id integer ACH ID # (if the package is paid by ACH) 📎
tokenized_id integer Tokenized ID # (if the package 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 📎
ship_addr1 string 📎
ship_addr2 string 📎
ship_addr3 string 📎
ship_city string 📎
ship_state string 📎
ship_postcode string 📎
ship_country string 📎
ship_notes string 📎
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 package 📎
amount_invoiced float Total amount invoiced so far 📎
amount_due float Total amount due (invoiced - collected) 📎
suspendfrom_datetime datetime Date/time this package was suspended from 📎
suspendto_datetime datetime Date/time this package was suspended to 📎
next_invoice_datetime datetime The date the next invoice will be generated 📎
is_overdue boolean Whether or not the invoice is overdue 📎
days_overdue integer # of days overdue the package is 📎
start_datetime datetime Date/time this package was started/effective 📎
cancel_datetime datetime Date/time this package was cancelled 📎
write_datetime datetime Date/time this package was created 📎
mod_datetime datetime Date/time this package was last updated 📎
holduntil_datetime datetime Date/time invoicing for this package is being held until 📎
package_status_id string 📎
package_status_name string User-friendly subscription status 📎
package_status_str string 📎
package_status_state string 📎
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 📎
custom_1 string Custom field value #1 📎
custom_2 string Custom field value #2 📎
custom_3 string Custom field value #3 📎
custom_4 string Custom field value #4 📎
custom_5 string Custom field value #5 📎
line_items array 📎
url_self string URL for viewing the subscription in the GUI 📎

Querying for subscriptions

JSON Request

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

JSON 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 plan to a different plan
  • 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

JSON Request

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

JSON 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 plan to a different plan
  • 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 plan/product type, AND how to create a prorated invoice for the new amount / credit back the unused portion of the old plan to the customer.

Upgrade/downgrade a subscription (and prorate amounts)

JSON Request

POST https://dev.chargeover.com/api/v3/package/612?action=upgrade
  
{
  "line_items": [
    {
      "_comment": "This is the EXISTING line_item_id value you wish to upgrade.", 
      "line_item_id": 729,

      "_comment": "If you want to change the plan/product type, specify the item_id here.", 
      "item_id": 14,

      "descrip": "Upgraded description goes here",

      "_comment": "This tells ChargeOver to create an invoice for the new prorated amount right away.",
      "subscribe_prorate": true,
      "subscribe_prorate_cycle": "now",
      
      "_comment": "This tells ChargeOver to credit back the unused portion of the old plan/product.",
      "cancel_prorate": true,
      "cancel_prorate_credit": true,
      "cancel_prorate_cycle": "now"
    }
  ]
}

JSON Response

HTTP/1.0 200 OK
Content-Type: application/json
  
{
    "code": 200,
    "status": "OK",
    "message": "",
    "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

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

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

Invoice a subscription now

JSON Request

POST /api/v3/package/624?action=invoice

JSON Response

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

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)

JSON Request

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

JSON Response

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

Suspend a subscription (range)

Suspend a subscription (range)

JSON Request

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

JSON Response

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

Unsuspend a subscription

Unsuspend a subscription

JSON Request

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

JSON Response

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

Cancel a subscription

Cancel a subscription

JSON Request

POST /api/v3/package/600?action=cancel

JSON Response

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

Set the payment method

Set the payment method

JSON Request

POST /api/v3/package/599?action=paymethod
  
{
    "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", 
}

JSON 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

JSON Request

POST /api/v3/package/616?action=welcome

JSON Response

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

Items (Plans, Products, Discounts)

Create an item

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

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 📎
external_key string External key value 📎
units string Units string 📎
custom_1 string Custom field value #1 📎