API
The ChargeOver API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. JSON will be returned in all responses from the API, including errors.
Getting Started
Finding your API Endpoint
The first step towards integration is finding your endpoint and credentials.
- Log in to ChargeOver, and click the settings gear/cog in the top right
- Choose "Developer" from the left-side navigation menu
- Choose "REST API"
- Enable the API, and copy your API credentials and API endpoint
- Click the save button to save the configuration
Visit this URL to make your first API request:
https://CHANGE-THIS.chargeover.com/api/v3/customer
(substitute your own application/domain name into the above string!)
To retrieve a list of data from ChargeOver, use a HTTP GET request:
https://CHANGE-THIS.chargeover.com/api/v3/customer
To retrieve a subset of the items in a list (e.g. records 10 to 25) you can use the offset and limit parameters (just like in an SQL database):
https://CHANGE-THIS.chargeover.com/api/v3/customer?offset=10&limit=15
To retrieve a specific record from ChargeOver, use a HTTP GET request and specify the record id:
https://CHANGE-THIS.chargeover.com/api/v3/customer/1
Authentication
All API calls are made over a secure TLS/HTTPS connection.
Authentication is via industry-standard HTTP basic authentication for the REST API.
For more information on HTTP Basic Authentication, please visit the links below:
Authentication
Getting started
First follow the steps outlined below:
Once you have a copy of your API Credentials, you are ready to supply it to an API platform (Postman, Insomnia, etc.)
Video walkthrough on how to obtain your API credentials:
Authentication
API Examples
// Username
PjID8u5VOCfJk3iYKzTMo7emstRLnEp9
// Password
xgEWspuItV7A2D6miwZFk94dTrBLSKQO
Postman
Configuring Postman to use your REST API credentials
- Open the Postman application
- Click on the "Collections" tab
- Click on the "+" to create a new Collection
- Add a request to the collection
- Click on the "Authorization" tab
- Select "Basic Auth" from the "Type" dropdown
- Input your API credentials (obtained previously from the steps above)
- Click on "Save" to save your API credentials to Postman
You are now ready to send API requests via Postman.
Postman
Insomnia
Configuring Insomnia to use your REST API credentials
- Open the Insomnia application
- On the "Auth" tab, click the dropdown arrow
- Select "Basic Auth"
- Input your API credentials (obtained previously from the steps above)
You are now ready to send API requests via Insomnia.
Insomnia
cURL
Sending basic auth credentials using cURL
- Open the Terminal application
- Type
curl -u username:password https://CHANGE-THIS.chargeover.com/api/v3/CHANGE-THIS
(substitute your own credentials/URL into the above string!) - Hit the "Return" key on your keyboard
cURL
API Examples
// Get the Teapot response
curl -u PjID8u5VOCfJk3iYKzTMo7emstRLnEp9:xgEWspuItV7A2D6miwZFk94dTrBLSKQO https://dev1.chargeover.test/api/v3/teapot
Header
Sending basic auth credentials using cURL PHP
An example is provided below:
$username = 'PjID8u5VOCfJk3iYKzTMo7emstRLnEp9';
$password = 'xgEWspuItV7A2D6miwZFk94dTrBLSKQO';
$curl = curl_init('https://CHANGE-THIS.chargeover.com/api/v3/teapot');
curl_setopt($ch, CURLOPT_USERPWD, $username . ':' . $password);
curl_exec($curl);
curl_close($curl);
Header
Filter / Sort / Pagination
Many fields can be used to query/filter the list of objects retrieved from ChargeOver
using a ?where=...
query string in your GET
request.
Refer to the examples below.
Filtering (Query)
Refer to the examples to the right.
To filter the result set, the following comparison operators can be used:
EQUALS
(equals)GT
(greater than)LT
(less than)GTE
(greater than or equal to)LTE
(less than or equal to)CONTAINS
(find strings containing this string)NOTEQUALS
(not equals)IS:NULL
(is null/unset)ISNOT:NULL
(is NOT null
Filtering (Query)
API Examples
// Get customers with an e-mail address of "johndoe@example.com"
/api/v3/customer?where=superuser_email:EQUALS:johndoe@example.com
// Get customers with the word "test" in their company name
/api/v3/customer?where=company:CONTAINS:test
// Get a list of invoices on "2015-02-05" (Feb 5, 2015)
/api/v3/invoice?where=date:EQUALS:2015-02-05
// Get a list of invoices between the two dates "2015-02-01" (Feb 1, 2015) and "2015-02-05" (Feb 5, 2015)
/v3/invoice?where=date:GTE:2015-02-01,date:LTE:2015-02-05
Sorting
To sort/order the result set, you can specify an additional query string parameter:
?order=customer_id:DESC
(specify the the_field_name:ASC
or
the_field_name:DESC
to sort ascending or descending)
Sorting
API Request
GET /api/v3/invoice?order=total:ASC
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"invoice_id": 1764,
"total": 500,
"customer_id": 6245
},
{
"invoice_id": 1668,
"total": 1000,
"customer_id": 6212
},
{
"invoice_id": 1681,
"total": 2000,
"customer_id": 6215
}
]
}
Paging (Limit/Offset)
To page your result set, you can specify limit=...
and offset=...
.
offset=
determines how far into the records you are querying
for to start returning data. For example, if you are querying for customers
and you have ten customers ranging from customer_id=1
and
customer_id=10
and offset=0
, then the returned
set of customers will start with the customer whose customer_id=1
.
However, if the offset=3
then the list of customers that is
returned will start with the customer who has a customer_id=4
.
limit=
determines the number of records returned. For example if
limit=5
when querying for customers, you would get back the data for
no more than five customers.
If your query contains ?offset=10&limit=15
, then this is essentially
saying, "starting at record 10, fetch the next 15 records."
Make note of the maximum number of records you can retrieve per page!
- If not specified otherwise, your result set will page by default at 10 records.
- The maximum number of records you can return per page is 500. You will not be able to retrieve more than 500 records at one time. .
Paging (Limit/Offset)
API Request
GET /api/v3/user?offset=8&limit=2
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"user_id": 356,
"external_key": null,
"first_name": "John",
"middle_name_glob": null,
"last_name": "Doe",
...other user data...
},
{
"user_id": 357,
"external_key": null,
"first_name": "Jane",
"middle_name_glob": null,
"last_name": "Doe",
...other user data...
}
]
}
Counting Objects
You can get a count of the number of objects by using the /_count
endpoints.
Counting Objects
Refer to the examples on the right.
To get a count of the number of objects within ChargeOver, append /_count
to the endpoint.
You can also count the number of objects matching a filter/query by
using your ?where=...
query on the /_count
endpoint.
Object Revisions
You can get a list of revision overview details by using the /_revision
endpoints.
Object Revisions
Refer to the examples on the right.
To get the recent revisions of objects within ChargeOver, add /_revision
to the endpoint.
You can also limit the number of records to the most recent revisions by including ?limit=5
as a query parameter. You can only limit the number of returned records by 1-10.
Object Revisions
API Examples
// Get the most recent 10 revisions of a customer
GET /API/v3/customer/100/_revision
// Get the most recent x number of revisions for a customer (max 10)
GET /API/v3/customer/100/_revision?limit=5
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"context_str": "customer",
"context_id": 100,
"admin_id": 1,
"admin_name": "Paul Rossmann",
"user_id": null,
"user_name": null,
"integration_id": null,
"revision_datetime": "2023-03-03 10:36:22",
"revision_ipaddr": "169.0.0.1",
"revision_note": "Customer updated"
},
{
"context_str": "customer",
"context_id": 100,
"admin_id": 1,
"admin_name": "Paul Rossmann",
"user_id": null,
"user_name": null,
"integration_id": null,
"revision_datetime": "2023-03-03 09:56:17",
"revision_ipaddr": "169.0.0.1",
"revision_note": "Customer created"
}
]
}
External Keys
ChargeOver has an external keys concept for all objects, to make it easier for you to integrate external systems with ChargeOver.
All objects (customers, users, invoices, billing packages, etc.) can be assigned a user-definable, unique external key value. This could be an internal identifier you use to identify a customer, the ID value from some other application, a reference to a primary key within one of your other systems, etc. When making API requests, you can always use the external key value instead of the ChargeOver id value.
External key policies:
- Default behavior - external key values can NOT be re-used, even if the original object is deleted or cancelled
- Optional - external key values can be cleared (and thus re-used) once a subscription is cancelled
- Optional - external key values can be cleared (and thus re-used) if an object is deleted
- Optional - external key values can be mangled (a random string will be added to the end of them) if a subscription is cancelled
- Optional - external key values can be mangled (a random string added to the end of them) if an object is deleted
Contact us to enable any optional external key policies for your account.
External Key Examples
Adding external_key
values to ChargeOver enables several "short-cuts" when working with the ChargeOver REST API.
- You can get objects from ChargeOver by
external_key
instead of using thecustomer_id
,item_id
, etc. - When adding or updating objects, you can reference other objects by
*_external_key
instead of their*_id
values
Refer to the examples to the right.
External Key Examples
API Examples
// Get a customer with external_key = abc123
GET /api/v3/customer/external_key:abc123
// Add an invoice for the customer with external_key = abc123
POST /api/v3/invoice
{
"customer_external_key": "abc123",
... other invoice data here ...
}
Object Tokens
ChargeOver assigns a unique random identifier to every object.
When making API requests, you can always use the object token value instead of the ChargeOver id value.
Object Token Examples
You can reference objects within ChargeOver by their token
value instead of the *_id
value.
- You can get objects from ChargeOver by
token
instead of using thecustomer_id
,item_id
, etc. - When adding or updating objects, you can reference other objects by
*_token
instead of their*_id
values
Refer to the examples to the right.
Object Token Examples
API Examples
// Get a customer with token = 0q7fx5652k18
GET /api/v3/customer/token:0q7fx5652k18
// Add an invoice for the customer with token = 0q7fx5652k18
POST /api/v3/invoice
{
"customer_token": "0q7fx5652k18",
... other invoice data here ...
}
Dates and Times
ChargeOver returns datetime
fields in ISO 8601
format.
For example, October 25th, 2022 at 8:50am Central Time
is represented as:
2022-10-25T08:50:45-05:00
Generally, the timestamps returned will be in America/Chicago
timezone.
When sending date
or datetime
values to ChargeOver, you send dates in a few formats:
YYYY-MM-DD
- a date, example:2022-10-25
YYYY-MM-DD HH:II:SS
- a date/time, example:2022-10-25 08:50:00
YYYY-MM-DDTHH:II:SS-Z
- a date/time with a timezone, example:2022-10-25T08:50:45-05:00
Note: The date/time format and timezone returned by ChargeOver is configurable, so your ChargeOver account may return dates/times in an alternative format or timezone.
Escape Syntax For Reserved Characters
Escape Syntax Example
If you are querying for an object that contains a reserved character such as a colon, you will need to escape the character using a slash.
Characters that need to be escaped:
:
(colon),
(comma)For example, if you had an item with an external_key called Example:ID
, then instead of using:
GET /api/v3/item?where=external_key:EQUALS:Example:ID
You would need to use:
GET /api/v3/item?where=external_key:EQUALS:Example\:ID
Escape Syntax Example
API Request
GET /api/v3/item?where=external_key:EQUALS:Example\:ID
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"item_id": 3,
"item_type": "service",
"tierset_id": 80,
"name": "Test Product",
"description": "",
"units": "",
"enabled": true,
"accounting_sku": null,
"external_key": "Example:ID",
"token": "hm261y3xnzd6",
"custom_1": "",
"custom_2": null,
"custom_3": null,
"write_datetime": "2017-02-28 21:02:33",
"mod_datetime": "2017-12-28 10:25:39",
"units_plural": "",
"expire_recurs": "6",
"trial_recurs": "1",
"tiersets": [
{
"tierset_id": 78,
"currency_id": 1,
"setup": 0,
"base": 25.95,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2017-12-28 10:25:39",
"mod_datetime": "2017-12-28 10:25:39",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 25.95",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
},
{
"tierset_id": 79,
"currency_id": 2,
"setup": 0,
"base": 25.95,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2017-12-28 10:25:39",
"mod_datetime": "2017-12-28 10:25:39",
"currency_symbol": "CAD$",
"currency_iso4217": "CAD",
"setup_formatted": "CAD$ 0.00",
"base_formatted": "CAD$ 25.95",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
},
{
"tierset_id": 80,
"currency_id": 6,
"setup": 0,
"base": 25.95,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2017-12-28 10:25:39",
"mod_datetime": "2017-12-28 10:25:39",
"currency_symbol": "A$",
"currency_iso4217": "AUD",
"setup_formatted": "A$ 0.00",
"base_formatted": "A$ 25.95",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
}
]
}
]
}
On Behalf Of...
Pass your end-customer's IP address to ChargeOver for fraud control.
On Behalf Of...
If you are making REST API calls directly as a direct result of an end-customer interaction,
(e.g. the customer is clicking a PAY NOW
button in your application, or something similar)
we encourage you to pass the end-customer's IP address and any identifying information
(e.g. a username, email address, user ID, etc.) in your API calls.
Do not pass this information if you are initiating the action, and not the customer. (e.g. if you are triggering an automated payment without the customer's direct interaction, do not pass these parameters!)
This information can be used for by ChargeOver's fraud detection services, and also relayed to payment gateways and merchant accounts for use by their fraud detection routines.
Pass this information in these two fields, as query string parameters to your REST API request:
on_behalf_addr=(the end-customers IP address here)
on_behalf_details=(the end-customers username, email address, or user ID in your app here)
On Behalf Of...
API Request
POST /api/v3/transaction?action=pay&on_behalf_addr=173.132.15.83&on_behalf_details=johndoe@example.com
Versioning
Whenever we make backwards-incompatible changes to the ChargeOver API, we release a new sequenced version of the API. We always strive to maintain backwards compatibility with the older APIs, and older API versions are rarely (if ever) completely removed from service.
The current release is v3.
Bulk / Batch Requests
Batch requests allow developers to avoid multiple HTTP round-trips when performing multiple API actions or bulk uploading data to ChargeOver.
The basic format of an API batch request is a list of JSON-encoded request objects to process. Each request object must have the following attributes:
Attribute | Description |
---|---|
request_method |
This HTTP request method for this request
|
uri |
A relative URI for the API resource. For example, to get a
specific customer, the URI would be /api/v3/customer/2
(where 2 is the customer_id). To create a customer,
the URI would be /api/v3/customer .
|
payload | If your request requires a payload, put the JSON-encoded payload here. For example, to create a customer, you'd pass in your JSON-encoded customer object. |
The API response will contain a corresponding list of response objects - one response object for each request you sent. Each response object will have the following attributes:
Attribute | Description |
---|---|
code |
A HTTP status code for the request.
|
status |
Either OK for success, or Error if an error occurred.
|
message | If an error occurred, the error message will appear here. |
response | If your request warrented a response (e.g. a returned object) the JSON-encoded response will be here. |
There is a maximum of 25 requests within a single batch/bulk request.
Batch Request
POST
your batch requests to the /api/v3/_bulk
endpoint.
Batch Request
API Request
POST /api/v3/_bulk
[
{
"request_method": "GET",
"uri": "\/api\/v3\/customer\/2",
"payload": null
},
{
"request_method": "POST",
"uri": "\/api\/v3\/customer",
"payload": {
"company": "My new bulk customer 928"
}
},
{
"request_method": "POST",
"uri": "\/api\/v3\/customer",
"payload": {
"company": "Test Company 464",
"external_key": "abcd1234"
}
}
]
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"_bulk": [
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"customer_id": 2,
"superuser_id": 349,
"external_key": null,
"token": "e6218b7c7b91a0121875a27a3a0ef9c5",
"company": "Test Customer 2",
... (truncated for brevity) ...
}
},
{
"code": 201,
"status": "OK",
"message": "",
"response": {
"id": 14
}
},
{
"code": 400,
"status": "Error",
"message": "A customer already exists with the external_key value \"abcd1234\"",
"response": false
}
]
}
}
JSONPath in Batches
ChargeOver supports using JSONPath for referencing one payload from within another payload, inside of a single batch/bulk request.
The classic use-case for JSONPath support in the bulk/batch API is trying to create a customer and an invoice for that customer in a single bulk/batch request. Without JSONPath references, this would not be possible to do in single bulk/batch request because you would need to know the id
value returned from executing the first payload (adding the customer) so that you could use this id
value in the second payload (adding the invoice).
JSONPath referencing support makes this possible by letting payloads refer to response values from other payloads.
In the example to the right, you can see that our second request (adding the invoice) uses a special key instead of the normal customer_id
key. The invoice add payload refers to customer_jsonpath
and the value is an identifier (the_customer
), followed by a JSONPath expression ($.response.id
).
The identifier serves to identify which previous batch/bulk object to refer to. The JSONPath expression tells us which value to fetch from that bulk/batch object response. In this case, customer_jsonpath
will be replaced by the returned id
value from the preceeding call to create the customer.
In other words, "customer_jsonpath": "the_customer:$.response.id"
essentially means "replace this with the customer_id
value returned from the payload named the_customer
".
JSONPath in Batches
API Request
POST /api/v3/_bulk
[
{
"request_method": "POST",
"uri": "\/api\/v3\/customer",
"payload": {
"company": "My test JSONPath customer"
},
"id": "the_customer"
},
{
"request_method": "POST",
"uri": "\/api\/v3\/invoice",
"payload": {
"customer_jsonpath": "the_customer:$.response.id",
"line_items": [
{
"item_id": 1,
"line_rate": 2.95,
"line_quantity": 2
}
]
},
"id": null
}
]
Rate Limits
By default, ChargeOver limits REST API requests to a maximum of 250 requests per minute.
If you exceed this limit, you will receive an API response like this:
HTTP/1.1 429 Too Many Requests Content-Type: application/json { "code": 429, "status": "Error", "message": "Rate limit exceeded", "response": false }
If you think you will routinely exceed or come close to the rate limits, please contact us to discuss your use-case.
You may be able to reduce the number of REST API requests you make using our bulk/batch request endpoint.
HTTP Status Codes
The API follows these rules for HTTP requests:
- If you are creating new objects, use a
POST
. - If you are updating an existing object, use a
PUT
. - If you are trying to get a particular object by id, use a
GET
. - If you are trying to get a list of objects, or query for a list of objects, use a
GET
. - If you are calling an action (e.g. pay an invoice, reset a password, etc.), use a
POST
.
- If you successfully create an object, you'll get back a
201 Created
HTTP response. You'll also get back aLocation:
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 aLocation:
header with the URL of the new object. - If you successfully get a specific object, you'll get back a
200 OK
HTTP response. - If you try to get a specific object that doesn't exist, you'll get back a
404 Not Found
HTTP response. - If you query for objects, you'll get back a
200 OK
HTTP response. - If you successfully call an action, you'll get back a
200 OK
HTTP response. - If you do something wrong (e.g. send an invalid JSON request, hit an invalid endpoint, etc.) you will get back a
400 Bad Request
HTTP response. - If your authentication parameters are incorrect, you will get back a
401 Unauthorized
HTTP response. - If you exceed the REST API rate limits, you will get back a
429 Too Many Requests
HTTP response. - If something goes wrong with ChargeOver itself, you will get back a
500 Internal Server Error
HTTP response.
Code / Libraries
Make sure to visit the ChargeOver GitHub account. Feel free to contact us for additional sample code.
Objects
The ChargeOver object model is documented below.
Customers
The primary key field for customers is customer_id
.
Create a customer
Note that the response/id value will be the customer_id value for the newly created customer.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
parent_customer_id | integer | Parent customer ID # | 📎 |
external_key | string | External key value | 📎 |
company | string | Company/customer name | 📎 |
language_id | integer | Language ID # | 📎 |
currency_id | integer | Currency ID # | 📎 |
class_id | integer | Default class tracking ID # | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
campaign_id | integer | Campaign/lead source ID # | 📎 |
campaign_details | string | Campaign/lead source details | 📎 |
superuser_username | string | Main contact username | 📎 |
superuser_email | string | Main contact e-mail address | 📎 |
superuser_name | string | Main contact name | 📎 |
superuser_first_name | string | Main contact first name | 📎 |
superuser_last_name | string | Main contact last name | 📎 |
superuser_phone | string | Main contact phone number | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state/province | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
brand_id | integer | Brand ID # | 📎 |
terms_id | integer | Default terms ID # | 📎 |
no_taxes | boolean | Flag to disable charging of taxes | 📎 |
no_dunning | boolean | Flag to disable dunning | 📎 |
no_latefees | boolean | Flag to disable late fees | 📎 |
no_procfees | boolean | Flag to disable processing fees | 📎 |
invoice_delivery | enum[print,email] | Delivery method for initial invoices ("email" or "print" for printed hard-copy) | 📎 |
dunning_delivery | enum[print,email] | Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) | 📎 |
tax_ident | string | Tax ID #/VAT # | 📎 |
tags | array | A list of tags | 📎 |
Create a customer
API Request
POST /api/v3/customer HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Content-Type: application/json
{
"company": "Test Company Name",
"bill_addr1": "16 Dog Lane",
"bill_addr2": "Suite D",
"bill_city": "Storrs",
"bill_state": "CT",
"superuser_name": "Karli Marie",
"superuser_phone": "860-647-8567",
"superuser_email": "karli@example.com",
"tags": [
"tag1",
"tag2"
]
}
Update a customer
Setting the parent_customer_id
to null
will effectively disconnect the child customer from its parent.
Note that a customer's parent_customer_id
can only be updated if its parent has not made a payment for the customer.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
parent_customer_id | integer | Parent customer ID # | 📎 |
superuser_id | integer | Main contact ID # | 📎 |
external_key | string | External key value | 📎 |
company | string | Company/customer name | 📎 |
language_id | integer | Language ID # | 📎 |
class_id | integer | Default class tracking ID # | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
campaign_id | integer | Campaign/lead source ID # | 📎 |
superuser_email | string | Main contact e-mail address | 📎 |
superuser_name | string | Main contact name | 📎 |
superuser_first_name | string | Main contact first name | 📎 |
superuser_last_name | string | Main contact last name | 📎 |
superuser_phone | string | Main contact phone number | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state/province | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
terms_id | integer | Default terms ID # | 📎 |
no_taxes | boolean | Flag to disable charging of taxes | 📎 |
no_dunning | boolean | Flag to disable dunning | 📎 |
no_latefees | boolean | Flag to disable late fees | 📎 |
no_procfees | boolean | Flag to disable processing fees | 📎 |
invoice_delivery | enum[print,email] | Delivery method for initial invoices ("email" or "print" for printed hard-copy) | 📎 |
dunning_delivery | enum[print,email] | Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) | 📎 |
tax_ident | string | Tax ID #/VAT # | 📎 |
tags | array | A list of tags | 📎 |
Update a customer
API Request
PUT /api/v3/customer/3
{
"company": "Test API Company, LLC",
"bill_addr1": "220 ChargeOver Street",
"bill_addr2": "Suite 10",
"bill_city": "Minneapolis",
"bill_state": "MN",
"bill_postcode": "55416",
"bill_country": "USA",
"external_key": "abcd3325",
"superuser_name": "David Palmer",
"superuser_email": "david@palmer.com",
"superuser_phone": "860-634-1111"
}
Get a list of customers
Notes:
- The
superuser_id
field is the primary contact (user) for this customer
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
parent_customer_id | integer | Parent customer ID # | 📎 |
token | string | Customer Token | 📎 |
superuser_id | integer | Main contact ID # | 📎 |
external_key | string | External key value | 📎 |
display_as | string | Deprecated | 📎 |
company | string | Company/customer name | 📎 |
language_id | integer | Language ID # | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | ISO 4217 currency code representation | 📎 |
currency_symbol | string | Symbol for currency ($, £, etc.) | 📎 |
class_id | integer | Default class tracking ID # | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
campaign_id | integer | Campaign/lead source ID # | 📎 |
superuser_username | string | Main contact username | 📎 |
superuser_email | string | Main contact e-mail address | 📎 |
superuser_name | string | Main contact name | 📎 |
superuser_first_name | string | Main contact first name | 📎 |
superuser_last_name | string | Main contact last name | 📎 |
superuser_phone | string | Main contact phone number | 📎 |
superuser_token | string | Main contact token | 📎 |
superuser_title | string | Main contact title | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state/province | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_block | string | Printable shipping address | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | string | Date/time this customer was created | 📎 |
write_ipaddr | string | IP address that created this customer | 📎 |
mod_datetime | string | Date/time this customer was updated | 📎 |
mod_ipaddr | string | IP address that last updated this customer | 📎 |
brand_id | integer | Brand ID # | 📎 |
class_name | string | Class name | 📎 |
terms_id | integer | Default terms ID # | 📎 |
terms_name | string | Default payment terms | 📎 |
terms_days | integer | # of days for the default payment terms | 📎 |
url_statementlink | string | URL the customer can visit to view their monthly statement | 📎 |
url_paymethodlink | string | URL the customer can visit to update their payment method | 📎 |
url_self | string | URL for viewing the customer in the GUI | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
admin_email | string | Admin/Worker Email | 📎 |
customer_status_id | integer | Customer Status ID # | 📎 |
customer_status_name | string | Human-friendly customer status | 📎 |
customer_status_str | string | Status string | 📎 |
customer_status_state | string | Status code | 📎 |
default_paymethod | string | Default payment method type | 📎 |
default_creditcard_id | integer | Default credit card ID # (if the default payment method is a credit card) | 📎 |
default_ach_id | integer | Default ACH/eCheck ID # (if the default payment method is ACH) | 📎 |
no_taxes | boolean | Flag to disable charging of taxes | 📎 |
no_dunning | boolean | Flag to disable dunning | 📎 |
no_latefees | boolean | Flag to disable late fees | 📎 |
no_procfees | boolean | Flag to disable processing fees | 📎 |
invoice_delivery | enum[print,email] | Delivery method for initial invoices ("email" or "print" for printed hard-copy) | 📎 |
dunning_delivery | enum[print,email] | Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) | 📎 |
tax_ident | string | Tax ID #/VAT # | 📎 |
total | float | The sum total amount of all invoices ever issued to this customer (lifetime value) | 📎 |
balance | float | Balance due for this customer | 📎 |
paid | float | The lifetime net total payments minus refunds this customer has made | 📎 |
mrr | float | Current monthly recurring revenue of the customer | 📎 |
arr | float | Current annual recurring revenue of the customer | 📎 |
Get a list of customers
API Request
GET /api/v3/customer
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"superuser_id": "348",
"external_key": "test-key",
"company": "Update This Record 755",
"email": "keith@testjson.com",
"phone": "",
"bill_addr1": "16 Dog Lane",
"bill_addr2": "Suite D",
"bill_addr3": null,
"bill_city": "Storrs",
"bill_state": "CT",
"bill_postcode": "",
"bill_country": null,
"bill_email": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_email": null,
"ship_notes": null,
"write_datetime": "2012-08-16 16:18:47",
"write_ipaddr": "172.16.16.104",
"mod_datetime": "2013-03-21 20:32:57",
"mod_ipaddr": "172.16.16.11",
"customer_id": "1"
}
]
}
Query for customers
Notes:
- The
superuser_id
field is the primary contact (user) for this customer
customer_id
parent_customer_id
bill_state
ship_state
bill_country
ship_country
external_key
token
company
superuser_id
superuser_email
custom_1
custom_2
custom_3
custom_4
custom_5
write_datetime
- date/time createdmod_datetime
- date/time last modified
customer_status_state
:
- a (for active customers)
- i (for customers who have manually been marked "inactive" or who have had no recent activity)
customer_status_str
:
- active-current
- active-overdue
- inactive-manual
- inactive-activity
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
parent_customer_id | integer | Parent customer ID # | 📎 |
token | string | Customer Token | 📎 |
superuser_id | integer | Main contact ID # | 📎 |
external_key | string | External key value | 📎 |
display_as | string | Deprecated | 📎 |
company | string | Company/customer name | 📎 |
language_id | integer | Language ID # | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | ISO 4217 currency code representation | 📎 |
currency_symbol | string | Symbol for currency ($, £, etc.) | 📎 |
class_id | integer | Default class tracking ID # | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
campaign_id | integer | Campaign/lead source ID # | 📎 |
superuser_username | string | Main contact username | 📎 |
superuser_email | string | Main contact e-mail address | 📎 |
superuser_name | string | Main contact name | 📎 |
superuser_first_name | string | Main contact first name | 📎 |
superuser_last_name | string | Main contact last name | 📎 |
superuser_phone | string | Main contact phone number | 📎 |
superuser_token | string | Main contact token | 📎 |
superuser_title | string | Main contact title | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state/province | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_block | string | Printable shipping address | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | string | Date/time this customer was created | 📎 |
write_ipaddr | string | IP address that created this customer | 📎 |
mod_datetime | string | Date/time this customer was updated | 📎 |
mod_ipaddr | string | IP address that last updated this customer | 📎 |
brand_id | integer | Brand ID # | 📎 |
class_name | string | Class name | 📎 |
terms_id | integer | Default terms ID # | 📎 |
terms_name | string | Default payment terms | 📎 |
terms_days | integer | # of days for the default payment terms | 📎 |
url_statementlink | string | URL the customer can visit to view their monthly statement | 📎 |
url_paymethodlink | string | URL the customer can visit to update their payment method | 📎 |
url_self | string | URL for viewing the customer in the GUI | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
admin_email | string | Admin/Worker Email | 📎 |
customer_status_id | integer | Customer Status ID # | 📎 |
customer_status_name | string | Human-friendly customer status | 📎 |
customer_status_str | string | Status string | 📎 |
customer_status_state | string | Status code | 📎 |
default_paymethod | string | Default payment method type | 📎 |
default_creditcard_id | integer | Default credit card ID # (if the default payment method is a credit card) | 📎 |
default_ach_id | integer | Default ACH/eCheck ID # (if the default payment method is ACH) | 📎 |
no_taxes | boolean | Flag to disable charging of taxes | 📎 |
no_dunning | boolean | Flag to disable dunning | 📎 |
no_latefees | boolean | Flag to disable late fees | 📎 |
no_procfees | boolean | Flag to disable processing fees | 📎 |
invoice_delivery | enum[print,email] | Delivery method for initial invoices ("email" or "print" for printed hard-copy) | 📎 |
dunning_delivery | enum[print,email] | Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) | 📎 |
tax_ident | string | Tax ID #/VAT # | 📎 |
total | float | The sum total amount of all invoices ever issued to this customer (lifetime value) | 📎 |
balance | float | Balance due for this customer | 📎 |
paid | float | The lifetime net total payments minus refunds this customer has made | 📎 |
mrr | float | Current monthly recurring revenue of the customer | 📎 |
arr | float | Current annual recurring revenue of the customer | 📎 |
Query for customers
API Request
GET /api/v3/customer?where=bill_country:EQUALS:Canada
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"superuser_id": 357,
"external_key": null,
"company": "CA Test Customer 1",
"email": "asgdadg@asdgaggd.com",
"phone": "",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": "Canada",
"bill_email": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_email": null,
"ship_notes": null,
"write_datetime": "2013-08-22 08:57:09",
"write_ipaddr": "172.16.16.102",
"mod_datetime": "2013-08-22 08:57:09",
"mod_ipaddr": "172.16.16.102",
"display_as": "CA Test Customer 1",
"ship_block": "",
"bill_block": "Canada",
"customer_id": 7
}
]
}
Get a specific customer
Get a specific customer using their customer_id.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
parent_customer_id | integer | Parent customer ID # | 📎 |
token | string | Customer Token | 📎 |
superuser_id | integer | Main contact ID # | 📎 |
external_key | string | External key value | 📎 |
display_as | string | Deprecated | 📎 |
company | string | Company/customer name | 📎 |
language_id | integer | Language ID # | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | ISO 4217 currency code representation | 📎 |
currency_symbol | string | Symbol for currency ($, £, etc.) | 📎 |
class_id | integer | Default class tracking ID # | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
campaign_id | integer | Campaign/lead source ID # | 📎 |
superuser_username | string | Main contact username | 📎 |
superuser_email | string | Main contact e-mail address | 📎 |
superuser_name | string | Main contact name | 📎 |
superuser_first_name | string | Main contact first name | 📎 |
superuser_last_name | string | Main contact last name | 📎 |
superuser_phone | string | Main contact phone number | 📎 |
superuser_token | string | Main contact token | 📎 |
superuser_title | string | Main contact title | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state/province | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_block | string | Printable shipping address | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | string | Date/time this customer was created | 📎 |
write_ipaddr | string | IP address that created this customer | 📎 |
mod_datetime | string | Date/time this customer was updated | 📎 |
mod_ipaddr | string | IP address that last updated this customer | 📎 |
brand_id | integer | Brand ID # | 📎 |
class_name | string | Class name | 📎 |
terms_id | integer | Default terms ID # | 📎 |
terms_name | string | Default payment terms | 📎 |
terms_days | integer | # of days for the default payment terms | 📎 |
url_statementlink | string | URL the customer can visit to view their monthly statement | 📎 |
url_paymethodlink | string | URL the customer can visit to update their payment method | 📎 |
url_self | string | URL for viewing the customer in the GUI | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
admin_email | string | Admin/Worker Email | 📎 |
customer_status_id | integer | Customer Status ID # | 📎 |
customer_status_name | string | Human-friendly customer status | 📎 |
customer_status_str | string | Status string | 📎 |
customer_status_state | string | Status code | 📎 |
default_paymethod | string | Default payment method type | 📎 |
default_creditcard_id | integer | Default credit card ID # (if the default payment method is a credit card) | 📎 |
default_ach_id | integer | Default ACH/eCheck ID # (if the default payment method is ACH) | 📎 |
no_taxes | boolean | Flag to disable charging of taxes | 📎 |
no_dunning | boolean | Flag to disable dunning | 📎 |
no_latefees | boolean | Flag to disable late fees | 📎 |
no_procfees | boolean | Flag to disable processing fees | 📎 |
invoice_delivery | enum[print,email] | Delivery method for initial invoices ("email" or "print" for printed hard-copy) | 📎 |
dunning_delivery | enum[print,email] | Delivery method for dunning/reminder invoices ("email" or "print" for printed hard-copy via Docsaway, Lob, etc.) | 📎 |
tax_ident | string | Tax ID #/VAT # | 📎 |
total | float | The sum total amount of all invoices ever issued to this customer (lifetime value) | 📎 |
balance | float | Balance due for this customer | 📎 |
paid | float | The lifetime net total payments minus refunds this customer has made | 📎 |
mrr | float | Current monthly recurring revenue of the customer | 📎 |
arr | float | Current annual recurring revenue of the customer | 📎 |
tags | array | A list of tags | 📎 |
Get a specific customer
API Request
GET /api/v3/customer/16
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"superuser_id": 364,
"external_key": null,
"token": "fozdqj169569",
"company": "Karli Marie",
"bill_addr1": "56 Wintergreen Street",
"bill_addr2": "",
"bill_addr3": "",
"bill_city": "Hamden",
"bill_state": "CT",
"bill_postcode": "06517",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"terms_id": 3,
"class_id": 0,
"custom_1": "",
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"custom_6": null,
"admin_id": 4,
"campaign_id": 0,
"currency_id": 1,
"language_id": 1,
"brand_id": 1,
"default_paymethod": "crd",
"default_creditcard_id": 51,
"default_ach_id": null,
"no_taxes": false,
"no_dunning": false,
"write_datetime": "2017-05-18 09:36:19",
"write_ipaddr": "130.215.123.7",
"mod_datetime": "2017-12-01 21:37:50",
"mod_ipaddr": "192.168.21.14",
"terms_name": "Due on Receipt",
"terms_days": 0,
"class_name": "",
"paid": 1145.46,
"total": 2656.11,
"balance": 1510.65,
"url_paymethodlink": "https:\/\/dev.chargeover.com\/r\/paymethod\/i\/fozdqj169569",
"url_self": "https:\/\/dev.chargeover.com\/admin\/r\/customer\/view\/16",
"admin_name": "ChargeOver Support",
"admin_email": "support@chargeover.com",
"currency_symbol": "$",
"currency_iso4217": "USD",
"display_as": "Karli Marie",
"ship_block": "",
"bill_block": "56 Wintergreen Street\nHamden CT 06517\nUnited States",
"superuser_name": "Karli Marie",
"superuser_first_name": "Karli",
"superuser_last_name": "Marie",
"superuser_phone": "860-249-1317",
"superuser_email": "karli@chargeover.com",
"superuser_token": "1892mske1j64",
"customer_id": 16,
"parent_customer_id": null,
"invoice_delivery": "email",
"dunning_delivery": "email",
"customer_status_id": 2,
"customer_status_name": "Over Due",
"customer_status_str": "active-overdue",
"customer_status_state": "a",
"superuser_username": "QATPM1zD4CLE",
"tags": [
"tag1",
"tag2"
]
}
}
Delete a customer
Allows you to delete a customer.
Note that you can only delete a customer if:
- They have no active subscriptions
- They have no open/unpaid invoices
Set a customer as inactive
Allows you to set a customer as "Inactive".
Set a customer as inactive
API Request
POST /api/v3/customer/2?action=setInactive
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V...
Content-Type: application/json
Set a customer as active
Allows you to set a specified customer as "Active".
Set a customer as active
API Request
POST /api/v3/customer/2?action=setActive
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V...
Content-Type: application/json
Set the primary contact for a customer
Specify the user you want to assign as the customer's primary contact using the user's user_id
.
Set the default payment method for a customer
Allows you to set the defaut payment method for a customer.
The update_subscriptions_and_scheduled_invoices
field is optional.
If you leave it off entirely OR set it to true
, we will update any already existing subscriptions for that customer to use this payment method too. If you set it to false
, we'll update the customer but NOT their already existing subscriptions.
Email a customer
Allows you to send an email from a template to a customer.
The message_id
field is optional. If left out, the default email will be a welcome message.
Disconnect a customer from its parent customer
Allows you to disconnect a child customer from its parent customer via POST API Request.
A customer's parent can only be disconnected if its parent has not made a payment for the customer.
Note you can also disconnect a parent by updating the customer and setting its parent_customer_id
to null
Users / Contacts
The primary key field for a user is user_id
Add a contact
Notes:
- The response/id value will be the user_id value for the newly created user.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
external_key | string | External key value | 📎 |
username | string | Customer portal username | 📎 |
password | string | Customer portal password | 📎 |
name | string | First and last name of the contact | 📎 |
first_name | string | First name of contact | 📎 |
middle_name_glob | string | Middle name/initial | 📎 |
last_name | string | Last name | 📎 |
name_suffix | string | Suffix (e.g. "Jr.", "Sr.", "III", etc.) | 📎 |
title | string | Title | 📎 |
string | E-mail address | 📎 | |
phone | string | Phone number | 📎 |
mobile | string | Mobile number | 📎 |
user_type_id | integer | User type ID # | 📎 |
customer_id | integer | The customer ID # this contact belongs to | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
Add a contact
Update a contact
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
external_key | string | External key value | 📎 |
username | string | Customer portal username | 📎 |
password | string | Customer portal password | 📎 |
name | string | First and last name of the contact | 📎 |
first_name | string | First name of contact | 📎 |
middle_name_glob | string | Middle name/initial | 📎 |
last_name | string | Last name | 📎 |
name_suffix | string | Suffix (e.g. "Jr.", "Sr.", "III", etc.) | 📎 |
title | string | Title | 📎 |
string | E-mail address | 📎 | |
phone | string | Phone number | 📎 |
mobile | string | Mobile number | 📎 |
user_type_id | integer | User type ID # | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
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 | 📎 |
string | E-mail address | 📎 | |
phone | string | Phone number | 📎 |
mobile | string | Mobile number | 📎 |
user_type_id | integer | User type ID # | 📎 |
user_type_name | string | User type | 📎 |
customer_id | integer | The customer ID # this contact belongs to | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | datetime | Date/time the user/contact was created | 📎 |
mod_datetime | datetime | Date/time the user/contact was last modified | 📎 |
url_self | string | URL for viewing the user/contact in the GUI | 📎 |
Get a specific contact
API Request
GET /api/v3/user/362
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"user_id": 362,
"external_key": null,
"first_name": "Keith",
"middle_name_glob": null,
"last_name": "Palmer",
"name_suffix": null,
"title": "",
"email": "keith@chargeover.com",
"phone": "860-634-1602",
"write_datetime": "2014-07-08 14:26:01",
"mod_datetime": "2014-07-08 14:26:01",
"name": "Keith Palmer",
"display_as": "Keith Palmer",
"user_type_id": 1,
"user_type_name": "Billing",
"username": "7yanhoctj6qs"
}
}
Get a list of contacts
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
user_id | integer | The user/contact ID # | 📎 |
external_key | string | External key value | 📎 |
token | string | Unique token | 📎 |
username | string | Customer portal username | 📎 |
name | string | First and last name of the contact | 📎 |
first_name | string | First name of contact | 📎 |
middle_name_glob | string | Middle name/initial | 📎 |
last_name | string | Last name | 📎 |
name_suffix | string | Suffix (e.g. "Jr.", "Sr.", "III", etc.) | 📎 |
display_as | string | (deprecated) | 📎 |
title | string | Title | 📎 |
string | E-mail address | 📎 | |
phone | string | Phone number | 📎 |
mobile | string | Mobile number | 📎 |
user_type_id | integer | User type ID # | 📎 |
user_type_name | string | User type | 📎 |
customer_id | integer | The customer ID # this contact belongs to | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | datetime | Date/time the user/contact was created | 📎 |
mod_datetime | datetime | Date/time the user/contact was last modified | 📎 |
url_self | string | URL for viewing the user/contact in the GUI | 📎 |
Get a list of contacts
API Request
GET /api/v3/user
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"user_id": 348,
"external_key": null,
"first_name": "John",
"middle_name_glob": "",
"last_name": "Doe",
"name_suffix": null,
"title": "",
"email": "test1@test1.com",
"phone": "",
"write_datetime": "2014-07-02 09:58:37",
"mod_datetime": "2014-07-02 06:05:24",
"name": "John Doe",
"display_as": "John Doe",
"username": "test1@test1.com"
},
...
Query for contacts
Available query parameter values for filtering:
user_id
external_key
first_name
last_name
email
phone
user_type_id
username
customers.customer_id
- Get contacts belonging to a specific customer
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
user_id | integer | The user/contact ID # | 📎 |
external_key | string | External key value | 📎 |
token | string | Unique token | 📎 |
username | string | Customer portal username | 📎 |
name | string | First and last name of the contact | 📎 |
first_name | string | First name of contact | 📎 |
middle_name_glob | string | Middle name/initial | 📎 |
last_name | string | Last name | 📎 |
name_suffix | string | Suffix (e.g. "Jr.", "Sr.", "III", etc.) | 📎 |
display_as | string | (deprecated) | 📎 |
title | string | Title | 📎 |
string | E-mail address | 📎 | |
phone | string | Phone number | 📎 |
mobile | string | Mobile number | 📎 |
user_type_id | integer | User type ID # | 📎 |
user_type_name | string | User type | 📎 |
customer_id | integer | The customer ID # this contact belongs to | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
write_datetime | datetime | Date/time the user/contact was created | 📎 |
mod_datetime | datetime | Date/time the user/contact was last modified | 📎 |
url_self | string | URL for viewing the user/contact in the GUI | 📎 |
Query for contacts
API Request
GET /api/v3/user?where=first_name:EQUALS:Keith
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"user_id": 362,
"external_key": null,
"first_name": "Keith",
"middle_name_glob": null,
"last_name": "Palmer",
"name_suffix": null,
"title": "",
"email": "keith@chargeover.com",
"phone": "860-634-1602",
"write_datetime": "2014-07-02 09:58:37",
"mod_datetime": "2014-07-08 14:26:01",
"name": "Keith Palmer",
"display_as": "Keith Palmer",
"username": "7yanhoctj6qs"
},
...
Send a password reset
By default, calling the password
action will send an e-mail to the end-user containing a link. The end-user will follow the link to reset their password.
If you’d instead prefer to explicitly set the password to something for the user, you can tell password
to set the password to a passed in value. An email will be sent to the end-user containing the new password.
IMPORTANT: In either of the above two cases, the default behavior sends an e-mail. If you don’t want the e-mail to be sent, use the _flag_emails=0
advanced flag to suppress the outgoing e-mail.
Send a password reset
API Request
POST /api/v3/user/372?action=password HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Log in a user
This fetches a short-lived, one-time-use login URL that you can use to automatically log a user into the ChargeOver customer portal. This link is only valid for a very short amount of time, so you must forward the user to this URL immediately. The user will be immediately and automatically logged into the customer portal.
By default when the user is logged in, they will be dropped on the home page. You can optionally specify a
destination
attribute to send them to a specific page of the portal after login.
Possible values for destination
:
subscriptions
(for the list of subscriptions)invoices
(for the list of invoices)payments
(for the list of payments)info
(for the "My Info" page with the company/name/phone/etc.)paymethods
(for the "Payment Methods" tab with credit card info, etc.)paymethods-creditcard
(the "Payment Methods" tab, and prompt the user to save a new credit card)paymethods-ach
(the "Payment Methods" tab, and prompt the user to save a new bank account)password
(for the "Change My Password" tab)
Invoices
The primary key field for an invoice is invoice_id
.
Create an invoice
Requirements
- You must specify an existing
customer_id
,customer_token
, orcustomer_external_key
value. - You must specify at least one line item.
- Each line item must refer to an existing
item_id
value.
Notes
- The response/id value is the invoice_id value of the newly created invoice.
- The
Location:
header will provide a direct API link to the newly created invoice.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
refnumber | string | Invoice reference number | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
date | date | Invoice date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the invoice
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Create an invoice
API Request
POST /api/v3/invoice HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 1,
"bill_addr1": "72 E Blue Grass Road",
"bill_city": "Willington",
"bill_state": "Connecticut",
"bill_postcode": "06279",
"line_items": [
{
"item_id": 307,
"descrip": "My description goes here",
"line_rate": 29.95,
"line_quantity": 12
},
{
"item_id": 293,
"descrip": "Another description",
"line_rate": 12.95,
"line_quantity": 2
}
]
}
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 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the invoice
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Get a list of invoices
Returns a list of all invoices.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
invoice_id | integer | Invoice ID # | 📎 |
refnumber | string | Invoice reference number | 📎 |
external_key | string | External key value | 📎 |
invoice_index | integer | The invoice subscription sequence number on a subscription | 📎 |
package_id | integer | Subscription ID # this invoice was generated from | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
brand_name | string | Brand name | 📎 |
write_datetime | datetime | Date/time the invoice was created | 📎 |
mod_datetime | datetime | Date/time this subscription was last updated | 📎 |
void_datetime | datetime | Date/time the invoice was voided | 📎 |
date | date | Invoice date | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_symbol | string | Currency symbol | 📎 |
currency_iso4217 | string | Currency ISO 4217 representation | 📎 |
class_id | integer | Class ID # | 📎 |
class_name | string | Class Name | 📎 |
paycycle | string | Payment cycle | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
terms_id | integer | Terms ID # | 📎 |
terms_name | string | Terms name | 📎 |
terms_days | integer | Terms # of days | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
token | string | Unique token | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (deprecated) | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (deprecated) | 📎 |
ship_block | string | Printable shipping address | 📎 |
cycle_pre_from_date | date | For pre-billing, cycle start date | 📎 |
cycle_pre_to_date | date | For pre-billing, cycle end date | 📎 |
cycle_this_date | date | Cycle date (generally the invoice date) | 📎 |
cycle_post_from_date | date | For post-billing (in arrears), cycle start date | 📎 |
cycle_post_to_date | date | For post-billing (in arrears), cycle end date | 📎 |
url_permalink | string | URL to view the invoice | 📎 |
url_pdflink | string | URL to download the invoice PDF | 📎 |
url_paylink | string | URL to pay for the invoice | 📎 |
url_self | string | URL for viewing the invoice in the GUI | 📎 |
is_paid | boolean | Whether or not the invoice has been paid | 📎 |
is_void | boolean | Whether or not the invoice has been voided | 📎 |
is_overdue | boolean | Whether or not the invoice is overdue | 📎 |
due_date | date | Date the invoice is due | 📎 |
days_overdue | integer | # of days overdue the invoice is | 📎 |
paid_date | date | Date this invoice was paid | 📎 |
balance | float | Balance of the invoice | 📎 |
applied | float | Amount applied to the invoice | 📎 |
total | float | Invoice total | 📎 |
subtotal | float | Invoice subtotal | 📎 |
taxes | float | Taxes | 📎 |
credits | float | Amount of credits applied to the invoice | 📎 |
payments | float | Amount of payments applied to the invoice | 📎 |
writeoffs | float | Amount written off | 📎 |
refunds | float | Amount refunded | 📎 |
overdue | float | Amount overdue | 📎 |
declines | integer | # of times that payment was attempted and failed for this invoice | 📎 |
sum_base | float | Sum of the amounts of all base fees on the invoice | 📎 |
sum_usage | float | Sum of the amounts of all usage-based/metered fees on the invoice | 📎 |
sum_onetime | float | Sum of the amounts of all of the one-time charges on the invoice | 📎 |
invoice_status_name | string | Human-friendly invoice status | 📎 |
invoice_status_str | string | Status string | 📎 |
invoice_status_state | string | Status code | 📎 |
memo | string | Memo/notes to customer | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
Get a list of invoices
API Request
GET /api/v3/invoice
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"invoice_id": 10160,
"currency_id": 1,
"brand_id": 1,
"terms_id": 3,
"admin_id": 0,
"external_key": null,
"token": "7s163e80302k",
"refnumber": "10160",
"cycle_pre_from_date": "2017-10-04",
"cycle_pre_to_date": "2017-11-03",
"cycle_this_date": "2017-10-03",
"cycle_post_from_date": "2017-08-28",
"cycle_post_to_date": "2017-10-03",
"bill_addr1": "56 Cowles Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Mt Pleasant",
"bill_state": "MI",
"bill_postcode": "48858",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-10-03 08:54:13",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "",
"invoice_status_name": "Paid",
"invoice_status_str": "closed-paid",
"invoice_status_state": "c",
"subtotal": 117.8,
"total": 117.8,
"taxes": 0,
"credits": 0,
"payments": 117.8,
"writeoffs": 0,
"declines": 0,
"applied": 117.8,
"sum_base": 112.9,
"sum_usage": 0,
"sum_onetime": 0,
"is_paid": true,
"paid_date": "2017-11-08",
"balance": 0,
"is_void": false,
"due_date": "2017-10-03",
"terms_name": "Due on Receipt",
"terms_days": 0,
"days_overdue": 76,
"is_overdue": false,
"date": "2017-10-03",
"bill_block": "56 Cowles Road\r\nMt Pleasant, MI 48858\r\nUnited States",
"ship_block": "",
"url_permalink": "https://dev.chargeover.com/r/invoice/view/7s163e80302k",
"url_paylink": "https://dev.chargeover.com/r/trans/pay/7s163e80302k",
"url_pdflink": "https://dev.chargeover.com/r/invoice/pdf/7s163e80302k",
"url_self": "https://dev.chargeover.com/admin/r/invoice/view/10160",
"package_id": 617,
"customer_id": 424
},
........
{
"invoice_id": 10203,
"currency_id": 1,
"brand_id": 1,
"terms_id": 3,
"admin_id": null,
"external_key": null,
"token": "e7a23gi4vhyc",
"refnumber": "10203",
"cycle_pre_from_date": "2017-12-03",
"cycle_pre_to_date": "2018-01-02",
"cycle_this_date": "2017-12-03",
"cycle_post_from_date": "2017-11-03",
"cycle_post_to_date": "2017-12-02",
"bill_addr1": "104 Abigail Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Brantford",
"bill_state": "MA",
"bill_postcode": "null",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-12-03 07:23:47",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "",
"invoice_status_name": "Overdue",
"invoice_status_str": "open-overdue",
"invoice_status_state": "o",
"subtotal": 45,
"total": 45,
"taxes": 0,
"credits": 0,
"payments": 0,
"writeoffs": 0,
"declines": 3,
"applied": 0,
"sum_base": 45,
"sum_usage": 0,
"sum_onetime": 0,
"is_paid": false,
"paid_date": null,
"balance": 45,
"is_void": false,
"due_date": "2017-12-03",
"terms_name": "Due on Receipt",
"terms_days": 0,
"days_overdue": 15,
"is_overdue": true,
"date": "2017-12-03",
"bill_block": "104 Abigail Road\r\nBrantford, MA\r\nUnited States",
"ship_block": "",
"url_permalink": "https://dev.chargeover.com/r/invoice/view/e7a23gi4vhyc",
"url_paylink": "https://dev.chargeover.com/r/trans/pay/e7a23gi4vhyc",
"url_pdflink": "https://dev.chargeover.com/r/invoice/pdf/e7a23gi4vhyc",
"url_self": "https://dev.chargeover.com/admin/r/invoice/view/10203",
"package_id": 618,
"customer_id": 414
}
]
}
Get a specific invoice
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
invoice_id | integer | Invoice ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
refnumber | string | Invoice reference number | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice_index | integer | The invoice subscription sequence number on a subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
package_id | integer | Subscription ID # this invoice was generated from | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_id | integer | Brand ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_name | string | Brand name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
write_datetime | datetime | Date/time the invoice was created | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mod_datetime | datetime | Date/time this subscription was last updated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
void_datetime | datetime | Date/time the invoice was voided | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
date | date | Invoice date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_symbol | string | Currency symbol | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_iso4217 | string | Currency ISO 4217 representation | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_name | string | Class Name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle_name | string | Payment cycle name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_name | string | Terms name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_days | integer | Terms # of days | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_name | string | Admin/Worker Name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
token | string | Unique token | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_block | string | Printable billing address | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_block | string | Printable shipping address | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cycle_pre_from_date | date | For pre-billing, cycle start date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cycle_pre_to_date | date | For pre-billing, cycle end date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cycle_this_date | date | Cycle date (generally the invoice date) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cycle_post_from_date | date | For post-billing (in arrears), cycle start date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cycle_post_to_date | date | For post-billing (in arrears), cycle end date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_permalink | string | URL to view the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_pdflink | string | URL to download the invoice PDF | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_paylink | string | URL to pay for the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_self | string | URL for viewing the invoice in the GUI | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_paid | boolean | Whether or not the invoice has been paid | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_void | boolean | Whether or not the invoice has been voided | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_overdue | boolean | Whether or not the invoice is overdue | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
due_date | date | Date the invoice is due | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
days_overdue | integer | # of days overdue the invoice is | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paid_date | date | Date this invoice was paid | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
balance | float | Balance of the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
applied | float | Amount applied to the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total | float | Invoice total | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subtotal | float | Invoice subtotal | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
taxes | float | Taxes | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
credits | float | Amount of credits applied to the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payments | float | Amount of payments applied to the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
writeoffs | float | Amount written off | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
refunds | float | Amount refunded | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
overdue | float | Amount overdue | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
declines | integer | # of times that payment was attempted and failed for this invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sum_base | float | Sum of the amounts of all base fees on the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sum_usage | float | Sum of the amounts of all usage-based/metered fees on the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
sum_onetime | float | Sum of the amounts of all of the one-time charges on the invoice | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice_status_name | string | Human-friendly invoice status | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice_status_str | string | Status string | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
invoice_status_state | string | Status code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the invoice
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
schedule - array A list of scheduled payments for this invoice
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Get a specific invoice
API Request
GET /api/v3/invoice/98165
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"invoice_id": 98165,
"currency_id": 1,
"brand_id": 1,
"terms_id": 2,
"admin_id": 1,
"external_key": null,
"token": "1tslo5m9h51b",
"refnumber": "98165",
"cycle_pre_from_date": null,
"cycle_pre_to_date": null,
"cycle_this_date": null,
"cycle_post_from_date": null,
"cycle_post_to_date": null,
"bill_addr1": "56 Cowles",
"bill_addr2": "Suite 620",
"bill_addr3": "",
"bill_city": "Minneapolis",
"bill_state": "MN",
"bill_postcode": "55416",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2019-09-26 10:16:43",
"void_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"admin_name": "ChargeOver Support",
"invoice_status_name": "Unpaid",
"invoice_status_str": "open-unpaid",
"invoice_status_state": "o",
"subtotal": 100,
"total": 100,
"taxes": 0,
"credits": 0,
"payments": 35,
"writeoffs": 0,
"declines": 0,
"applied": 35,
"sum_base": 0,
"sum_usage": 0,
"sum_onetime": 100,
"is_paid": false,
"paid_date": null,
"balance": 65,
"is_void": false,
"due_date": "2019-12-20",
"terms_name": "Net 30",
"terms_days": 30,
"days_overdue": 0,
"is_overdue": false,
"date": "2019-09-26",
"bill_block": "56 Cowles\r\nSuite 620\r\nMinneapolis, MN 55416\r\nUnited States",
"ship_block": "",
"url_permalink": "https:\/\/example.chargeover.com\/r\/invoice\/view\/1tslo5m9h51b",
"url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/pay\/1tslo5m9h51b",
"url_pdflink": "https:\/\/example.chargeover.com\/r\/invoice\/pdf\/1tslo5m9h51b",
"url_self": "https:\/\/example.chargeover.com\/admin\/r\/invoice\/view\/98165",
"package_id": null,
"customer_id": 3488,
"line_items": [
{
"invoice_id": 98165,
"item_id": 29,
"tierset_id": null,
"admin_id": null,
"descrip": "1-month subscription to gold plan.",
"line_rate": 100,
"line_quantity": 1,
"line_prorate": 1,
"line_usage": 0,
"usage_from": 0,
"usage_to": 0,
"tax_id": null,
"tax_group_id": null,
"tax_taxable": 100,
"tax_taxed": 0,
"tax_total": 0,
"is_base": false,
"is_free": false,
"is_setup": false,
"is_usage": false,
"is_recurring": false,
"is_latefee": false,
"is_taxed": false,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"item_name": "Gold Plan",
"item_external_key": null,
"item_token": "1kzl806611h1",
"item_accounting_sku": null,
"item_units": null,
"tax_name": null,
"tax_group_name": null,
"line_subtotal": 100,
"line_total": 100,
"line_item_id": 234,
"package_line_id": null,
"package_line_external_key": null
}
],
"sent": [],
"schedule": [
{
"invoice_schedule_id": 13,
"invoice_id": 98165,
"token": "199m59nc2k1p",
"paymethod": "inv",
"creditcard_id": null,
"ach_id": null,
"url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/sch\/1tslo5m9h51b\/199m59nc2k1p",
"amount": 10,
"balance": 0,
"amount_or_percent_formatted": "$ 10.00",
"date": "2019-09-30"
},
{
"invoice_schedule_id": 16,
"invoice_id": 98165,
"token": "19nvqp56y146",
"paymethod": "ach",
"creditcard_id": null,
"ach_id": 8,
"url_paylink": "https:\/\/example.chargeover.com\/r\/trans\/sch\/1tslo5m9h51b\/19nvqp56y146",
"amount": 25,
"balance": 25,
"amount_or_percent_formatted": "25%",
"date": "2019-11-20"
}
]
}
}
Query for invoices
Available query parameter values for filtering:
invoice_id
refnumber
customer_id
bill_state
ship_state
bill_country
ship_country
invoice_status_str
- See the list of valid values belowinvoice_status_state
- See the list of valid values belowpackage_token
package_id
invoice_index
date
currency_id
token
custom_1
custom_2
custom_3
line_items.item_id
line_items.custom_1
line_items.custom_2
line_items.custom_3
transaction.transaction_id
- Get a list of invoices paid by this transactionquote.quote_id
- Get the invoice that originated from a specific quotewrite_datetime
- date/time createdmod_datetime
- date/time last modified
Valid values for invoice_status_str:
- open-unpaid
- open-overdue
- open-collections
- closed-void
- closed-paid
Valid values for invoice_status_state:
o
(any “open” invoice, i.e. anything with money due)c
(any “closed” invoice, i.e. anything without money due)
By default, only the overview invoice details are returned (i.e. no individual line items). If you get a specific invoice by invoice id value
(e.g. GET /api/v3/invoice/1234
) you’ll get back the invoice line items.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
invoice_id | integer | Invoice ID # | 📎 |
refnumber | string | Invoice reference number | 📎 |
external_key | string | External key value | 📎 |
invoice_index | integer | The invoice subscription sequence number on a subscription | 📎 |
package_id | integer | Subscription ID # this invoice was generated from | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
brand_name | string | Brand name | 📎 |
write_datetime | datetime | Date/time the invoice was created | 📎 |
mod_datetime | datetime | Date/time this subscription was last updated | 📎 |
void_datetime | datetime | Date/time the invoice was voided | 📎 |
date | date | Invoice date | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_symbol | string | Currency symbol | 📎 |
currency_iso4217 | string | Currency ISO 4217 representation | 📎 |
class_id | integer | Class ID # | 📎 |
class_name | string | Class Name | 📎 |
paycycle | string | Payment cycle | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
terms_id | integer | Terms ID # | 📎 |
terms_name | string | Terms name | 📎 |
terms_days | integer | Terms # of days | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
token | string | Unique token | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (deprecated) | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (deprecated) | 📎 |
ship_block | string | Printable shipping address | 📎 |
cycle_pre_from_date | date | For pre-billing, cycle start date | 📎 |
cycle_pre_to_date | date | For pre-billing, cycle end date | 📎 |
cycle_this_date | date | Cycle date (generally the invoice date) | 📎 |
cycle_post_from_date | date | For post-billing (in arrears), cycle start date | 📎 |
cycle_post_to_date | date | For post-billing (in arrears), cycle end date | 📎 |
url_permalink | string | URL to view the invoice | 📎 |
url_pdflink | string | URL to download the invoice PDF | 📎 |
url_paylink | string | URL to pay for the invoice | 📎 |
url_self | string | URL for viewing the invoice in the GUI | 📎 |
is_paid | boolean | Whether or not the invoice has been paid | 📎 |
is_void | boolean | Whether or not the invoice has been voided | 📎 |
is_overdue | boolean | Whether or not the invoice is overdue | 📎 |
due_date | date | Date the invoice is due | 📎 |
days_overdue | integer | # of days overdue the invoice is | 📎 |
paid_date | date | Date this invoice was paid | 📎 |
balance | float | Balance of the invoice | 📎 |
applied | float | Amount applied to the invoice | 📎 |
total | float | Invoice total | 📎 |
subtotal | float | Invoice subtotal | 📎 |
taxes | float | Taxes | 📎 |
credits | float | Amount of credits applied to the invoice | 📎 |
payments | float | Amount of payments applied to the invoice | 📎 |
writeoffs | float | Amount written off | 📎 |
refunds | float | Amount refunded | 📎 |
overdue | float | Amount overdue | 📎 |
declines | integer | # of times that payment was attempted and failed for this invoice | 📎 |
sum_base | float | Sum of the amounts of all base fees on the invoice | 📎 |
sum_usage | float | Sum of the amounts of all usage-based/metered fees on the invoice | 📎 |
sum_onetime | float | Sum of the amounts of all of the one-time charges on the invoice | 📎 |
invoice_status_name | string | Human-friendly invoice status | 📎 |
invoice_status_str | string | Status string | 📎 |
invoice_status_state | string | Status code | 📎 |
memo | string | Memo/notes to customer | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
Query for invoices
API Request
GET /api/v3/invoice?where=customer_id:EQUALS:1,invoice_status_state:EQUALS:o&limit=1000 HTTP/1.1
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"invoice_id": "2688",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_email": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_email": null,
"ship_notes": null,
"write_datetime": "2012-11-09 18:10:03",
"void_datetime": null,
"invoice_status_name": "Unpaid",
"invoice_status_str": "open-unpaid",
"invoice_status_state": "o",
"total": 150,
"credits": 0,
"payments": 0,
"is_paid": false,
"balance": 150,
"is_void": false,
"bill_block": "",
"ship_block": "",
"url_permalink": "https:\/\/dev.chargeover.com\/r\/invoice\/view\/i17fq4huy2ar",
"url_pdflink": "https:\/\/dev.chargeover.com\/r\/invoice\/pdf\/i17fq4huy2ar",
"customer_id": "1"
}
]
}
Add a late fee to an invoice
Allows you to add a late fee to an invoice. The late fee amount is dictated by the configuration of the Late Fees feature in your account.
Scheduling payments for invoices
ChargeOver allows you to schedule a full payment or several partial payments to
invoices via the REST API. You must specify the amount
and
date
of the payment.
For invoices created from a subscription, the payment method used is always the payment method from the subscription itself.
For one-time invoices, you can specify a credit card, bank account, or tokenized payment method
to be used for the payment by providing the creditcard_id
, ach_id
, or
tokenized_id
in the paymethod
field. Otherwise, you can use any
to allow any
of the customer's stored payment methods to be used.
You can also use crd
to have the payment charged to any credit card stored for the customer,
ach
to specify the payment method as any of the stored ACH bank accounts the customer has, or
tok
to specify the payment method as any of the stored tokenized payment methods the customer has.
Scheduling payments for invoices
API Request
POST /api/v3/invoice/5052?action=schedule
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
{
"schedule": [
{
"_comment": "You can specify a specific creditcard or ach to use as the payment method:",
"amount": 50,
"date": "2021-10-20",
"creditcard_id": 9
},
{
"_comment": "To schedule with ANY payment method the customer has on file:",
"amount": 10,
"date": "2021-11-28",
"paymethod": "any"
},
{
"_comment": "To schedule the payment(s) with ANY CREDITCARD the customer has on file:",
"amount": 10,
"date": "2021-12-28",
"paymethod": "crd"
},
{
"_comment": "To schedule the payment(s) with ANY ACH the customer has on file:",
"amount": 10,
"date": "2022-01-28",
"paymethod": "ach"
}
]
}
Removing scheduled payments from invoices
This will remove all scheduled payments from a specific invoice.
Set the payment method for an invoice
Set the payment method for an invoice.
- If the invoice was created from a subscription, this updates the subscription payment method.
- If the invoice has scheduled payments attached, this updates the payment method for the attached scheduled payments.
- If the invoice is not from an invoice, and has no attached scheduled payments, this method does nothing.
If you want to remove any payment methods from the scheduled payments/subscription, you can set a payment method of paymethod: "inv"
.
Overriding tax calculations on an invoice
This allows you to override the tax configurations in your account and specify a specific tax amount to charge when creating an invoice.
Overriding tax calculations on an invoice
API Request
POST /api/v3/invoice
Content-Type: application/json
{
"customer_id": 57,
"bill_addr1": "78 W Blue Grass Road",
"bill_city": "Willington",
"bill_state": "Connecticut",
"bill_postcode": "06279",
"line_items": [
{
"item_id": 247,
"descrip": "My description goes here",
"line_rate": 29.95,
"line_quantity": 12,
"tax_total": 34.56,
"tax_override": true,
"tax_name": "Connecticut"
}
]
}
Credit card payment (specify card details)
Credit card payment (specify card details)
API Request
POST /api/v3/invoice/16715?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"number": "4111 1111 1111 1111",
"expdate_year": "2017",
"expdate_month": "08",
"name": "Keith Palmer",
"address": "72 E Blue Grass Road",
"city": "Willington",
"state": "CT",
"postcode": "06279",
"country": "United States"
}
ACH/eCheck payment (specify ACH details)
ACH/eCheck payment (specify ACH details)
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.
Email an invoice
Send an invoice via e-mail. You can specify an email template to use with the message_id
, which is the id number you see in the URL when you edit an email template in ChargeOver.
Email an invoice
API Request
POST /api/v3/invoice/13011?action=email
Content-Type: application/json
{
"_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
"email": "to@example.com",
"cc": "cc@example.com",
"bcc": "bcc@example.com",
"subject": "Override the default subject",
"body": "Override the default plain-text body of the email",
"html": "Override the default <b>HTML body<\/b> of the email",
"from": "\"Example Company\" <from@example.com>",
"_comment_message_id": "If you wish to use an existing template other than the default, specify the message_id of the template:",
"message_id": 1
}
Print & mail an invoice
Physically print a hard-copy of an invoice, and mail it (via USPS or other local carrier) to the customer.
This requires an active subscription with one of ChargeOver's supported print vendors (Docsaway, Postal Methods, etc.).
Get a PDF of an invoice
Retrieve a PDF of an invoice.
Get a PDF of an invoice
API Request
POST /api/v3/invoice/13011?action=pdf
Transactions (Payments, Refunds, Credits)
Pay with credit card
Attempt to make a payment for a customer, using a credit card.
If you specify one or more paymethods
then those specific payment methods will be used.
If you do not specify, then:
- If the invoice is from a subscription, the payment method for the subscription will be tried.
- Otherwise, if the customer has a default payment method specified, the default payment method will be tried.
- Otherwise, all payment methods for the customer will be tried.
Alternatively, you can specify an existing creditcard_id
or ach_id
within paymethods
if you wish to attempt the transaction on an existing pay method.
Valid paymethods
values:
- New credit card
- New ACH
- Existing
creditcard_id
- Existing
ach_id
The returned id
value will be the transaction_id
value of the resulting transaction.
Requirements
- You must specify an existing
customer_id
,customer_token
, orcustomer_external_key
. - You must specify either an
amount
or at least oneinvoice_id
to pay.
Pay with credit card
API Request
POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 4130,
"_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
"amount": 15.95,
"applied_to": [
{
"invoice_id": 16891
}
],
"paymethods": [
{
"_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
"creditcard_id": 1234
},
{
"_comment": "... or the full credit card details...",
"number": "4111 1111 1111 1111",
"expdate_year": "2025",
"expdate_month": "09",
"cvv": "123"
}
]
}
Pay with bank account
Attempt to make a payment for a customer, using a bank account (ACH/direct debit/PAD).
Note that bank account payments (ACH/direct debit/PAD) do not return a real-time response from the bank. Payments will go to a "Pending" status, and take an average of 2-5 business days to settle (or be returned by the bank), at which time the status will update to either "Success" or "Failed (decline)".
If you specify one or more paymethods
then those specific payment methods will be used.
If you do not specify, then:
- If the invoice is from a subscription, the payment method for the subscription will be tried.
- Otherwise, if the customer has a default payment method specified, the default payment method will be tried.
- Otherwise, all payment methods for the customer will be tried.
Alternatively, you can specify an existing creditcard_id
or ach_id
within paymethods
if you wish to attempt the transaction on an existing pay method.
Valid paymethods
values:
- New credit card
- New ACH
- Existing
creditcard_id
- Existing
ach_id
The returned id
value will be the transaction_id
value of the resulting transaction.
Requirements
- You must specify an existing
customer_id
,customer_token
, orcustomer_external_key
. - You must specify either an
amount
or at least oneinvoice_id
to pay.
Pay with bank account
API Request
POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 4130,
"_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
"amount": 15.95,
"applied_to": [
{
"invoice_id": 16891
}
],
"paymethods": [
{
"_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
"ach_id": 1234
},
{
"_comment": "... or full ACH\/bank account details.",
"type": "chec",
"number": "856667",
"routing": "072403004",
"name": "Jane Doe"
}
]
}
Pay against a schedule / installment
Attempt to make a payment for a customer, against a scheduled payment or installment.
If you are using ChargeOver's scheduled payments features (scheduling payments or installments against an invoice) then you can take payments using the API, against a particular scheduled payment.
You will specify the invoice_schedule_id
of the scheduled payment you want to pay against, along with
the amount of the payment to apply to that scheduled payment.
Pay against a schedule / installment
API Request
POST /api/v3/transaction?action=pay HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 4130,
"_comment": "Payment amount amount (if you don't specify an amount, you MUST specify a list of invoice_id values -- the amount will be calculated for you).",
"amount": 15.95,
"applied_to": [
{
"invoice_id": 16891,
"invoice_schedule_id": 79,
"applied": 15.95
}
],
"paymethods": [
{
"_comment": "You can supply just an existing pay method id value (e.g. creditcard_id, ach_id, tokenized_id)... ",
"creditcard_id": 1234
},
{
"_comment": "... or the full credit card details...",
"number": "4111 1111 1111 1111",
"expdate_year": "2025",
"expdate_month": "09",
"cvv": "123"
},
{
"_comment": "... or full ACH\/bank account details.",
"type": "chec",
"number": "856667",
"routing": "072403004",
"name": "Jane Doe"
}
]
}
Create a Credit Memo
Create a credit memo for a customer.
Notes:
- The transaction_type value MUST be "cre"
- The gateway_method value MUST be "credit"
- The gateway_status value should be either 1 (to indicate the payment was successful) or 0 (zero, to log a payment that failed/was declined)
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
gateway_id | integer | Payment gateway ID # | 📎 |
gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
gateway_transid | string | Payment gateway transaction identifier | 📎 |
gateway_method | string | Payment gateway method | 📎 |
gateway_msg | string | A customer-facing error message indicating why the transaction declined/failed | 📎 |
external_key | string | Transaction external key value | 📎 |
amount | float | Total transaction amount (refunds will be negative) | 📎 |
transaction_date | date | Date of the transaction | 📎 |
transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
transaction_method | string | Transaction method | 📎 |
transaction_detail | string | Transaction details | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
memo | string | Transaction memo | 📎 |
Create a Credit Memo
API Request
POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 1,
"gateway_id": 1,
"gateway_status": 1,
"gateway_transid": "abcd1234",
"gateway_msg": "test gateway message",
"gateway_method": "credit",
"amount": 15.95,
"transaction_type": "cre",
"transaction_detail": "here are some details",
"transaction_datetime": "2013-06-20 18:48:17",
"_comment": "You can specify which invoices to apply the payments to...",
"applied_to": [
{
"invoice_id": 16891
}
],
"_comment": "... or be even more specific, and tell ChargeOver what ",
"_comment": " invoices to apply the payments to, and what amounts/splits",
"_comment": " to apply to each of the invoices...",
"applied_to": [
{
"invoice_id": 10071,
"applied": 10.95
},
{
"invoice_id": 10072,
"applied": 5.0
}
],
"_comment": "... or just tell ChargeOver to auto-apply it to the oldest, ",
"_comment": " newest, or 'best fit' invoices (based on amount/date).",
"auto_apply": "oldest_first",
"auto_apply": "newest_first",
"auto_apply": "best_fit",
}
Record offline payment
A payment transaction is used to indicate an invoice has been paid (either entirely paid, or partially paid for).
Note: This does not actually charge a credit card or an ACH account. If you're trying to do that, please see the attempt a payment endpoint.
Notes:
- The transaction_type value MUST be “pay”
- The gateway_status value should be either 1 (to indicate the payment was successful) or 0 (zero, to log a payment that failed/was declined)
- The gateway_method value MUST be one of:
visa
,mastercard
,american-express
,discover
,check
,paypal
,credit
,ach
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
gateway_id | integer | Payment gateway ID # | 📎 |
gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
gateway_transid | string | Payment gateway transaction identifier | 📎 |
gateway_method | string | Payment gateway method | 📎 |
gateway_msg | string | A customer-facing error message indicating why the transaction declined/failed | 📎 |
external_key | string | Transaction external key value | 📎 |
amount | float | Total transaction amount (refunds will be negative) | 📎 |
transaction_date | date | Date of the transaction | 📎 |
transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
transaction_method | string | Transaction method | 📎 |
transaction_detail | string | Transaction details | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
memo | string | Transaction memo | 📎 |
Record offline payment
API Request
POST /api/v3/transaction HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 1,
"gateway_id": 1,
"gateway_status": 1,
"gateway_transid": "abcd1234",
"gateway_msg": "test gateway message",
"gateway_method": "check",
"amount": 15.95,
"transaction_type": "pay",
"transaction_detail": "here are some details",
"transaction_datetime": "2013-06-20 18:48:17",
"_comment": "You can specify which invoices to apply the payments to...",
"applied_to": [
{
"invoice_id": 16891
}
],
"_comment": "... or be even more specific, and tell ChargeOver what ",
"_comment": " invoices to apply the payments to, and what amounts/splits",
"_comment": " to apply to each of the invoices...",
"applied_to": [
{
"invoice_id": 10071,
"applied": 10.95
},
{
"invoice_id": 10072,
"applied": 5.0
}
],
"_comment": "... or just tell ChargeOver to auto-apply it to the oldest, ",
"_comment": " newest, or 'best fit' invoices (based on amount/date).",
"auto_apply": "oldest_first",
"auto_apply": "newest_first",
"auto_apply": "best_fit",
}
Get a specific transaction
Getting a transaction (a payment, refund, credit, etc.) gives you the full transaction details.
A couple of notes about some specific attributes returned:
- applied_to - if the payment is applied to any invoices, a list of invoices and the amount of the payment applied will be listed here
- refunds - for payments, if any portion of the payment was refunded, a list of related refund
transaction_id
values will be here - payments - for refunds, the original payment
transaction_id
value will be here
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
transaction_id | integer | Transaction ID # | 📎 | ||||||||||||||||||||||||
parent_transaction_id | integer | Parent transaction ID # | 📎 | ||||||||||||||||||||||||
transaction_batch_id | integer | Transaction batch ID # | 📎 | ||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||
brand_id | integer | Brand ID # | 📎 | ||||||||||||||||||||||||
gateway_id | integer | Payment gateway ID # | 📎 | ||||||||||||||||||||||||
gateway_type | string | Payment gateway type | 📎 | ||||||||||||||||||||||||
gateway_nickname | string | Nickname for the payment gateway | 📎 | ||||||||||||||||||||||||
gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 | ||||||||||||||||||||||||
gateway_transid | string | Payment gateway transaction identifier | 📎 | ||||||||||||||||||||||||
gateway_method | string | Payment gateway method | 📎 | ||||||||||||||||||||||||
gateway_msg | string | A customer-facing error message indicating why the transaction declined/failed | 📎 | ||||||||||||||||||||||||
gateway_err_code | integer | A merchant-facing specific error code indicating why the transaction declined/failed | 📎 | ||||||||||||||||||||||||
gateway_err_detail | string | A merchant-facing detailed error message indicating why the transaction declined/failed | 📎 | ||||||||||||||||||||||||
gateway_opts | mixed | Additional gateway-specific data | 📎 | ||||||||||||||||||||||||
token | string | A unique token for the transaction | 📎 | ||||||||||||||||||||||||
external_key | string | Transaction external key value | 📎 | ||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||
currency_iso4217 | string | Currency ISO 4217 code | 📎 | ||||||||||||||||||||||||
currency_symbol | string | Currency symbol | 📎 | ||||||||||||||||||||||||
amount | float | Total transaction amount (refunds will be negative) | 📎 | ||||||||||||||||||||||||
fee | float | Transaction fee (if gateway provides this data) | 📎 | ||||||||||||||||||||||||
applied | float | Amount that is applied to invoices | 📎 | ||||||||||||||||||||||||
unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 | ||||||||||||||||||||||||
transaction_date | date | Date of the transaction | 📎 | ||||||||||||||||||||||||
transaction_status_name | string | Human-friendly transaction status | 📎 | ||||||||||||||||||||||||
transaction_status_str | string | Status string | 📎 | ||||||||||||||||||||||||
transaction_status_state | string | State code | 📎 | ||||||||||||||||||||||||
transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 | ||||||||||||||||||||||||
transaction_type_name | string | Transaction type name | 📎 | ||||||||||||||||||||||||
transaction_method | string | Transaction method | 📎 | ||||||||||||||||||||||||
transaction_detail | string | Transaction details | 📎 | ||||||||||||||||||||||||
transaction_datetime | datetime | Date/time of the transaction was created | 📎 | ||||||||||||||||||||||||
transaction_ipaddr | string | IP address that created the transaction | 📎 | ||||||||||||||||||||||||
void_datetime | datetime | Date/time the transaction was voided | 📎 | ||||||||||||||||||||||||
url_self | string | URL for viewing the transaction in the GUI | 📎 | ||||||||||||||||||||||||
applied_to - array Information about how the payment is applied
|
|||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||
memo | string | Transaction memo | 📎 |
Get a specific transaction
API Request
GET /api/v3/transaction/92
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeX...
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"transaction_id": 43,
"gateway_id": 201,
"currency_id": 1,
"external_key": null,
"token": "185g5984n91k",
"transaction_date": "2019-07-24",
"gateway_status": 1,
"gateway_transid": "1563978556",
"gateway_msg": "",
"gateway_err_code": 0,
"gateway_err_detail": null,
"gateway_opts": {
"time_stamp": "Wed, 24 Jul 2019 09:29:16 -0500",
"auth_code": "ABC123"
},
"gateway_method": "visa",
"amount": 75,
"fee": 0,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1111",
"transaction_datetime": "2019-07-24 09:29:16",
"transaction_ipaddr": "10.80.1.1",
"void_datetime": null,
"transaction_status_name": "Success",
"transaction_status_str": "ok-successful",
"transaction_status_state": "o",
"transaction_type_name": "Payment",
"applied": 75,
"brand_id": 1,
"currency_symbol": "$",
"currency_iso4217": "USD",
"url_self": "https:\/\/dev1.chargeover.com\/admin\/r\/transaction\/view\/43",
"customer_id": 48,
"unapplied": 0,
"applied_to": [
{
"invoice_id": 1027,
"applied": 75
}
],
"refunds": [
{
"transaction_id": 44
}
]
}
}
List transactions
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
transaction_id | integer | Transaction ID # | 📎 |
parent_transaction_id | integer | Parent transaction ID # | 📎 |
transaction_batch_id | integer | Transaction batch ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
gateway_id | integer | Payment gateway ID # | 📎 |
gateway_type | string | Payment gateway type | 📎 |
gateway_nickname | string | Nickname for the payment gateway | 📎 |
gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
gateway_transid | string | Payment gateway transaction identifier | 📎 |
gateway_method | string | Payment gateway method | 📎 |
gateway_msg | string | A customer-facing error message indicating why the transaction declined/failed | 📎 |
gateway_err_code | integer | A merchant-facing specific error code indicating why the transaction declined/failed | 📎 |
gateway_err_detail | string | A merchant-facing detailed error message indicating why the transaction declined/failed | 📎 |
gateway_opts | mixed | Additional gateway-specific data | 📎 |
token | string | A unique token for the transaction | 📎 |
external_key | string | Transaction external key value | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | Currency ISO 4217 code | 📎 |
currency_symbol | string | Currency symbol | 📎 |
amount | float | Total transaction amount (refunds will be negative) | 📎 |
fee | float | Transaction fee (if gateway provides this data) | 📎 |
applied | float | Amount that is applied to invoices | 📎 |
unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 |
transaction_date | date | Date of the transaction | 📎 |
transaction_status_name | string | Human-friendly transaction status | 📎 |
transaction_status_str | string | Status string | 📎 |
transaction_status_state | string | State code | 📎 |
transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
transaction_type_name | string | Transaction type name | 📎 |
transaction_method | string | Transaction method | 📎 |
transaction_detail | string | Transaction details | 📎 |
transaction_datetime | datetime | Date/time of the transaction was created | 📎 |
transaction_ipaddr | string | IP address that created the transaction | 📎 |
void_datetime | datetime | Date/time the transaction was voided | 📎 |
url_self | string | URL for viewing the transaction in the GUI | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
memo | string | Transaction memo | 📎 |
List transactions
API Request
GET /api/v3/transaction
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"transaction_id": 1,
"gateway_id": 101,
"currency_id": 1,
"gateway_status": 1,
"gateway_transid": "*TEST CC* Mon, 23 Jun 2014 22:48:20 -0500",
"gateway_msg": "",
"amount": 25,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1111",
"transaction_datetime": "2014-06-23 22:48:20",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 1
},
{
"transaction_id": 2,
"gateway_id": 101,
"currency_id": 1,
"gateway_status": 1,
"gateway_transid": "*TEST CC* Mon, 23 Jun 2014 22:50:48 -0500",
"gateway_msg": "",
"amount": 75,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1427",
"transaction_datetime": "2014-06-23 22:50:48",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 2
},
...
]
}
Query for transactions
Available query parameter values for filtering:
- transaction_id
- customer_id
- gateway_id
- currency_id
- creditcard_id
- ach_id
- tokenized_id
- token
- external_key
- gateway_status
- gateway_transid
- amount
- fee
- transaction_type
- transaction_method
- transaction_detail
- transaction_datetime
- transaction_status.state
- transaction_status.str
- applied_to.package_id (this will find transactions that are applied to invoices from a specific package)
- applied_to.package_external_key (this will find transactions that are applied to invoices from a specific package)
- applied_to.invoice_id (this will find transactions that are applied to a particular invoice)
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
transaction_id | integer | Transaction ID # | 📎 |
parent_transaction_id | integer | Parent transaction ID # | 📎 |
transaction_batch_id | integer | Transaction batch ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
gateway_id | integer | Payment gateway ID # | 📎 |
gateway_type | string | Payment gateway type | 📎 |
gateway_nickname | string | Nickname for the payment gateway | 📎 |
gateway_status | integer | Payment gateway status (1 for success, 0 for failure) | 📎 |
gateway_transid | string | Payment gateway transaction identifier | 📎 |
gateway_method | string | Payment gateway method | 📎 |
gateway_msg | string | A customer-facing error message indicating why the transaction declined/failed | 📎 |
gateway_err_code | integer | A merchant-facing specific error code indicating why the transaction declined/failed | 📎 |
gateway_err_detail | string | A merchant-facing detailed error message indicating why the transaction declined/failed | 📎 |
gateway_opts | mixed | Additional gateway-specific data | 📎 |
token | string | A unique token for the transaction | 📎 |
external_key | string | Transaction external key value | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | Currency ISO 4217 code | 📎 |
currency_symbol | string | Currency symbol | 📎 |
amount | float | Total transaction amount (refunds will be negative) | 📎 |
fee | float | Transaction fee (if gateway provides this data) | 📎 |
applied | float | Amount that is applied to invoices | 📎 |
unapplied | float | Amount that is unapplied (not applied to any invoices) | 📎 |
transaction_date | date | Date of the transaction | 📎 |
transaction_status_name | string | Human-friendly transaction status | 📎 |
transaction_status_str | string | Status string | 📎 |
transaction_status_state | string | State code | 📎 |
transaction_type | string | Transaction type (one of: pay, ref, cre, spl) | 📎 |
transaction_type_name | string | Transaction type name | 📎 |
transaction_method | string | Transaction method | 📎 |
transaction_detail | string | Transaction details | 📎 |
transaction_datetime | datetime | Date/time of the transaction was created | 📎 |
transaction_ipaddr | string | IP address that created the transaction | 📎 |
void_datetime | datetime | Date/time the transaction was voided | 📎 |
url_self | string | URL for viewing the transaction in the GUI | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
memo | string | Transaction memo | 📎 |
Query for transactions
API Request
GET /api/v3/transaction?where=transaction_type:EQUALS:pay
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"transaction_id": 65,
"gateway_id": 201,
"currency_id": 1,
"token": "6by30nr7dxlh",
"transaction_date": "2015-02-16",
"gateway_status": 1,
"gateway_transid": "*TEST CC* Mon, 16 Feb 2015 16:29:13 -0500",
"gateway_msg": "",
"amount": 10.95,
"fee": -0.33,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1111",
"transaction_datetime": "2015-02-16 20:29:13",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 1
},
{
"transaction_id": 66,
"gateway_id": 202,
"currency_id": 1,
"token": "flsxubzeao0t",
"transaction_date": "2015-02-20",
"gateway_status": 0,
"gateway_transid": null,
"gateway_msg": "-",
"amount": 25.95,
"fee": 0,
"transaction_type": "pay",
"transaction_method": "Visa",
"transaction_detail": "x1111",
"transaction_datetime": "2015-02-20 20:20:34",
"void_datetime": null,
"transaction_type_name": "Payment",
"currency_symbol": "$",
"currency_iso4217": "USD",
"customer_id": 1
},
...
Mark a transaction declined
If ChargeOver is unable to get informaton back about NSF payments from your ACH payment gateway, you can use this API call to manually mark a transaction as declined via the API.
Optionally, you can specify values for the gateway_msg
, gateway_err_code
, and gateway_err_detail
fields to supply more information about the failed transaction.
For the gateway_msg
field, you can put the message from your gateway about why the transaction failed. For instance, if a transaction failed because of insufficient funds, you could put "Insufficient Funds"
in for this field.
If you are not sure what error code to use for the gateway_err_code
field, you can view our list of payment processor error codes here.
Adjust applied amounts
Use this to adjust how much of a payment or credit is applied to specific invoices, or which invoices a payment or credit is applied to.
On every REST API request, you need to specify all of the invoices the payment is applied to. Any existing applications of the payment will be overwritten by the applications in this REST API request (e.g. if an invoice previously had this payment applied to it, and you don't specify that invoice in this request, the payment application will be removed from that invoice).
To unapply the payment entirely, specify an empty `applied_to` array.
Note: You can only adjust how payments and credits are applied.
Adjust applied amounts
API Request
POST /api/v3/transaction/68?action=changeAppliedAmounts HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"applied_to": [
{
"invoice_id": 1274,
"applied": 10
},
{
"invoice_id": 1287,
"applied": 2.9
}
]
}
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.
Email a receipt
Send a payment receipt, or payment failure notification, via e-mail. You can specify an email template to use with the message_id
, which is the id number you see in the URL when you edit an email template in ChargeOver.
Email a receipt
API Request
POST /api/v3/transaction/65?action=email
Content-Type: application/json
{
"_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
"email": "to@example.com",
"cc": "cc@example.com",
"bcc": "bcc@example.com",
"subject": "Override the default subject",
"body": "Override the default plain-text body of the email",
"html": "Override the default <b>HTML body<\/b> of the email",
"from": "\"Example Company\" <from@example.com>",
"_comment_message_id": "You can optionally specify a message_id value to use a specific email template.",
"message_id": 2
}
Quotes
The primary key field for a quote is quote_id
.
Create a quote
Requirements
- You must specify an existing customer_id, customer_token, or customer_external_key value.
- You must specify at least one line item.
- Each line item must refer to an existing item_id value.
- You must specify a paycycle:
one
- a quote for a one-time invoicemon
- a quote for a monthly subscription2mn
- a quote for a subscription that invoices the customer every 2 monthsyrl
- a quote for a yearly subscription2yr
- a quote for a subscription that invoices the customer every 2 years3yr
- a quote for a subscription that invoices the customer every 3 years1wk
- a quote for a weekly subscription2wk
- a quote for a subscription that invoices the customer every 2 weeksqtr
- a quote for a quarterly subscriptionsix
- a quote for a subscription that invoices customers every 6 months
- The id value in the response is the
quote_id
value of the newly created quote. - The "Location:" header will provide a direct API link to the newly created quote.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
refnumber | string | Quote reference number | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle for the quote (e.g. monthly, etc.) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Quote nickname | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
date | date | Quote date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
validuntil_date | date | Quote valid until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime_str | string | Date/time invoicing for the resulting subscription to be delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # for Quickbooks | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_id | integer | Brand ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_acceptredirect | string | URL the lead should be redirected to after accepting a quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_rejectredirect | string | URL the lead should be redirected to after rejecting a quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the quote
|
Create a quote
API Request
POST /api/v3/quote
Content-Type: application/json
{
"customer_id": 5,
"paycycle": "mon",
"line_items": [
{
"item_id": 1,
"descrip": "Here is a description for my line item.",
"line_quantity": 15
},
{
"item_id": 1,
"descrip": "Here is a description for my line item.",
"line_quantity": 15,
"tierset": {
"pricemodel": "fla",
"base": 10.95,
"setup": 199.99
}
}
]
}
Update a quote
If you want to keep a line item unchanged, pass just the line_item_id value of the existing line item.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
refnumber | string | Quote reference number | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle for the quote (e.g. monthly, etc.) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Quote nickname | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime_str | string | Date/time invoicing for the resulting subscription to be delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # for Quickbooks | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the quote
|
Update a quote
API Request
PUT /api/v3/quote/199
Content-Type: application/json
{
"customer_id": 5,
"paycycle": "mon",
"line_items": [
{
"_comment": "To update an existing line item, pass it's line_item_id value:",
"line_item_id": 369,
"descrip": "Updated description.",
"line_quantity": 25
},
{
"_comment": "Custom pricing can be specified via the tierset attribute:",
"item_id": 1,
"line_quantity": 1,
"tierset": {
"pricemodel": "fla",
"base": 10.95,
"setup": 199.99
}
}
]
}
Get a list of quotes
Returns a list of ALL quotes
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
quote_id | integer | Quote ID # | 📎 |
refnumber | string | Quote reference number | 📎 |
external_key | string | External key value | 📎 |
paycycle | string | Payment cycle for the quote (e.g. monthly, etc.) | 📎 |
nickname | string | Quote nickname | 📎 |
customer_id | integer | Customer ID # | 📎 |
write_datetime | datetime | Date/time the quote was created | 📎 |
date | date | Quote date | 📎 |
validuntil_date | date | Quote valid until | 📎 |
holduntil_datetime_str | string | Date/time invoicing for the resulting subscription to be delayed until | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_symbol | string | Currency symbol | 📎 |
currency_iso4217 | string | Currency ISO 4217 representation | 📎 |
terms_id | integer | Terms ID # | 📎 |
class_id | integer | Class ID # for Quickbooks | 📎 |
terms_name | string | Terms name | 📎 |
terms_days | integer | Terms # of days | 📎 |
brand_id | integer | Brand ID # | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
token | string | Unique token | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (deprecated) | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (deprecated) | 📎 |
ship_block | string | Printable shipping address | 📎 |
url_permalink | string | URL to view the quote | 📎 |
url_pdflink | string | URL to get a PDF of the quote | 📎 |
url_self | string | URL for viewing the quote in the GUI | 📎 |
url_acceptlink | string | URL to visit to accept the quote | 📎 |
url_paylink | string | URL to visit to provide a payment method for the quote | 📎 |
url_rejectlink | string | URL to visit to reject the quote | 📎 |
url_acceptredirect | string | URL the lead should be redirected to after accepting a quote | 📎 |
url_rejectredirect | string | URL the lead should be redirected to after rejecting a quote | 📎 |
won_datetime | string | The Date/time that the quote was accepted | 📎 |
lost_datetime | string | The Date/time that the quote was rejected | 📎 |
due_date | date | Date the quote is due | 📎 |
setup | float | Optional one time free charged for set up expenses | 📎 |
total | float | Amount due after taxes and fees | 📎 |
upfront | float | The amount due when you accept the quote | 📎 |
subtotal | float | Amount due before taxes and fees | 📎 |
taxes | float | Amount due for taxes | 📎 |
quote_status_name | string | Human-friendly quote status | 📎 |
quote_status_str | string | Status string | 📎 |
quote_status_state | string | Status code | 📎 |
memo | string | Memo/notes to customer | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
Get a list of quotes
API Request
GET /api/v3/quote
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"quote_id": 1,
"terms_id": 2,
"admin_id": 1,
"currency_id": 1,
"token": "14km8c4v7n06",
"refnumber": "1",
"paycycle": "mon",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2019-07-25 15:58:48",
"quote_status_name": "Accepted",
"quote_status_str": "closed-won",
"quote_status_state": "c",
"currency_symbol": "$",
"currency_iso4217": "USD",
"total": 10.95,
"setup": 0,
"terms_name": "Net 30",
"date": "2019-07-25",
"due_date": "2019-08-24",
"bill_block": "United States",
"ship_block": "",
"url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/14km8c4v7n06",
"url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/14km8c4v7n06",
"url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/1",
"url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/14km8c4v7n06",
"url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/14km8c4v7n06",
"customer_id": 2
},
{
"quote_id": 2,
"terms_id": 2,
"admin_id": 1,
"currency_id": 1,
"token": "5906g19516kf",
"refnumber": "2",
"paycycle": "one",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2019-07-25 16:11:35",
"quote_status_name": "Accepted",
"quote_status_str": "closed-won",
"quote_status_state": "c",
"currency_symbol": "$",
"currency_iso4217": "USD",
"total": 10.95,
"setup": 0,
"terms_name": "Net 30",
"date": "2019-07-25",
"due_date": "2019-08-24",
"bill_block": "United States",
"ship_block": "",
"url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/5906g19516kf",
"url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/5906g19516kf",
"url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/2",
"url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/5906g19516kf",
"url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/5906g19516kf",
"customer_id": 2
}
]
}
Query for quotes
Available query parameter values for filtering:
quote_id
customer_id
brand_id
currency_id
refnumber
token
external_key
date
bill_state
ship_state
bill_country
ship_country
quote_status_str
quote_status_state
Valid values for quote_status_str:
- open-new
- open-sent
- closed-won
- closed-lost
Valid values for quote_status_state:
o
(any “open” quote, i.e. any that have not been accepted or lost)c
(any “closed” quote, i.e. any that have been accepted or lost)
By default, only the overview quote details are returned (i.e. no individual line items). If you get a specific quote by quote id value (e.g. GET /api/v3/quote/1234
) you'll get back the invoice line items
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
quote_id | integer | Quote ID # | 📎 |
refnumber | string | Quote reference number | 📎 |
external_key | string | External key value | 📎 |
paycycle | string | Payment cycle for the quote (e.g. monthly, etc.) | 📎 |
nickname | string | Quote nickname | 📎 |
customer_id | integer | Customer ID # | 📎 |
write_datetime | datetime | Date/time the quote was created | 📎 |
date | date | Quote date | 📎 |
validuntil_date | date | Quote valid until | 📎 |
holduntil_datetime_str | string | Date/time invoicing for the resulting subscription to be delayed until | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_symbol | string | Currency symbol | 📎 |
currency_iso4217 | string | Currency ISO 4217 representation | 📎 |
terms_id | integer | Terms ID # | 📎 |
class_id | integer | Class ID # for Quickbooks | 📎 |
terms_name | string | Terms name | 📎 |
terms_days | integer | Terms # of days | 📎 |
brand_id | integer | Brand ID # | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
admin_id | integer | Admin/Worker ID # | 📎 |
admin_name | string | Admin/Worker Name | 📎 |
token | string | Unique token | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (deprecated) | 📎 |
bill_block | string | Printable billing address | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (deprecated) | 📎 |
ship_block | string | Printable shipping address | 📎 |
url_permalink | string | URL to view the quote | 📎 |
url_pdflink | string | URL to get a PDF of the quote | 📎 |
url_self | string | URL for viewing the quote in the GUI | 📎 |
url_acceptlink | string | URL to visit to accept the quote | 📎 |
url_paylink | string | URL to visit to provide a payment method for the quote | 📎 |
url_rejectlink | string | URL to visit to reject the quote | 📎 |
url_acceptredirect | string | URL the lead should be redirected to after accepting a quote | 📎 |
url_rejectredirect | string | URL the lead should be redirected to after rejecting a quote | 📎 |
won_datetime | string | The Date/time that the quote was accepted | 📎 |
lost_datetime | string | The Date/time that the quote was rejected | 📎 |
due_date | date | Date the quote is due | 📎 |
setup | float | Optional one time free charged for set up expenses | 📎 |
total | float | Amount due after taxes and fees | 📎 |
upfront | float | The amount due when you accept the quote | 📎 |
subtotal | float | Amount due before taxes and fees | 📎 |
taxes | float | Amount due for taxes | 📎 |
quote_status_name | string | Human-friendly quote status | 📎 |
quote_status_str | string | Status string | 📎 |
quote_status_state | string | Status code | 📎 |
memo | string | Memo/notes to customer | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
Query for quotes
API Request
GET /api/v3/quote?where=customer_id:EQUALS:35,quote_status_state:EQUALS:o&limit=1000 HTTP/1.1
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"quote_id": 9,
"terms_id": 2,
"admin_id": null,
"external_key": "a0K3D000001Wv8cUAg",
"currency_id": 1,
"token": "i5d57esw422k",
"refnumber": "9",
"paycycle": "mon",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2020-05-04 17:13:35",
"quote_status_name": "New",
"quote_status_str": "open-new",
"quote_status_state": "o",
"currency_symbol": "$",
"currency_iso4217": "USD",
"total": 100.83,
"setup": 0,
"terms_name": "Net 30",
"date": "2020-05-04",
"due_date": "2020-06-03",
"paycycle_name": "Monthly",
"bill_block": "",
"ship_block": "",
"url_permalink": "https://example.chargeover.com/r/quote/view/i5d57esw422k",
"url_pdflink": "https://example.chargeover.com/r/quote/pdf/i5d57esw422k",
"url_self": "https://example.chargeover.com/admin/r/quote/view/9",
"url_acceptlink": "https://example.chargeover.com/r/quote/accept/i5d57esw422k",
"url_rejectlink": "https://example.chargeover.com/r/quote/reject/i5d57esw422k",
"customer_id": 35
}
]
}
Get a specific quote
If the quote has been turned into an invoice, there will be an invoices
attribute which links
to the related invoice.
If the quote has been turned into a subscription, there will be a packages
attribute which links
to the related subscription.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
quote_id | integer | Quote ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
refnumber | string | Quote reference number | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle for the quote (e.g. monthly, etc.) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Quote nickname | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
write_datetime | datetime | Date/time the quote was created | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
date | date | Quote date | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
validuntil_date | date | Quote valid until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime_str | string | Date/time invoicing for the resulting subscription to be delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_symbol | string | Currency symbol | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_iso4217 | string | Currency ISO 4217 representation | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # for Quickbooks | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_name | string | Terms name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_days | integer | Terms # of days | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_id | integer | Brand ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle_name | string | Payment cycle name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/Worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_name | string | Admin/Worker Name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
token | string | Unique token | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_block | string | Printable billing address | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_block | string | Printable shipping address | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_permalink | string | URL to view the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_pdflink | string | URL to get a PDF of the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_self | string | URL for viewing the quote in the GUI | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_acceptlink | string | URL to visit to accept the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_paylink | string | URL to visit to provide a payment method for the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_rejectlink | string | URL to visit to reject the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_acceptredirect | string | URL the lead should be redirected to after accepting a quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_rejectredirect | string | URL the lead should be redirected to after rejecting a quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
won_datetime | string | The Date/time that the quote was accepted | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lost_datetime | string | The Date/time that the quote was rejected | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
due_date | date | Date the quote is due | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
setup | float | Optional one time free charged for set up expenses | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
total | float | Amount due after taxes and fees | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
upfront | float | The amount due when you accept the quote | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
subtotal | float | Amount due before taxes and fees | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
taxes | float | Amount due for taxes | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quote_status_name | string | Human-friendly quote status | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quote_status_str | string | Status string | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
quote_status_state | string | Status code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
memo | string | Memo/notes to customer | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the quote
|
Get a specific quote
API Request
GET /api/v3/quote/198
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"quote_id": 198,
"terms_id": 2,
"admin_id": 1,
"currency_id": 1,
"token": "659m6ys792j0",
"refnumber": "198",
"paycycle": "mon",
"bill_addr1": "72 E Blue Grass Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Minneapolis",
"bill_state": "MN",
"bill_postcode": "55416",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"memo": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2019-08-14 10:38:50",
"quote_status_name": "Accepted",
"quote_status_str": "closed-won",
"quote_status_state": "c",
"currency_symbol": "$",
"currency_iso4217": "USD",
"total": 10.4,
"setup": 100,
"terms_name": "Net 30",
"date": "2019-08-14",
"due_date": "2019-09-13",
"bill_block": "72 E Blue Grass Road\r\nMinneapolis, MN 55416\r\nUnited States",
"ship_block": "",
"url_permalink": "https:\/\/example.chargeover.com\/r\/quote\/view\/659m6ys792j0",
"url_pdflink": "https:\/\/example.chargeover.com\/r\/quote\/pdf\/659m6ys792j0",
"url_self": "https:\/\/example.chargeover.com\/admin\/r\/quote\/view\/198",
"url_acceptlink": "https:\/\/example.chargeover.com\/r\/quote\/accept\/659m6ys792j0",
"url_rejectlink": "https:\/\/example.chargeover.com\/r\/quote\/reject\/659m6ys792j0",
"customer_id": 294,
"line_items": [
{
"quote_id": 198,
"item_id": 1,
"tierset_id": 175,
"descrip": "This is a ChargeOver test item.",
"line_rate": 10.95,
"line_quantity": 1,
"is_base": false,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"item_name": "My Test Service Plan",
"item_external_key": null,
"item_token": "d70a9a880d95",
"item_accounting_sku": null,
"line_total": 10.95,
"line_subtotal": 10.95,
"line_item_id": 367,
"tierset": {
"tierset_id": 175,
"currency_id": 1,
"setup": 100,
"base": 10.95,
"minimum": 0,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2019-08-14 10:38:45",
"mod_datetime": "2019-08-14 10:38:45",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 100.00",
"base_formatted": "$ 10.95",
"minimum_formatted": "$ 0.00",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
}
},
{
"quote_id": 198,
"item_id": 2,
"tierset_id": 174,
"descrip": "Discount",
"line_rate": 0,
"line_quantity": 1,
"is_base": false,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"item_name": "Discount",
"item_external_key": null,
"item_token": "62ucb1dhemv3",
"item_accounting_sku": null,
"line_total": 0,
"line_subtotal": 0,
"line_item_id": 368,
"tierset": {
"tierset_id": 174,
"currency_id": 1,
"setup": 0,
"base": 0,
"minimum": 0,
"percent": 5,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2019-08-14 10:38:40",
"mod_datetime": "2019-08-14 10:38:40",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 0.00",
"minimum_formatted": "$ 0.00",
"percent_formatted": "5 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
}
}
],
"sent": [],
"invoices": [],
"packages": [
{
"package_id": 44
}
]
}
}
Email a quote
Send a quote via email. You can specify an email template to use with the message_id
, which is the id number you see in the URL when you edit an email template in ChargeOver.
Email a quote
API Request
POST /api/v3/quote/9?action=email
Content-Type: application/json
{
"_comment": "Each of these is OPTIONAL, and can be used to over-ride the default email templates, etc.",
"email": "johndoe@send-quote-to.com",
"subject": "Test subject",
"body": "Override the default message body here",
"from": "you@your-company.com"
}
Convert a quote by paycycle
Notes:
Convert a quote based on its paycycle.
- A quote with a onetime paycycle will be converted into an invoice
- Anything else will become a subscription (package)
- "context_str" returns what the quote was converted into (invoice or package)
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
, ortokenized_id
value you want to use for payment, just specify that field and value - you do not need to specifypaymethod
at all in this case. - To use any credit card the customer already has on file, just specify
"paymethod": "crd"
. - To use any ACH/eCheck account the customer already has on file, just specify
"paymethod": "ach"
. - To use any payment method available for this customer, just specify
"paymethod": "any"
. - If you do not specify a payment method at all, ChargeOver will default to sending an invoice to the customer.
Optionally, when adding a new package, you can specify the payment cycle (how often the customer gets invoiced and/or charged for the subscription) by using the paycycle
field. There are several payment cycles you can set a package to run on:
dly
- Daily1wk
- Every week2wk
- Every other week116
- 1st and the 16th4wk
- Every four weeks8wk
- Every eight weeks30d
- Every 30 daysmon
- Monthly2mn
- Every other month12w
- Every twelve weeksqtr
- Quarterlysix
- Every six monthsyrl
- Yearly2yr
- Every 2 years3yr
- Every 3 years4yr
- Every 4 years5yr
- Every 5 years10y
- Every 10 years
If you do not specify a paycycle
, the payment cycle for the subscription will set to the default payment cycle configured in your account's General Settings.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Nickname for the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the subscription
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Create a subscription
API Request
POST /api/v3/package HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 5,
"nickname": "Example nickname",
"paycycle": "mon",
"custom_1": "Example",
"coupon": "Example Coupon",
"holduntil_datetime": "2023-10-01",
"line_items": [
{
"item_id": 1,
"descrip": "Here is a description for my line item.",
"line_quantity": 15
}
]
}
Create a subscription (custom pricing)
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Nickname for the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the subscription
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Create a subscription (custom pricing)
API Request
POST /api/v3/package HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 5,
"holduntil_datetime": "2013-10-01",
"paymethod": "crd",
"creditcard_id": 38,
"line_items": [
{
"item_id": 2,
"descrip": "Here is a description for my line item.",
"tierset": {
"base": 35,
"pricemodel": "fla",
"paycycle": "evy"
}
}
]
}
Create a subscription (mixed payment cycles)
ChargeOver supports mixed payment cycle subscriptions, e.g. where part of the subscription is monthly, and part of it is yearly.
Each line item can have it's own payment cycle, as defined by the paycycle
attribute. If you do not
define a payment cycle for the line, it defaults to the payment cycle set on the product/discount being used.
Important: Invoices are created using the paycycle
of the subscription itself.
Generally, your subscription payment cycle should be equal to the shortest payment cycle your lines use.
Examples:
- Subscription
paycycle=mon
(monthly), Linepaycycle=yrl
(yearly) - invoices are created monthly, but the line will only occur once per year. - Subscription
paycycle=yrl
(yearly), Linepaycycle=mon
(monthly) - invoices are created yearly, and each invoice will contain 12 lines (one for each month).
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Nickname for the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the subscription
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Create a subscription (mixed payment cycles)
API Request
POST /api/v3/package
Content-Type: application/json
Authorization: Basic RzhhdmlEbEsyNUhnc0wxakp0OXdFUGh6cEJVb3hxTlM6ZVVTQmJncjRtTHEwTlFUNXNPWnREZmt5Q0tZOHhNbGE
{
"customer_id": 5,
"paycycle": "mon",
"line_items": [
{
"item_id": 1,
"descrip": "Yearly product.",
"tierset": {
"base": 120,
"pricemodel": "fla",
"paycycle": "yrl"
}
},
{
"item_id": 1,
"descrip": "Monthly product.",
"tierset": {
"base": 10.95,
"pricemodel": "fla",
"paycycle": "mon"
}
}
]
}
Create a subscription (prorated)
You can create prorated subscriptions which either generate a prorated invoice right away, or put the prorated charge on the next invoice.
The example to the right creates a new subscription, and generates a prorated invoice for the period March 12, to the end of March. The next invoice date will be April 1.
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Nickname for the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the subscription
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 |
Create a subscription (prorated)
API Request
POST /api/v3/package
{
"customer_id": 19879,
"paycycle": "mon",
"line_items": [
{
"item_id": 1,
"descrip": "Here is a description for my line item.",
"line_quantity": 15,
"subscribe_prorate": true,
"subscribe_prorate_cycle": "now",
"subscribe_prorate_when": "pre",
"subscribe_prorate_from_datetime": "2023-03-12",
"subscribe_prorate_to_datetime": "2023-03-31"
}
]
}
Update a subscription
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
class_id | integer | Class ID # | 📎 |
external_key | string | External key value | 📎 |
nickname | string | Nickname for the subscription | 📎 |
admin_id | integer | Admin/worker ID # | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (Deprecated) | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (Deprecated) | 📎 |
terms_id | integer | Terms ID # | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 |
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 |
tags | array | A list of tags | 📎 |
Get a list of subscriptions
Returns a list of all subscriptions
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
package_id | integer | Subscription ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
brand_name | string | Brand name | 📎 |
class_id | integer | Class ID # | 📎 |
class_name | string | Class name | 📎 |
external_key | string | External key value | 📎 |
token | string | Unique token | 📎 |
nickname | string | Nickname for the subscription | 📎 |
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 |
paymethod_name | string | Payment method for the subscription (e.g. Credit Card) | 📎 |
paymethod_detail | string | Payment method details (e.g. "Visa x1111") | 📎 |
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 |
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 |
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 |
admin_id | integer | Admin/worker ID # | 📎 |
admin_name | string | Admin/worker name | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (Deprecated) | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (Deprecated) | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | Currency ISO 4217 code | 📎 |
currency_symbol | string | Currency symbol | 📎 |
amount_collected | float | Total amount collected so far for this subscription | 📎 |
amount_invoiced | float | Total amount invoiced so far | 📎 |
amount_due | float | Total amount due (invoiced - collected) | 📎 |
amount_overdue | float | Total amount past due | 📎 |
suspendfrom_datetime | datetime | Date/time this subscription was suspended from | 📎 |
suspendto_datetime | datetime | Date/time this subscription was suspended to | 📎 |
next_invoice_datetime | datetime | The date the next invoice will be generated | 📎 |
is_overdue | boolean | Whether or not the subscription is overdue | 📎 |
days_overdue | integer | # of days overdue the subscription is | 📎 |
start_datetime | datetime | Date/time this subscription was started/effective | 📎 |
cancel_datetime | datetime | Date/time this subscription was cancelled | 📎 |
write_datetime | datetime | Date/time this subscription was created | 📎 |
mod_datetime | datetime | Date/time this subscription was last updated, upgraded, downgraded, etc.) | 📎 |
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 |
package_status_id | integer | Subscription status ID # | 📎 |
package_status_name | string | Human-friendly subscription status | 📎 |
package_status_str | string | Status string | 📎 |
package_status_state | string | Status code | 📎 |
mrr | float | Current monthly recurring revenue of the subscription | 📎 |
arr | float | Current annual recurring revenue of the subscription | 📎 |
cancel_reason | string | Reason for cancellation | 📎 |
terms_id | integer | Terms ID # | 📎 |
terms_name | string | Payment terms | 📎 |
terms_days | integer | Terms # of days | 📎 |
paycycle | string | Payment cycle | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 |
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 |
url_self | string | URL for viewing the subscription in the GUI | 📎 |
Get a list of subscriptions
API Request
GET api/v3/package
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"terms_id": 3,
"class_id": null,
"admin_id": 4,
"currency_id": 1,
"brand_id": 1,
"external_key": null,
"token": "3u8419j8zq21",
"nickname": "",
"paymethod": "crd",
"paycycle": "yrl",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"creditcard_id": 44,
"ach_id": null,
"tokenized_id": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-06-30 08:37:41",
"mod_datetime": "2017-06-30 08:37:41",
"start_datetime": "2017-06-30 08:37:41",
"suspendfrom_datetime": null,
"suspendto_datetime": null,
"cancel_datetime": null,
"holduntil_datetime": null,
"terms_name": "Due on Receipt",
"terms_days": 0,
"currency_symbol": "$",
"currency_iso4217": "USD",
"class_name": "",
"amount_collected": 1030,
"amount_invoiced": 1030,
"amount_due": 0,
"is_overdue": false,
"days_overdue": 0,
"next_invoice_datetime": "2018-06-30 06:00:01",
"cancel_reason": null,
"url_self": "https://dev.chargeover.com/admin/r/package/view/602",
"package_id": 602,
"customer_id": 10,
"package_status_id": 2,
"package_status_name": "Current",
"package_status_str": "active-current",
"package_status_state": "a"
},
......
{
"terms_id": 3,
"class_id": null,
"admin_id": null,
"currency_id": 1,
"brand_id": 1,
"external_key": null,
"token": "7ek3bodjzyg2",
"nickname": "",
"paymethod": "ach",
"paycycle": "mon",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"creditcard_id": null,
"ach_id": 4,
"tokenized_id": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-07-28 11:37:43",
"mod_datetime": "2017-07-28 11:37:43",
"start_datetime": "2017-07-28 11:37:43",
"suspendfrom_datetime": null,
"suspendto_datetime": null,
"cancel_datetime": "2017-09-25 14:18:06",
"holduntil_datetime": null,
"terms_name": "Due on Receipt",
"terms_days": 0,
"currency_symbol": "$",
"currency_iso4217": "USD",
"class_name": "",
"amount_collected": 500,
"amount_invoiced": 500,
"amount_due": 0,
"is_overdue": false,
"days_overdue": 0,
"next_invoice_datetime": null,
"cancel_reason": "Unknown or unspecified reason",
"url_self": "https://dev.chargeover.com/admin/r/package/view/611",
"package_id": 611,
"customer_id": 27,
"package_status_id": 5,
"package_status_name": "Canceled manually",
"package_status_str": "canceled-manual",
"package_status_state": "c"
}
]
}
Get a specific subscription
Object Attributes
Attribute | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
package_id | integer | Subscription ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer_id | integer | Customer ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_id | integer | Brand ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
brand_name | string | Brand name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_id | integer | Class ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
class_name | string | Class name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
external_key | string | External key value | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
token | string | Unique token | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
nickname | string | Nickname for the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod_name | string | Payment method for the subscription (e.g. Credit Card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paymethod_detail | string | Payment method details (e.g. "Visa x1111") | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_id | integer | Admin/worker ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
admin_name | string | Admin/worker name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr1 | string | Billing address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr2 | string | Billing address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_addr3 | string | Billing address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_city | string | Billing address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_state | string | Billing address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_postcode | string | Billing address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_country | string | Billing address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
bill_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr1 | string | Shipping address line 1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr2 | string | Shipping address line 2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_addr3 | string | Shipping address line 3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_city | string | Shipping address city | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_state | string | Shipping address state | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_postcode | string | Shipping address postal code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_country | string | Shipping address country | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
ship_notes | string | (Deprecated) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_id | integer | Currency ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_iso4217 | string | Currency ISO 4217 code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
currency_symbol | string | Currency symbol | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount_collected | float | Total amount collected so far for this subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount_invoiced | float | Total amount invoiced so far | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount_due | float | Total amount due (invoiced - collected) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount_overdue | float | Total amount past due | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
suspendfrom_datetime | datetime | Date/time this subscription was suspended from | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
suspendto_datetime | datetime | Date/time this subscription was suspended to | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
next_invoice_datetime | datetime | The date the next invoice will be generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_overdue | boolean | Whether or not the subscription is overdue | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
days_overdue | integer | # of days overdue the subscription is | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
start_datetime | datetime | Date/time this subscription was started/effective | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancel_datetime | datetime | Date/time this subscription was cancelled | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
write_datetime | datetime | Date/time this subscription was created | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mod_datetime | datetime | Date/time this subscription was last updated, upgraded, downgraded, etc.) | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
package_status_id | integer | Subscription status ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
package_status_name | string | Human-friendly subscription status | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
package_status_str | string | Status string | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
package_status_state | string | Status code | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mrr | float | Current monthly recurring revenue of the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
arr | float | Current annual recurring revenue of the subscription | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
cancel_reason | string | Reason for cancellation | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_id | integer | Terms ID # | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_name | string | Payment terms | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
terms_days | integer | Terms # of days | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle | string | Payment cycle | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
paycycle_name | string | Payment cycle name | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_1 | mixed | Custom field #1 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_2 | mixed | Custom field #2 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_3 | mixed | Custom field #3 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_4 | mixed | Custom field #4 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_5 | mixed | Custom field #5 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_6 | mixed | Custom field #6 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_7 | mixed | Custom field #7 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_8 | mixed | Custom field #8 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_9 | mixed | Custom field #9 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_10 | mixed | Custom field #10 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_11 | mixed | Custom field #11 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_12 | mixed | Custom field #12 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_13 | mixed | Custom field #13 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_14 | mixed | Custom field #14 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_15 | mixed | Custom field #15 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_16 | mixed | Custom field #16 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_17 | mixed | Custom field #17 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_18 | mixed | Custom field #18 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_19 | mixed | Custom field #19 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
custom_20 | mixed | Custom field #20 | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
line_items - array A list of line items for the subscription
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tags | array | A list of tags | 📎 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
url_self | string | URL for viewing the subscription in the GUI | 📎 |
Get a specific subscription
API Request
GET /api/v3/package/21
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"terms_id": 2,
"class_id": null,
"admin_id": 3,
"currency_id": 1,
"brand_id": 1,
"external_key": null,
"token": "1tk5j5u2efhi",
"nickname": "",
"paymethod": "inv",
"paycycle": "mon",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"creditcard_id": null,
"ach_id": null,
"tokenized_id": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"custom_4": null,
"custom_5": null,
"write_datetime": "2017-09-20 12:33:44",
"mod_datetime": "2017-09-20 12:33:44",
"start_datetime": "2017-09-20 12:33:44",
"suspendfrom_datetime": null,
"suspendto_datetime": null,
"cancel_datetime": null,
"holduntil_datetime": null,
"terms_name": "Net 30",
"terms_days": 30,
"currency_symbol": "$",
"currency_iso4217": "USD",
"amount_collected": 0,
"amount_invoiced": 250,
"amount_due": 250,
"is_overdue": false,
"days_overdue": 0,
"next_invoice_datetime": "2017-10-20 00:00:01",
"cancel_reason": null,
"url_self": "http:\/\/dev.chargeover.com\/admin\/r\/package\/view\/21",
"package_id": 21,
"customer_id": 22,
"package_status_id": 2,
"package_status_name": "Current",
"package_status_str": "active-current",
"package_status_state": "a",
"line_items": [
{
"item_id": 254,
"tierset_id": 16,
"admin_id": null,
"external_key": null,
"nickname": "",
"descrip": null,
"line_quantity": 1,
"trial_days": 0,
"trial_recurs": "0",
"trial_units": 0,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"subscribe_datetime": "2017-09-20 12:33:44",
"subscribe_prorate_from_datetime": null,
"subscribe_prorate_to_datetime": null,
"cancel_datetime": null,
"expire_datetime": null,
"expire_recurs": null,
"item_name": "Premium Silver",
"item_external_key": null,
"item_accounting_sku": null,
"item_token": "8225neo3wmp4",
"item_type": "service",
"item_units": null,
"item_is_usage": false,
"line_item_id": 23,
"package_id": 21,
"tierset": {
"tierset_id": 16,
"currency_id": 1,
"setup": 0,
"base": 250,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2017-09-20 12:29:32",
"mod_datetime": "2017-09-20 12:29:32",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 250.00",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
}
}
]
}
}
Querying for subscriptions
Available query parameter values for filtering:
package_id
customer_id
token
brand_id
custom_N
- Example:custom_1
,custom_2
, etc.paymethod
paycycle
nickname
bill_state
ship_state
package_status_str
package_status_state
external_key
write_datetime
- date/time createdmod_datetime
- date/time last modifiedcancel_datetime
quote.quote_id
- Get the subscription that originated from a specific quoteline_items.external_key
line_items.custom_1
line_items.item_id
- Get subscriptions that contain a specific product/discountcustomer.superuser_email
- Get subscriptions for a specific primary contact email addresscustomer.users.email
- Get subscriptions with this email address
Valid values for package_status_state
:
a
(for active packages)c
(for cancelled packages)e
(for expired packages)s
(for suspended packages)
Valid values for package_status_str
:
- active-trial
- active-current
- active-overdue
- canceled-nonpayment
- canceled-manual
- expired-expired
- expired-trial
- suspended-suspended
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
package_id | integer | Subscription ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
brand_id | integer | Brand ID # | 📎 |
brand_name | string | Brand name | 📎 |
class_id | integer | Class ID # | 📎 |
class_name | string | Class name | 📎 |
external_key | string | External key value | 📎 |
token | string | Unique token | 📎 |
nickname | string | Nickname for the subscription | 📎 |
paymethod | string | Payment method for the subscription, one of: crd, inv, ach, tok | 📎 |
paymethod_name | string | Payment method for the subscription (e.g. Credit Card) | 📎 |
paymethod_detail | string | Payment method details (e.g. "Visa x1111") | 📎 |
creditcard_id | integer | Credit card ID # (if the subscription is paid by credit card) | 📎 |
ach_id | integer | ACH ID # (if the subscription is paid by ACH) | 📎 |
tokenized_id | integer | Tokenized ID # (if the subscription is paid by an external service token) | 📎 |
admin_id | integer | Admin/worker ID # | 📎 |
admin_name | string | Admin/worker name | 📎 |
bill_addr1 | string | Billing address line 1 | 📎 |
bill_addr2 | string | Billing address line 2 | 📎 |
bill_addr3 | string | Billing address line 3 | 📎 |
bill_city | string | Billing address city | 📎 |
bill_state | string | Billing address state | 📎 |
bill_postcode | string | Billing address postal code | 📎 |
bill_country | string | Billing address country | 📎 |
bill_notes | string | (Deprecated) | 📎 |
ship_addr1 | string | Shipping address line 1 | 📎 |
ship_addr2 | string | Shipping address line 2 | 📎 |
ship_addr3 | string | Shipping address line 3 | 📎 |
ship_city | string | Shipping address city | 📎 |
ship_state | string | Shipping address state | 📎 |
ship_postcode | string | Shipping address postal code | 📎 |
ship_country | string | Shipping address country | 📎 |
ship_notes | string | (Deprecated) | 📎 |
currency_id | integer | Currency ID # | 📎 |
currency_iso4217 | string | Currency ISO 4217 code | 📎 |
currency_symbol | string | Currency symbol | 📎 |
amount_collected | float | Total amount collected so far for this subscription | 📎 |
amount_invoiced | float | Total amount invoiced so far | 📎 |
amount_due | float | Total amount due (invoiced - collected) | 📎 |
amount_overdue | float | Total amount past due | 📎 |
suspendfrom_datetime | datetime | Date/time this subscription was suspended from | 📎 |
suspendto_datetime | datetime | Date/time this subscription was suspended to | 📎 |
next_invoice_datetime | datetime | The date the next invoice will be generated | 📎 |
is_overdue | boolean | Whether or not the subscription is overdue | 📎 |
days_overdue | integer | # of days overdue the subscription is | 📎 |
start_datetime | datetime | Date/time this subscription was started/effective | 📎 |
cancel_datetime | datetime | Date/time this subscription was cancelled | 📎 |
write_datetime | datetime | Date/time this subscription was created | 📎 |
mod_datetime | datetime | Date/time this subscription was last updated, upgraded, downgraded, etc.) | 📎 |
holduntil_datetime | datetime | Date/time invoicing for this subscription is being delayed until | 📎 |
package_status_id | integer | Subscription status ID # | 📎 |
package_status_name | string | Human-friendly subscription status | 📎 |
package_status_str | string | Status string | 📎 |
package_status_state | string | Status code | 📎 |
mrr | float | Current monthly recurring revenue of the subscription | 📎 |
arr | float | Current annual recurring revenue of the subscription | 📎 |
cancel_reason | string | Reason for cancellation | 📎 |
terms_id | integer | Terms ID # | 📎 |
terms_name | string | Payment terms | 📎 |
terms_days | integer | Terms # of days | 📎 |
paycycle | string | Payment cycle | 📎 |
paycycle_name | string | Payment cycle name | 📎 |
custom_1 | mixed | Custom field #1 | 📎 |
custom_2 | mixed | Custom field #2 | 📎 |
custom_3 | mixed | Custom field #3 | 📎 |
custom_4 | mixed | Custom field #4 | 📎 |
custom_5 | mixed | Custom field #5 | 📎 |
custom_6 | mixed | Custom field #6 | 📎 |
custom_7 | mixed | Custom field #7 | 📎 |
custom_8 | mixed | Custom field #8 | 📎 |
custom_9 | mixed | Custom field #9 | 📎 |
custom_10 | mixed | Custom field #10 | 📎 |
custom_11 | mixed | Custom field #11 | 📎 |
custom_12 | mixed | Custom field #12 | 📎 |
custom_13 | mixed | Custom field #13 | 📎 |
custom_14 | mixed | Custom field #14 | 📎 |
custom_15 | mixed | Custom field #15 | 📎 |
custom_16 | mixed | Custom field #16 | 📎 |
custom_17 | mixed | Custom field #17 | 📎 |
custom_18 | mixed | Custom field #18 | 📎 |
custom_19 | mixed | Custom field #19 | 📎 |
custom_20 | mixed | Custom field #20 | 📎 |
first_invoice_schedule_template_id | integer | Payment schedule to use for the first invoice generated | 📎 |
recurring_invoice_schedule_template_id | integer | Payment schedule to use for subsequent generated invoices | 📎 |
url_self | string | URL for viewing the subscription in the GUI | 📎 |
Querying for subscriptions
API Request
GET /api/v3/package?where=package_status_state:EQUALS:a,customer_id:EQUALS:16
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"terms_id": 3,
"currency_id": 1,
"external_key": "adlink_5901",
"nickname": "",
"paymethod": "crd",
"paycycle": "mon",
"bill_addr1": null,
"bill_addr2": null,
"bill_addr3": null,
"bill_city": null,
"bill_state": null,
"bill_postcode": null,
"bill_country": null,
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"creditcard_id": 53,
"ach_id": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2014-06-20 15:52:47",
"mod_datetime": "2014-06-20 15:52:57",
"suspendfrom_datetime": null,
"suspendto_datetime": null,
"cancel_datetime": null,
"holduntil_datetime": null,
"currency_symbol": "$",
"currency_iso4217": "USD",
"amount_collected": 0,
"amount_invoiced": 0,
"amount_due": 0,
"next_invoice_datetime": "2014-09-01 00:00:01",
"package_id": 16,
"customer_id": 16,
"package_status_id": 2,
"package_status_name": "Current",
"package_status_str": "active-current",
"package_status_state": "a"
}
]
}
Upgrade/downgrade a subscription
When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:
- Change a customer’s product to a different product
- Change the amount a customer is charged each month
- Add or remove products that are charged each month
Upgrade/downgrade a subscription
API Request
POST /api/v3/package/554?action=upgrade HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"line_items": [
{
"_comment": "If you want to change the quantity, specify the new quantity here",
"line_item_id": 1953,
"item_id": 239,
"descrip": "A new description goes here",
"line_quantity": 123
}
]
}
Upgrade/downgrade a subscription (and prorate amounts)
When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:
- Change a customer’s product to a different product
- Change the amount a customer is charged each month
- Add or remove products that are charged each month
Upgrade/downgrade a subscription (and prorate amounts)
API Request
POST /api/v3/package/612?action=upgrade
{
"line_items": [
{
"_comment": "This tells ChargeOver to credit back the unused portion of the old product.",
"line_item_id": 729,
"item_id": 14,
"descrip": "Upgraded description goes here",
"line_quantity": 1,
"subscribe_prorate": true,
"subscribe_prorate_cycle": "now",
"subscribe_prorate_when": "pre",
"cancel_prorate": true,
"cancel_prorate_credit": true,
"cancel_prorate_cycle": "now"
}
]
}
Upgrade a subscription by adding a line item (and prorate amounts)
When you want to change how the services one of your customers is billing for, you’ll go through the upgrade/downgrade process. The upgrade/downgrade process allows you to:
- Change a customer’s product to a different product
- Change the amount a customer is charged each month
- Add or remove products that are charged each month
This example shows how to add a line item to a customer's subscription AND how to create a prorated invoice for the new amount.
- The
subscribe_prorate_from_datetime
andsubscribe_prorate_to_datetime
fields are optional -- if you don't specify dates, ChargeOver will assume the current date until the end of the current billing cycle - The
subscribe_prorate_cycle
options are:"now"
(generate an invoice for the prorated amount right now) or"next"
(add the prorated charge to the next invoice that will be generated at the end of the billing cycle)
Upgrade a subscription by adding a line item (and prorate amounts)
API Request
POST /api/v3/package/49?action=upgrade
{
"line_items": [
{
"_comment": "This tells ChargeOver to create an invoice for the new prorated amount right away (billing in advance).",
"item_id": 1,
"descrip": "The description of the new line item",
"line_quantity": 1,
"subscribe_prorate": true,
"subscribe_prorate_cycle": "now",
"subscribe_prorate_when": "pre",
"subscribe_prorate_from_datetime": "2018-04-20"
}
]
}
Cancel a line item on a subscription
It is also possible to cancel a specific line item on a subscription so that the customer will no longer be billed for it on future invoices.
The example to the right shows how to cancel a line item on a subscription using the line_item_id
of
the line item(s) you want to cancel.
If you cancel all of the lines on the subscription, the default behavior is to leave the subscription itself
active (but with no line items). If you want to cancel the subscription itself when all of the line items are
cancelled, you can also specify: "cancel_package_if_last_line_item": true
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
Schedule price update on a subscription (set the price)
Scheduling a price update automatically changes the subscription price on the date specified.
The example to the right shows how to schedule a price update on a subscription by explicitly setting the price.
Valid values forpricemodel
fla
- Flat Pricing (example: $X dollars every billing cycle)uni
- Unit Pricing (example: $X per unit every billing cycle)vol
- Volume Pricing (example: $X dollars every billing cycle, with different price levels depending on volume)tie
- Tiered Pricing (example: $X dollars every billing cycle for the first 10 units, then $Y dollars per month for the next 10 units, etc.)
Schedule price update on a subscription (set the price)
API Request
POST /api/v3/package/585?action=schedulePriceChange
{
"schedule_lines": [
{
"package_line_id": 590,
"this_change_date": "2025-01-01",
"this_change_details": {
"pricemodel": {
"pricemodel": "fla",
"base": 9.99
}
}
},
{
"package_line_id": 590,
"this_change_date": "2026-01-01",
"this_change_details": {
"pricemodel": {
"pricemodel": "vol",
"base": 10,
"tiers": [
{
"unit_from": 1,
"unit_to": 10,
"amount": 8.99
},
{
"unit_from": 11,
"unit_to": 20,
"amount": 7.99
}
]
}
}
}
]
}
Schedule price update on a subscription (increase the price by percentage)
Scheduling a price update automatically changes the subscription price on the date specified.
The example to the right shows how to schedule a price update on a subscription by using a percentage to increase the price.
Schedule recurring price update on a subscription
Automatically increase your subscription price at regular intervals by scheduling a recurring price update.
The example to the right shows how to schedule a recurring price update on a subscription.
The recurring price update will only take effect after all your one-time schedules have been run.
Valid paycyclesdly
- Daily1wk
- Weeklymon
- Monthlyqtr
- Quarterlyyrl
- Yearly
Schedule recurring price update on a subscription
Invoice a subscription now
The default behavior when creating a recurring package via the ChargeOver REST API is to generate the first invoice on the following day.
You can trigger the immediate generation of an invoice by calling this method. By default, the invoice created will be dated with today's date.
You can also immediately generate future-dated invoices by specifying a
date
attribute in YYYY-MM-DD
format. There is
also one special date, the string NEXT_SCHEDULED_INVOICE
,
which will generate an invoice dated with the date of the next normally
scheduled invoice.
Adjust the next invoice date for a subscription
This will change the date that the next invoice for a subscription is generated on.
For example, if you specify the holduntil_datetime
to be "2019-10-03"
, the next date that an invoice will be generated on for that subscription will be changed to October 3, 2019.
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 (range)
Suspend a subscription (range)
Unsuspend a subscription
Unsuspend a subscription
API Request
POST /api/v3/package/1965?action=unsuspend HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Cancel a subscription
This allows you to cancel a subscription immediately, or to schedule a subscription to cancel on a future date.
To cancel immediately, do not specify a cancel_date
value. To schedule a future cancellation, pass in a cancel_date
value (formatted as YYYY-MM-DD
) to specify the future cancellation date.
Cancel a subscription
API Request
POST /api/v3/package/600?action=cancel
{
"_comment_reason": "The [cancel_reason_id] fields is optional; you do not need to include it.",
"cancel_reason_id": 1,
"_comment_date": "The [cancel_date] field is optional. Specify a date in the future to schedule the subscription for future cancellation.",
"cancel_date": "2023-10-24"
}
Change the payment cycle
Valid values for specifying paycycle
:
dly
- daily1wk
- weekly2wk
- 2 weeks4wk
- 4 weeks2mn
- 2 monthsmon
- monthlyqtr
- quarterlyyrl
- yearly2yr
- 2 years3yr
- 3 years4yr
- 4 years5yr
- 5 years10y
- 10 yearssix
- 6 months30d
- 30 days8wk
- 8 weeks12w
- 12 weeks
Set the payment method
Valid values for specifying paymethod:
inv
- Generate an invoice for the subscription but do not take an automatic paymentcrd
- Credit Cardach
- ACH/eChecktok
- Tokenized payment method
Additionally:
- If you specify
crd
you must specify thecreditcard_id
- If you specify
ach
you must specify theach_id
- If you specify
tok
you must specify thetokenized_id
Set the payment method
Send a welcome e-mail
This will send a welcome e-mail (using your welcome e-mail template) to the primary contact for the package/customer.
Send a welcome e-mail
API Request
POST /api/v3/package/616?action=sendWelcome
Content-Type: application/json
{
"_comment": "All attributes are optional, and can be used to override the default email templates, etc.",
"email": "to@example.com",
"cc": "cc@example.com",
"bcc": "bcc@example.com",
"subject": "Override the default subject",
"body": "Override the default plain-text body of the email",
"html": "Override the default <b>HTML body<\/b> of the email",
"from": "\"Example Company\" <from@example.com>",
"_comment_message_id": "You can optionally specify a message_id value to use a specific email template.",
"message_id": 2
}
Items (Products, Discounts)
Create an item
The response/id value will be the item_id value for the newly created item.
Valid values forpaycycle
evy
- Every billing cycledly
- Daily1wk
- Every week2wk
- Every other week116
- 1st and the 16th4wk
- Every four weeks8wk
- Every eight weeks30d
- Every 30 daysmon
- Monthly2mn
- Every other month12w
- Every twelve weeksqtr
- Quarterlysix
- Every six monthsyrl
- Yearly2yr
- Every 2 years3yr
- Every 3 years4yr
- Every 4 years5yr
- Every 5 years10y
- Every 10 years
pricemodel
fla
- Flat Pricing (example: $X dollars every billing cycle)uni
- Unit Pricing (example: $X per unit every billing cycle)vol
- Volume Pricing (example: $X dollars every billing cycle, with different price levels depending on volume)tie
- Tiered Pricing (example: $X dollars every billing cycle for the first 10 units, then $Y dollars per month for the next 10 units, etc.)pas
- Pass-through from usage data (Pass-through pricing is for scenarios where the usage data and the pricing is already known)
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
item_type | string | Item type | 📎 |
name | string | Item name | 📎 |
description | string | Description | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
accounting_sku | string | Accounting SKU | 📎 |
accounting_account_income | string | Accounting Income Account | 📎 |
external_key | string | External key value | 📎 |
units | string | Units string | 📎 |
tax_group_id | integer | Tax group ID # | 📎 |
expire_recurs | integer | Default # of times to recur | 📎 |
trial_recurs | integer | Default # of times to skip/free trial cycles | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
Create an item
Querying for items
Available query parameter values for filtering:
- item_id
- name
- external_key
- accounting_sku
- item_type
- custom_1
- custom_2
- custom_3
item_type
service
(for Services)discount
(for Discounts)
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
item_id | integer | Item ID # | 📎 |
item_type | string | Item type | 📎 |
name | string | Item name | 📎 |
description | string | Description | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
accounting_sku | string | Accounting SKU | 📎 |
accounting_account_income | string | Accounting Income Account | 📎 |
external_key | string | External key value | 📎 |
units | string | Units string | 📎 |
units_plural | string | Units string pluralized | 📎 |
tax_group_id | integer | Tax group ID # | 📎 |
tax_group_name | string | Tax group name | 📎 |
expire_recurs | integer | Default # of times to recur | 📎 |
trial_recurs | integer | Default # of times to skip/free trial cycles | 📎 |
token | string | Unique token | 📎 |
tierset_id | integer | Default pricing tierset ID # | 📎 |
write_datetime | datetime | Date/time the item was created | 📎 |
mod_datetime | datetime | Date/time the item was last updated | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
Querying for items
API Request
GET /api/v3/item?where=item_type:EQUALS:service
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"item_id": 1,
"item_type": "service",
"tierset_id": 1,
"name": "My Test Service Plan",
"description": "This is a ChargeOver test item.",
"units": "",
"accounting_sku": null,
"external_key": null,
"token": "d56c047651ec",
"custom_1": "",
"custom_2": "",
"custom_3": "",
"write_datetime": "2014-12-02 18:46:48",
"mod_datetime": "2014-12-02 18:46:48",
"units_plural": "",
"tiersets": [
{
"tierset_id": 1,
"setup": 0,
"base": 10.95,
"paycycle": "mon",
"pricemodel": "fla",
"write_datetime": "2014-12-02 18:46:48",
"mod_datetime": "2014-12-02 18:46:48",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 10.95",
"pricemodel_desc": "Flat Pricing (e.g. $X dollars per month)",
"tiers": []
}
]
}
]
}
Get a specific item
Get a specific item using its item_id
.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
item_id | integer | Item ID # | 📎 |
item_type | string | Item type | 📎 |
name | string | Item name | 📎 |
description | string | Description | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
accounting_sku | string | Accounting SKU | 📎 |
accounting_account_income | string | Accounting Income Account | 📎 |
external_key | string | External key value | 📎 |
units | string | Units string | 📎 |
units_plural | string | Units string pluralized | 📎 |
tax_group_id | integer | Tax group ID # | 📎 |
tax_group_name | string | Tax group name | 📎 |
expire_recurs | integer | Default # of times to recur | 📎 |
trial_recurs | integer | Default # of times to skip/free trial cycles | 📎 |
token | string | Unique token | 📎 |
tierset_id | integer | Default pricing tierset ID # | 📎 |
write_datetime | datetime | Date/time the item was created | 📎 |
mod_datetime | datetime | Date/time the item was last updated | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
Get a specific item
API Request
GET /api/v3/item/12
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"item_id": 12,
"item_type": "service",
"tierset_id": 24,
"name": "My Test Service Plan",
"description": null,
"units": null,
"enabled": true,
"accounting_sku": null,
"external_key": null,
"token": "c162794b20v7",
"custom_1": null,
"custom_2": null,
"custom_3": null,
"write_datetime": "2019-10-07 11:15:51",
"mod_datetime": "2019-10-07 11:15:51",
"units_plural": "",
"expire_recurs": null,
"trial_recurs": null,
"service_data": {
"trial_days": 0,
"trial_units": 0,
"is_usage": false
},
"tiersets": [
{
"tierset_id": 24,
"currency_id": 1,
"setup": 0,
"base": 100,
"minimum": 0,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2019-10-07 11:15:51",
"mod_datetime": "2019-10-07 11:15:51",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 100.00",
"minimum_formatted": "$ 0.00",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
},
{
"tierset_id": 24,
"currency_id": 1,
"setup": 0,
"base": 100,
"minimum": 0,
"percent": 0,
"paycycle": "evy",
"pricemodel": "fla",
"write_datetime": "2019-10-07 11:15:51",
"mod_datetime": "2019-10-07 11:15:51",
"currency_symbol": "$",
"currency_iso4217": "USD",
"setup_formatted": "$ 0.00",
"base_formatted": "$ 100.00",
"minimum_formatted": "$ 0.00",
"percent_formatted": "0 %",
"pricemodel_desc": "Flat Pricing (example: $X dollars every billing cycle)",
"tiers": []
}
],
"categories": []
}
}
Update an item
This allows you to update an existing product. When updating a product, you can specify the pricing for multiple currencies if desired.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
name | string | Item name | 📎 |
description | string | Description | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
accounting_sku | string | Accounting SKU | 📎 |
accounting_account_income | string | Accounting Income Account | 📎 |
external_key | string | External key value | 📎 |
units | string | Units string | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
Delete an item
This allows you to delete a product that is not in use. You will only be able to delete a product if it is not on any invoices or subscriptions.
Credit Cards
Store a credit card
This method can be used to store a new card or update an existing card.
To update an existing card: Send a new POST request using an existing card number
with its updated values. The stored card will then be updated.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | The customer id # | 📎 |
external_key | string | Unique external key value | 📎 |
name | string | Name on credit card | 📎 |
number | string | Credit card number | 📎 |
cvv | string | CVV/CSC security code (not stored, but may be used for validation/pre-auth) | 📎 |
expdate | string | Expiration date (in YYYY-MM-DD format) | 📎 |
expdate_year | string | Expiration year (4-digits, YYYY) (only required if you do not provide expdate) | 📎 |
expdate_month | string | Expiration month (2-digits, MM) (only required if you do not provide expdate) | 📎 |
address | string | Billing street address | 📎 |
city | string | Billing city | 📎 |
state | string | Billing state | 📎 |
postcode | string | Billing postal code | 📎 |
country | string | Billing country | 📎 |
Store a credit card
API Request
POST /api/v3/creditcard HTTP/1.1
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
Content-Type: application/json
{
"customer_id": 475,
"number": "4111 1111 1111 1111",
"expdate_year": "2015",
"expdate_month": "11",
"cvv": 123,
"name": "Keith Palmer",
"address": "72 E Blue Grass Road",
"city": "Willington",
"state": "CT",
"postcode": "06279",
"country": "United States"
}
Querying for credit cards
Available query parameter values for filtering:
- creditcard_id
- customer_id
- external_key
- token
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | The customer id # | 📎 |
creditcard_id | integer | The credit card ID # | 📎 |
external_key | string | Unique external key value | 📎 |
type | string | Credit card type | 📎 |
type_name | string | Credit card type user-friendly name | 📎 |
token | string | Credit card token | 📎 |
name | string | Name on credit card | 📎 |
mask_number | string | Last 4 digits of the credit card | 📎 |
mask_and_bin_number | string | First 6 digits and last 4 digits of the credit card | 📎 |
expdate | string | Expiration date (in YYYY-MM-DD format) | 📎 |
expdate_year | string | Expiration year (4-digits, YYYY) (only required if you do not provide expdate) | 📎 |
expdate_month | string | Expiration month (2-digits, MM) (only required if you do not provide expdate) | 📎 |
expdate_formatted | string | Expiration date (formatted) | 📎 |
address | string | Billing street address | 📎 |
city | string | Billing city | 📎 |
state | string | Billing state | 📎 |
postcode | string | Billing postal code | 📎 |
country | string | Billing country | 📎 |
url_updatelink | string | 📎 | |
write_datetime | datetime | Date/time the credit card was stored | 📎 |
write_ipaddr | datetime | IP address that created the card | 📎 |
mod_datetime | datetime | Date/time the credit card was modified | 📎 |
Querying for credit cards
API Request
GET /api/v3/creditcard?limit=10&where=customer_id:EQUALS:3
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"creditcard_id": 1,
"external_key": null,
"type": "visa",
"token": "ly1j7wmginqp",
"expdate": "2023-05-01",
"write_datetime": "2019-07-25 10:24:52",
"write_ipaddr": "10.80.1.1",
"mask_number": "x1111",
"mask_and_bin_number": "411111xxx1111",
"name": "John LLC",
"expdate_month": "5",
"expdate_year": "2023",
"expdate_formatted": "May 2023",
"type_name": "Visa",
"url_updatelink": "https:\/\/example.chargeover.com\/r\/paymethod\/i\/ru0895x81ht1",
"address": null,
"city": null,
"postcode": null,
"country": "United States",
"customer_id": 2
},
{
"creditcard_id": 2,
"external_key": null,
"type": "mast",
"token": "4ei8py0h1x06",
"expdate": "2022-05-01",
"write_datetime": "2019-07-25 10:25:37",
"write_ipaddr": "10.80.1.1",
"mask_number": "x4444",
"mask_and_bin_number": "555555xxx4444",
"name": "John LLC",
"expdate_month": "5",
"expdate_year": "2022",
"expdate_formatted": "May 2022",
"type_name": "MasterCard",
"url_updatelink": "https:\/\/example.chargeover.com\/r\/paymethod\/i\/ru0895x81ht1",
"address": null,
"city": null,
"postcode": null,
"country": "United States",
"customer_id": 2
}
]
}
ACH/eCheck Accounts
Store an ACH account
This method can be used to store a new ACH or update an existing ACH.
To update an existing card: Send a new POST request using existing routing
and number
fields with its updated values. The stored ACH will then be updated.
- The type field must be one of:
chec
(personal checking account),busi
(business checking account), orsavi
(savings account) - The number field should be a valid bank account number
0(3-digit institution code)(5 digit transit number)
Example: 032012345
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
external_key | string | Unique external key value | 📎 |
type | string | Bank account type (one of: chec, busi, savi) | 📎 |
number | string | Bank account number | 📎 |
routing | string | Bank account routing number | 📎 |
name | string | Name on bank account | 📎 |
bank | string | Bank name | 📎 |
Store an ACH account
Querying for ACH accounts
Available query parameter values for filtering:
- ach_id
- customer_id
- external_key
- token
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
ach_id | integer | ACH ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
external_key | string | Unique external key value | 📎 |
type | string | Bank account type (one of: chec, busi, savi) | 📎 |
type_name | string | Bank account type (pretty name) | 📎 |
token | string | ACH account token | 📎 |
mask_number | string | Last 4 digits of the bank account number | 📎 |
mask_routing | string | Bank account routing number | 📎 |
name | string | Name on bank account | 📎 |
mask_bank | string | Bank name | 📎 |
url_verifylink | string | ACH verification link | 📎 |
write_datetime | datetime | Date/time the bank account was stored | 📎 |
mod_datetime | datetime | Date/time the bank account was modified | 📎 |
Querying for ACH accounts
API Request
GET /api/v3/ach?limit=10&where=customer_id:EQUALS:36
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"ach_id": 6,
"external_key": null,
"type": "chec",
"token": "zm960n26k14h",
"type_name": "Checking",
"customer_id": 36,
"name": "Camille Bettencourt",
"mask_bank": "Isabella Bank",
"mask_number": "x6667",
"mask_routing": "x3004"
},
{
"ach_id": 7,
"external_key": null,
"type": "chec",
"token": "31q03f11yw98",
"type_name": "Checking",
"customer_id": 36,
"name": "Camille Bettencourt",
"mask_bank": "Td Bank, Na",
"mask_number": "x6670",
"mask_routing": "x3093"
}
]
}
Tokenized Pay Methods
The tokenized card APIs are used for storing/retrieving credit cards that have already been tokenized by another service (e.g. customer or card tokens from other payment gateways such as Stripe or Braintree).
This is useful if you're migrating from Stripe or Braintree but want to still be able to use the credit cards you have stored there during migration.
Store a pay method token
Store an already tokenized credit card in ChargeOver.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customer_id | integer | Customer ID # | 📎 |
name | string | Descriptive name for token (e.g. "Visa x4111") | 📎 |
type | string | Type of token (usually "customer") | 📎 |
paymethod_hint | string | (Optional) Either "crd" (credit card) or "ach" (ACH/bank accounts) | 📎 |
expdate | date | (Optional; only required for First Data/Payeezy) Expiration date (YYYY-MM-DD) of the tokenized credit card | 📎 |
type_hint | string | (Optional; only required for First Data/Payeezy) A credit card type (one of "visa", "mast", "disc", or "amex") | 📎 |
token | string | The token value | 📎 |
gateway | string | (Optional; only required if providing tokens for multiple gateways) A hint for which gateway this is a token for | 📎 |
Querying for pay method tokens
Available query parameter values for filtering:
- customer_id
- customer_external_key
- customer_token
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
tokenized_id | integer | Tokenized ID # | 📎 |
customer_id | integer | Customer ID # | 📎 |
name | string | Descriptive name for token (e.g. "Visa x4111") | 📎 |
type | string | Type of token (usually "customer") | 📎 |
paymethod_hint | string | (Optional) Either "crd" (credit card) or "ach" (ACH/bank accounts) | 📎 |
expdate | date | (Optional; only required for First Data/Payeezy) Expiration date (YYYY-MM-DD) of the tokenized credit card | 📎 |
type_hint | string | (Optional; only required for First Data/Payeezy) A credit card type (one of "visa", "mast", "disc", or "amex") | 📎 |
token | string | The token value | 📎 |
gateway | string | (Optional; only required if providing tokens for multiple gateways) A hint for which gateway this is a token for | 📎 |
write_datetime | datetime | Date/time the tokenized payment method was stored | 📎 |
mod_datetime | datetime | Date/time the tokenized payment method was edited | 📎 |
Querying for pay method tokens
API Request
GET /api/v3/tokenized?limit=10&where=customer_id:EQUALS:2
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"tokenized_id": 1,
"type": "customer",
"name": null,
"token": "cus_5tSkoQ6mDrXOMQ",
"expdate": null,
"type_hint": null,
"paymethod_hint": null,
"customer_id": 2
}
]
}
Brands
Retrieve brand list
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
brand_id | integer | Brand ID # | 📎 |
brand | string | Deprecated (use "name" instead) | 📎 |
name | string | Brand name | 📎 |
brand_addr1 | string | Street address 1 | 📎 |
brand_addr2 | string | Street address 1 | 📎 |
brand_city | string | City | 📎 |
brand_state | string | State/province | 📎 |
brand_postcode | string | Postal code | 📎 |
brand_country | string | Country | 📎 |
brand_block | string | Printable brand address | 📎 |
brand_phone | string | Brand phone number | 📎 |
brand_email | string | Brand email address | 📎 |
brand_linkedin | string | Brand linkedin | 📎 |
brand_twitter | string | Brand twitter | 📎 |
brand_facebook | string | Brand facebook | 📎 |
brand_yelp | string | Brand yelp | 📎 |
brand_youtube | string | Brand youtube | 📎 |
brand_instagram | string | Brand instagram | 📎 |
brand_pinterest | string | Brand pinterest | 📎 |
brand_tiktok | string | Brand tiktok | 📎 |
custom_1 | string | Custom field 1 | 📎 |
custom_2 | string | Custom field 2 | 📎 |
custom_3 | string | Custom field 3 | 📎 |
custom_4 | string | Custom field 4 | 📎 |
custom_5 | string | Custom field 5 | 📎 |
url_logosmall | string | URL to a small version of the brand logo | 📎 |
url_logomedium | string | URL to a medium version of the brand logo | 📎 |
url_logolarge | string | URL to a large version of the brand logo | 📎 |
url_logohuge | string | URL to a huge version of the brand logo | 📎 |
url_logooriginal | string | URL to the originally uploaded brand logo | 📎 |
Usage / Metered
Storing usage/metered data
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
line_item_id | string | Line Item ID that the usage is for | 📎 |
usage_value | string | Usage value | 📎 |
type | string | Usage type (default "add", other options are "add", "max", "lat", "pia", "pas", "dlt") | 📎 |
options | array | An array of usage options | 📎 |
from | datetime | Starting date/time for the usage period | 📎 |
to | datetime | Ending date/time for the usage period | 📎 |
external_key | string | External key value | 📎 |
custom_1 | string | Custom field 1 | 📎 |
custom_2 | string | Custom field 2 | 📎 |
custom_3 | string | Custom field 3 | 📎 |
custom_4 | string | Custom field 4 | 📎 |
custom_5 | string | Custom field 5 | 📎 |
custom_6 | string | Custom field 6 | 📎 |
custom_7 | string | Custom field 7 | 📎 |
custom_8 | string | Custom field 8 | 📎 |
custom_9 | string | Custom field 9 | 📎 |
custom_10 | string | Custom field 10 | 📎 |
custom_11 | string | Custom field 11 | 📎 |
custom_12 | string | Custom field 12 | 📎 |
custom_13 | string | Custom field 13 | 📎 |
custom_14 | string | Custom field 14 | 📎 |
custom_15 | string | Custom field 15 | 📎 |
custom_16 | string | Custom field 16 | 📎 |
custom_17 | string | Custom field 17 | 📎 |
custom_18 | string | Custom field 18 | 📎 |
custom_19 | string | Custom field 19 | 📎 |
custom_20 | string | Custom field 20 | 📎 |
Bulk usage/metered data upload
ChargeOver also has a dedicated bulk endpoint to push usage to. You can upload a maximum number of 1000 usage records per REST API call.
In addition to line_item_id
, ChargeOver also supports sending usage data using the customer.external_key
and line_item.item_external_key
fields.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
line_item_id | string | Line Item ID that the usage is for | 📎 |
usage_value | string | Usage value | 📎 |
type | string | Usage type (default "add", other options are "add", "max", "lat", "pia", "pas", "dlt") | 📎 |
options | array | An array of usage options | 📎 |
from | datetime | Starting date/time for the usage period | 📎 |
to | datetime | Ending date/time for the usage period | 📎 |
external_key | string | External key value | 📎 |
custom_1 | string | Custom field 1 | 📎 |
custom_2 | string | Custom field 2 | 📎 |
custom_3 | string | Custom field 3 | 📎 |
custom_4 | string | Custom field 4 | 📎 |
custom_5 | string | Custom field 5 | 📎 |
custom_6 | string | Custom field 6 | 📎 |
custom_7 | string | Custom field 7 | 📎 |
custom_8 | string | Custom field 8 | 📎 |
custom_9 | string | Custom field 9 | 📎 |
custom_10 | string | Custom field 10 | 📎 |
custom_11 | string | Custom field 11 | 📎 |
custom_12 | string | Custom field 12 | 📎 |
custom_13 | string | Custom field 13 | 📎 |
custom_14 | string | Custom field 14 | 📎 |
custom_15 | string | Custom field 15 | 📎 |
custom_16 | string | Custom field 16 | 📎 |
custom_17 | string | Custom field 17 | 📎 |
custom_18 | string | Custom field 18 | 📎 |
custom_19 | string | Custom field 19 | 📎 |
custom_20 | string | Custom field 20 | 📎 |
Bulk usage/metered data upload
API Request
POST /api/v3/usage?action=bulk
Content-Type: application/json
[
{
"customer.external_key": "77889",
"line_item.item_external_key": "item_key",
"usage_value": 100
},
{
"line_item_id": 720,
"usage_value": 101
},
{
"line_item_id": 722,
"usage_value": 300
},
{
"line_item_id": 723,
"usage_value": 150
}
]
Query for usage/metered data
Available query parameter values for filtering:
line_item_id
- associated subscription lineexternal_key
- external key for usage/metered data pointfrom
- from dateto
- to date
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
usage_history_id | integer | Usage History ID # | 📎 |
line_item_id | string | Line Item ID that the usage is for | 📎 |
usage_value | string | Usage value | 📎 |
type | string | Usage type (default "add", other options are "add", "max", "lat", "pia", "pas", "dlt") | 📎 |
from | datetime | Starting date/time for the usage period | 📎 |
to | datetime | Ending date/time for the usage period | 📎 |
external_key | string | External key value | 📎 |
custom_1 | string | Custom field 1 | 📎 |
custom_2 | string | Custom field 2 | 📎 |
custom_3 | string | Custom field 3 | 📎 |
custom_4 | string | Custom field 4 | 📎 |
custom_5 | string | Custom field 5 | 📎 |
custom_6 | string | Custom field 6 | 📎 |
custom_7 | string | Custom field 7 | 📎 |
custom_8 | string | Custom field 8 | 📎 |
custom_9 | string | Custom field 9 | 📎 |
custom_10 | string | Custom field 10 | 📎 |
custom_11 | string | Custom field 11 | 📎 |
custom_12 | string | Custom field 12 | 📎 |
custom_13 | string | Custom field 13 | 📎 |
custom_14 | string | Custom field 14 | 📎 |
custom_15 | string | Custom field 15 | 📎 |
custom_16 | string | Custom field 16 | 📎 |
custom_17 | string | Custom field 17 | 📎 |
custom_18 | string | Custom field 18 | 📎 |
custom_19 | string | Custom field 19 | 📎 |
custom_20 | string | Custom field 20 | 📎 |
Query for usage/metered data
API Request
GET /api/v3/usage?where=line_item_id:EQUALS:581
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNSjNOaWo1aGZMeERSYjg6OXZDSmJtZFpLU2llVmNoeXJSSXRGUXc4TUJONGxPSDM=
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"usage_history_id": 14,
"external_key": null,
"usage_value": 1,
"custom_1": "test",
"custom_2": "test2",
"custom_3": null,
"custom_4": null,
"custom_5": null,
"custom_6": null,
"custom_7": null,
"custom_8": null,
"custom_9": null,
"custom_10": null,
"custom_11": null,
"custom_12": null,
"custom_13": null,
"custom_14": null,
"custom_15": null,
"custom_16": null,
"custom_17": null,
"custom_18": null,
"custom_19": null,
"custom_20": null,
"line_item_id": 581,
"from": "2024-05-04 00:00:00",
"to": "2024-05-04 00:00:00"
},
{
"usage_history_id": 15,
"external_key": null,
"usage_value": 3,
"custom_1": "test",
"custom_2": "test2",
"custom_3": null,
"custom_4": null,
"custom_5": null,
"custom_6": null,
"custom_7": null,
"custom_8": null,
"custom_9": null,
"custom_10": null,
"custom_11": null,
"custom_12": null,
"custom_13": null,
"custom_14": null,
"custom_15": null,
"custom_16": null,
"custom_17": null,
"custom_18": null,
"custom_19": null,
"custom_20": null,
"line_item_id": 629,
"from": "2024-05-05 00:00:00",
"to": "2024-05-05 00:00:00"
}
]
}
Delete usage/metered
Delete one usage entry.
Delete for a line item
Delete all usage entries attached to a particular line item.
Categories
Available query parameter values for filtering:
- item_category_id
- external_key
- name
- children_of_item_category_id (i.e. get the child categories of this category)
- parent_of_item_category_id (i.e. get the parent category of this category)
Query for categories
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
item_category_id | integer | Item category ID # | 📎 |
name | string | Category name | 📎 |
external_key | string | External key value | 📎 |
Query for categories
API Request
GET /api/v3/item_category?where=
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"item_category_id": 1,
"name": "Root",
"external_key": null
},
{
"item_category_id": 2,
"name": "Cars",
"external_key": ""
},
{
"item_category_id": 3,
"name": "Motorcycles",
"external_key": ""
},
{
"item_category_id": 4,
"name": "Trucks",
"external_key": ""
},
{
"item_category_id": 8,
"name": "SUVs",
"external_key": ""
},
{
"item_category_id": 7,
"name": "Sports Cars",
"external_key": ""
},
{
"item_category_id": 9,
"name": "Ducati",
"external_key": ""
},
{
"item_category_id": 10,
"name": "Kawasaki",
"external_key": ""
},
{
"item_category_id": 11,
"name": "Triumph",
"external_key": ""
}
]
}
Campaigns
Classes
Retrieve a list of classes
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
class_id | integer | Class ID # | 📎 |
name | string | Class name | 📎 |
accounting_sku | string | Accounting system SKU | 📎 |
Retrieve a list of classes
API Request
GET /api/v3/class
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"class_id": 4,
"name": "KMT-20",
"accounting_sku": "KMT-20"
},
{
"class_id": 8,
"name": "PREM-BRZ",
"accounting_sku": "PREM-03"
},
{
"class_id": 6,
"name": "PREM-GLD",
"accounting_sku": "PREM-01"
},
{
"class_id": 7,
"name": "PREM-SLVR",
"accounting_sku": "PREM-02"
},
{
"class_id": 9,
"name": "QT",
"accounting_sku": "QT-01"
},
{
"class_id": 3,
"name": "TBT-03",
"accounting_sku": "TBT-03"
},
{
"class_id": 5,
"name": "TBT-05",
"accounting_sku": "TBT-05"
},
{
"class_id": 1,
"name": "Test -UGG-01",
"accounting_sku": "UGG-01"
},
{
"class_id": 2,
"name": "VRG-02",
"accounting_sku": "VRG-02"
}
]
}
Countries
Retrieve country list
Retrieve country list
API Request
GET /api/v3/country
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"country_id": 16,
"name": "Australia",
"iso2": "AU",
"iso3": "AUS",
"cctld": ".au"
},
{
"country_id": 2,
"name": "Aland Islands",
"iso2": "AX",
"iso3": "ALA",
"cctld": ".ax"
},
{
"country_id": 42,
"name": "Canada",
"iso2": "CA",
"iso3": "CAN",
"cctld": ".ca"
},
{
"country_id": 243,
"name": "United States",
"iso2": "US",
"iso3": "USA",
"cctld": ".us"
}
]
}
Coupons
Retrieve a list of coupons
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
coupon_id | integer | The coupon ID # | 📎 |
code | string | Coupon code | 📎 |
descrip | string | Description | 📎 |
type | string | Coupon type | 📎 |
discount_item_id | integer | Item ID # or related discount (if applicable) | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
discount | array | Discount details | 📎 |
freetrial | array | Free trial details | 📎 |
write_datetime | datetime | Date/time the coupon was created | 📎 |
write_ipaddr | datetime | IP address that created the coupon | 📎 |
Retrieve a list of coupons
API Request
GET /api/v3/coupon HTTP/1.1
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"coupon_id": 1,
"code": "TEST",
"descrip": "t",
"type": "give-a-discount",
"enabled": true,
"write_datetime": "2021-05-25 08:23:05",
"write_ipaddr": "172.19.0.1",
"discount_item_id": 673
},
{
"coupon_id": 2,
"code": "Coupon 2",
"descrip": "test",
"type": "give-a-discount",
"enabled": true,
"write_datetime": "2022-02-15 13:47:43",
"write_ipaddr": "172.23.0.1",
"discount_item_id": 1153
},
{
"coupon_id": 3,
"code": "Coupon 3",
"descrip": "tset",
"type": "free-trial",
"enabled": true,
"write_datetime": "2022-02-15 13:47:55",
"write_ipaddr": "172.23.0.1",
"discount_item_id": null
}
]
}
Retrieve a specific coupon
Allows you to retrieve a specific coupon based on its coupon_id.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
coupon_id | integer | The coupon ID # | 📎 |
code | string | Coupon code | 📎 |
descrip | string | Description | 📎 |
type | string | Coupon type | 📎 |
discount_item_id | integer | Item ID # or related discount (if applicable) | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
discount | array | Discount details | 📎 |
freetrial | array | Free trial details | 📎 |
write_datetime | datetime | Date/time the coupon was created | 📎 |
write_ipaddr | datetime | IP address that created the coupon | 📎 |
Retrieve a specific coupon
API Request
GET /api/v3/coupon/1 HTTP/1.1
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"coupon_id": 1,
"code": "ABC123",
"descrip": "10% off your next purchase",
"type": "give-a-discount",
"enabled": true,
"write_datetime": "2021-05-25 08:23:05",
"write_ipaddr": "172.19.0.1",
"discount_item_id": 673
}
}
Currencies
List currencies
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
currency_id | integer | Currency ID # | 📎 |
currency | string | Deprecated | 📎 |
name | string | Currency name | 📎 |
iso4217 | string | ISO 4217 currency code | 📎 |
symbol | string | Currency symbol | 📎 |
rounding | integer | Number of decimal places to round currency fractions to | 📎 |
List currencies
API Request
GET /api/v3/currency
API Response
{
"code":200,
"status":"OK",
"message":"",
"response":[
{
"currency_id":1,
"currency":"United States dollar",
"iso4217":"USD",
"symbol":"$",
"rounding":"2"
},
{
"currency_id":2,
"currency":"Canadian dollar",
"iso4217":"CAD",
"symbol":"CAD$",
"rounding":"2"
},
{
"currency_id":3,
"currency":"Pound sterling",
"iso4217":"GBP",
"symbol":"\u00c2\u00a3",
"rounding":"2"
},
{
"currency_id":4,
"currency":"Euro",
"iso4217":"EUR",
"symbol":"\u00e2\u201a\u00ac",
"rounding":"2"
}
]
}
Set an exchange rate
By default, ChargeOver will automatically set the exchange rate between currencies for you each day.
You only need to manually set the exchange rate if you want to override the exchange rate that ChargeOver updates automatically every day.
Get an exchange rate
Allows you to see what the exchange rate is between two currencies in ChargeOver.
Languages
Terms
Sales terms specify the number of days an invoice is expected to be paid after the goods are dispatched or service is completed. e.g. NET 30, NET 60, etc.
Notes
Create a note
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
note | string | Note text | 📎 |
context_str | string | The type of object the note is attached to | 📎 |
context_id | string | The object ID # the note is attached to | 📎 |
Querying for notes
Available query parameter values for filtering:
- context_str (this should be one of: customer, billing_package, invoice, user, quote, item)
- context_id
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
note_id | integer | Note ID # | 📎 |
user_id | integer | User ID # | 📎 |
admin_id | integer | Admin ID # | 📎 |
note | string | Note text | 📎 |
note_is_pinned | boolean | Whether or not the note was pinned | 📎 |
context_str | string | The type of object the note is attached to | 📎 |
context_id | string | The object ID # the note is attached to | 📎 |
note_datetime | datetime | Date/time the note was created | 📎 |
Querying for notes
API Request
GET /api/v3/note?where=context_str:EQUALS:customer,context_id:EQUALS:265
API Response
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"note_id": 3,
"user_id": null,
"admin_id": 1,
"note_is_pinned": false,
"note_datetime": "2024-02-16 07:46:58",
"note": "Customer agreed to upgrade to PRO plan.",
"context_str": "customer",
"context_id": 265
},
{
"note_id": 4,
"user_id": null,
"admin_id": 1,
"note_is_pinned": false,
"note_datetime": "2024-02-16 07:47:14",
"note": "Customer requested billing date be changed from 14th of the month to 12th of the month; credit issues.",
"context_str": "customer",
"context_id": 265
}
]
}
Admin Workers
Admin workers are administrative users of the ChargeOver backend (e.g. your employees or workers).
The primary key field for admins is admin_id
.
Get a list of admin workers
Notes:
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
admin_id | integer | Admin ID # | 📎 |
username | string | Username | 📎 |
external_key | string | External key value | 📎 |
timezone | string | Timezone | 📎 |
name | string | Full name | 📎 |
first_name | string | First Name | 📎 |
last_name | string | Last Name | 📎 |
initials | string | Initials | 📎 |
nickname | string | Nickname | 📎 |
string | Email address | 📎 | |
string | Twitter URL | 📎 | |
string | Facebook URL | 📎 | |
string | LinkedIn URL | 📎 | |
login_count | string | The # of times the worker has logged in | 📎 |
login_datetime | string | Last logged in | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
custom_4 | mixed | Custom field value #4 | 📎 |
custom_5 | mixed | Custom field value #5 | 📎 |
write_datetime | date | Date/time the admin was created | 📎 |
mod_datetime | date | Date/time the admin was modified | 📎 |
Get a list of admin workers
API Request
GET /api/v3/admin
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"admin_id": 10,
"external_key": null,
"timezone": "America\/Detroit",
"first_name": "Keith",
"last_name": "Palmer",
"initials": null,
"email": "noreply@chargeover.com",
"login_datetime": "2015-03-03 22:04:38",
"write_datetime": "2015-03-03 22:02:37",
"mod_datetime": "2015-03-03 22:04:36",
"name": "Keith Palmer",
"username": "noreply@chargeover.com"
},
...
]
}
Query for admin workers
Valid query parameters:
- admin_id
- external_key
- first_name
- last_name
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
admin_id | integer | Admin ID # | 📎 |
username | string | Username | 📎 |
external_key | string | External key value | 📎 |
timezone | string | Timezone | 📎 |
name | string | Full name | 📎 |
first_name | string | First Name | 📎 |
last_name | string | Last Name | 📎 |
initials | string | Initials | 📎 |
nickname | string | Nickname | 📎 |
string | Email address | 📎 | |
string | Twitter URL | 📎 | |
string | Facebook URL | 📎 | |
string | LinkedIn URL | 📎 | |
login_count | string | The # of times the worker has logged in | 📎 |
login_datetime | string | Last logged in | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
custom_4 | mixed | Custom field value #4 | 📎 |
custom_5 | mixed | Custom field value #5 | 📎 |
write_datetime | date | Date/time the admin was created | 📎 |
mod_datetime | date | Date/time the admin was modified | 📎 |
Query for admin workers
API Request
GET /api/v3/admin/?where=first_name:EQUALS:keith
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"admin_id": 10,
"external_key": null,
"timezone": "America\/Detroit",
"first_name": "Keith",
"last_name": "Palmer",
"initials": null,
"email": "noreply@chargeover.com",
"login_datetime": "2015-03-03 22:04:38",
"write_datetime": "2015-03-03 22:02:37",
"mod_datetime": "2015-03-03 22:04:36",
"name": "Keith Palmer",
"username": "noreply@chargeover.com"
}
]
}
Get a specific admin worker
Get an admin by admin_id.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
admin_id | integer | Admin ID # | 📎 |
username | string | Username | 📎 |
external_key | string | External key value | 📎 |
timezone | string | Timezone | 📎 |
name | string | Full name | 📎 |
first_name | string | First Name | 📎 |
last_name | string | Last Name | 📎 |
initials | string | Initials | 📎 |
nickname | string | Nickname | 📎 |
string | Email address | 📎 | |
string | Twitter URL | 📎 | |
string | Facebook URL | 📎 | |
string | LinkedIn URL | 📎 | |
login_count | string | The # of times the worker has logged in | 📎 |
login_datetime | string | Last logged in | 📎 |
custom_1 | mixed | Custom field value #1 | 📎 |
custom_2 | mixed | Custom field value #2 | 📎 |
custom_3 | mixed | Custom field value #3 | 📎 |
custom_4 | mixed | Custom field value #4 | 📎 |
custom_5 | mixed | Custom field value #5 | 📎 |
write_datetime | date | Date/time the admin was created | 📎 |
mod_datetime | date | Date/time the admin was modified | 📎 |
Get a specific admin worker
API Request
GET /api/v3/admin/10
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"admin_id": 10,
"external_key": null,
"timezone": "America\/Detroit",
"first_name": "Keith",
"last_name": "Palmer",
"initials": null,
"email": "noreply@chargeover.com",
"login_datetime": "2015-03-03 22:04:38",
"write_datetime": "2015-03-03 22:02:37",
"mod_datetime": "2015-03-03 22:04:36",
"name": "Keith Palmer",
"username": "noreply@chargeover.com"
}
}
ChargeOver.js
The ChargeOver.js REST API components allow you to take advantage of the store/review/commit mode that ChargeOver.js offers.
This provides the ability to hold ChargeOver.js requests in a "pending" state until reviewed further.
Incoming ChargeOver.js requests can be reviewed, and then either committed (saved to the database) or rejected (discarded).
Get a list of pending requests
Get a list of pending ChargeOver.js requests.
Each object will contain a JSON-encoded payload of data submitted via ChargeOver.js.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
chargeoverjs_id | integer | Store ID # | 📎 |
token | string | ChargeOver.js token | 📎 |
action | string | ChargeOver.js action | 📎 |
payload | string | ChargeOver.js payload | 📎 |
Get a list of pending requests
API Request
GET /api/v3/_chargeoverjs
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"action": "customer.create",
"payload": "{\"customer\":{\"company\":\"Test Company, LLC\",\"bill_addr1\":\"56 Cowles Road\",\"bill_addr2\":\"\",\"bill_addr3\":\"\",\"bill_city\":\"Mt Pleasant\",\"bill_state\":\"MI\",\"bill_postcode\":\"48858\",\"bill_country\":\"United States\",\"custom_1\":\"\",\"custom_2\":\"\",\"custom_3\":\"\"},\"user\":{\"name\":\"John Doe\",\"phone\":\"888-924-2347\",\"email\":\"test@ChargeOver.com\"}}",
"token": "9w5jdiqz1pf7h8ga",
"chargeoverjs_id": 1
},
...
]
}
Commit a ChargeOver.js request
Commit a pending ChargeOver.js request (i.e. actually accept and write the data to ChargeOver).
Commit a ChargeOver.js request
API Request
POST /api/v3/_chargeoverjs HTTP/1.1
Authorization: Basic VjF0dWZnOXZrbFV5d0gwRHFyRnMyNmJqQ1RtN0E4S0U6UEJSSWg4bXF6RXJUMmlrcHVkM1Z0THdYNlcxS283Sk4=
Content-Type: application/json
{
"commit": "9w5jdiqz1pf7h8ga"
}
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"response": {
"code": 200,
"errmsgs": [],
"errfields": [],
"response": {
"customer": {
"superuser_id": 0,
"external_key": null,
"token": "kpumnq0w7ec8",
"company": "Test Company, LLC",
"bill_addr1": "56 Cowles Road",
"bill_addr2": null,
"bill_addr3": null,
"bill_city": "Mt Pleasant",
"bill_state": "MI",
"bill_postcode": "48858",
"bill_country": "United States",
"bill_notes": null,
"ship_addr1": null,
"ship_addr2": null,
"ship_addr3": null,
"ship_city": null,
"ship_state": null,
"ship_postcode": null,
"ship_country": null,
"ship_notes": null,
"terms_id": 2,
"class_id": null,
"custom_1": null,
"custom_2": null,
"custom_3": null,
"admin_id": null,
"campaign_id": null,
"currency_id": 1,
"no_taxes": false,
"no_dunning": false,
"write_datetime": "2015-06-08 11:18:23",
"write_ipaddr": "172.16.16.11",
"mod_datetime": "2015-06-08 11:18:23",
"mod_ipaddr": "172.16.16.11",
"terms_name": "Net 30",
"terms_days": 30,
"paid": 0,
"total": 0,
"balance": 0,
"url_paymethodlink": "http:\/\/haproxy-dev.chargeover.com\/signup\/r\/paymethod\/i\/kpumnq0w7ec8",
"currency_symbol": "$",
"currency_iso4217": "USD",
"display_as": "Test Company, LLC",
"ship_block": "",
"bill_block": "56 Cowles Road\nMt Pleasant MI 48858\nUnited States",
"superuser_name": "",
"superuser_first_name": "",
"superuser_last_name": "",
"superuser_phone": "",
"superuser_email": "",
"customer_id": 13
},
"user": {
"user_id": 361,
"external_key": null,
"first_name": "John",
"middle_name_glob": null,
"last_name": "Doe",
"name_suffix": null,
"title": "",
"email": "test@ChargeOver.com",
"token": "o4jcubrmy1g2",
"phone": "888-924-2347",
"user_type_id": 1,
"write_datetime": "2015-06-08 11:18:23",
"mod_datetime": "2015-06-08 11:18:23",
"name": "John Doe",
"display_as": "John Doe",
"user_type_name": "Billing",
"username": "eb1auzqo0fjm"
}
}
}
}
Reject a ChargeOver.js request
Reject a pending ChargeOver.js request (i.e. discard/do not process the ChargeOver.js request).
Custom Fields
Use these endpoints to get information about custom fields that are defined within ChargeOver.
List custom fields
Possible values for type
:
string
- a single-line free-form text fieldselect
- a dropdown/select box offering a specific set of choicesdate
- a datenumber
- a number
If the type is select
, available choices will be returned in type_opts
.
The field
attribute is the API field name you can use to populate custom field data onto an object.
For example, if context_str=customer
and field=custom_2
then when you create a customer via the REST
API, you would send:
POST /api/v3/customer
{
"company": "Sombra Corporation",
"custom_2": "The Dark Tower"
}
Custom fields are not required, so can be left out of API requests if you do not wish to provide a value.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
customfield_id | integer | Custom field ID # | 📎 |
name | string | Name | 📎 |
type | string | Type | 📎 |
type_opts | array | Type options (e.g. allowable dropdown values) | 📎 |
enabled | boolean | Enabled/disabled | 📎 |
context_str | string | Context | 📎 |
field | string | API field name | 📎 |
List custom fields
API Request
GET /api/v3/_customfield
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"context_str": "customer",
"field": "custom_2",
"customfield_id": 417,
"name": "Favorite Book",
"enabled": true,
"type": "select",
"type_opts": [
"Snow Crash",
"Perdido Street Station",
"The Dark Tower",
"Other"
]
},
{
"context_str": "quote",
"field": "custom_1",
"customfield_id": 418,
"name": "Favorite Color",
"enabled": true,
"type": "string",
"type_opts": null
}
]
}
REST Hooks
REST Hooks <RESTHooks.org> is a collection of patterns that treat webhooks like subscriptions.
Your app can subscribe to an event (example: "A customer is created") via the ChargeOver REST API, and instantaneously receive notifications (JSON payloads) via HTTP POST requests whenever that event occurs within ChargeOver.
Viewing your rest hooks
Returns a list of all your subscribed REST Hooks
Viewing your rest hooks
API Request
GET /api/v3/_resthook
Authorization: Basic N3N1dFdGRU8yektWWUlHbVpNS...
Content-Type: application/json
Subscribing
Subscribing is the process of telling ChargeOver to send webhooks to you whenever a specific event occurs (example: "Send http://example.org/my_webhook_url data whenever a customer is created.").
Once you've subscribed, each time the event occurs within ChargeOver, ChargeOver will send an HTTP POST request to your URL with a JSON payload of the event data.
Please refer to our webhooks documentation to see the JSON payloads your webhook URL will receive.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
target_url | string | The subscription URL | 📎 |
event | string | The event | 📎 |
Integrations
Use these endpoints to push and pull data relating ChargeOver records to integrated application records.
Query for map values
Query for a list of mapped values (e.g. which Salesforce record corresponds to this ChargeOver record?)
Query for map values
API Request
GET http://dev1.chargeover.com/api/v3/_integration_map?where=integration:EQUALS:qbonline HTTP/1.1
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"integration": "qbonline",
"context_str": "customer",
"context_id": 3759,
"integration_guid": "{-1234}"
},
{
"integration": "qbonline",
"context_str": "invoice",
"context_id": 3,
"integration_guid": "{-2345}"
},
{
"integration": "qbonline",
"context_str": "customer",
"context_id": 3760,
"integration_guid": "{-123x}"
}
]
}
Add a map record
Add a map record (e.g. map a specific Salesforce record to a specific ChargeOver record)
Add a map record
API Request
POST http://dev1.chargeover.com/api/v3/_integration_map?action=addMap HTTP/1.1
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
{
"integration": "salesforce",
"context_str": "customer",
"context_id": 3760,
"integration_guid": "5003000000D8cuI"
}
System Log
The ChargeOver system log contains warnings and other notifications about notable events happening within ChargeOver. This may include notifictaions about webhook URLs failing, usage URLs failing, etc.
Retrieve the system log
Retrieve a list of log entries.
Object Attributes
Attribute | Type | Description | |
---|---|---|---|
log_id | integer | Log ID # | 📎 |
msg | string | Log Message | 📎 |
log_datetime | datetime | Date/time the log entry was recorded | 📎 |
Retrieve the system log
API Request
GET /api/v3/_log_system
API Response
{
"code": 200,
"status": "OK",
"message": "",
"response": [
{
"log_id": 1,
"msg": "Webhook 2: http:\/\/www.example.com\/tasdgadg.php returned a non-200 OK response: 301",
"log_datetime": "2015-10-31 15:02:47"
},
{
"log_id": 2,
"msg": "Webhook 2: http:\/\/www.example.com\/tasdgadg.php returned a non-200 OK response: 301",
"log_datetime": "2015-10-31 15:02:48"
}
]
}
Reports
Reporting
It is possible to pull reporting and aggregation data via the ChargeOver REST API.
Get a List of Reports
Allows you to get a list of all reports with each report's name
and report_id
number.
Get a List of Reports
API Request
GET /api/v3/_report
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": [
{
"name": "Open Customer Balances",
"report_id": 3
},
{
"name": "All Customer Balances",
"report_id": 4
},
{
"name": "Credits",
"report_id": 6
},
{
"name": "Failed Payments",
"report_id": 7
}
}
Get a Specific Report
Get a specific report for more details on the available filters and columns in the report.
Get a Specific Report
API Request
GET /api/v3/_report/141
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
API Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"name": "Example Report Name",
"report_id": 141,
"available_filters": {
"invoice_invoice_date": {
"ops": [
"GTE",
"LTE"
]
},
"customer_customer_id": {
"ops": [
"EQUALS"
]
}
}
}
}
Run a report / report data
You can also get the data from a specific report via the API by using the report's report_id
.
Ordering and limiting report data:
It is possible to order or to limit the results you get back from the report if desired. For example, if you wanted to view the "All Customers" report with the list of customers in ascending order based off of customer_id, you could use:
/api/v3/_report/37?action=reportData&order=customer_customer_id:ASC
There are two parameters used for limiting the data that is returned: offset
and limit
.
offset
determines how far into the report the data is returned from. For example, if you are calling for the "All Customers" report and have ten customers ranging from customer_id=1 and customer_id=10 and offset=0
then the returned report will start with the customer whose customer_id = 1. However, if the offset=3
then the report data that is returned will start with the customer who has a customer_id = 4.
Note: If you request an offset
you MUST also specify an order
with ASC
for ascending or DESC
for descending.
limit
determines the number of objects returned from the report. For example if limit=5
for the "All Customers" report, you would get back the data for no more than five customers in the report. The maximum page size for report data is 1000.
One last example:
/api/v3/_report/37?action=reportData&offset=10&limit=50&order=customer_customer_id:ASC
If you used the above API call you would get back no more than 50 objects from the report, starting with the 10th object in the report.
Run a report / report data
API Request
POST /api/v3/_report/58?action=reportData
Authorization: Basic czI3bEhUNGh4UTNuUkNhRUJQMGR6S2V0anVpTmZMbXk6UnF6M0xEWTZjaXBLYkZPVHdCRTlOb1ZKblM1c1FVcmw=
Content-Type: application/json
[
"transaction_transaction_date:GTE:2017-09-11",
"transaction_transaction_date:LTE:2017-10-11"
]
API Response
HTTP/1.0 200 OK
Content-Type: application/json
{
"code": 200,
"status": "OK",
"message": "",
"details": {},
"response": {
"_report": [
{
"transaction_transaction_date": "Sep 14, 2017",
"transaction_transaction_method": "ACH\/eCheck",
"transaction_transaction_detail": "x6667",
"transaction_amount": "$ 50.00",
"transaction_gateway_transid": "*DEBIT: Test ACH\/eCheck* [1505398606]",
"transaction_transaction_type": "Payment",
"transaction_transaction_date_unformatted": "2017-09-14",
"transaction_amount_unformatted": 50
},
{
"transaction_transaction_date": "Sep 28, 2017",
"transaction_transaction_method": "Visa",
"transaction_transaction_detail": "x4444",
"transaction_amount": "$ 100.00",
"transaction_gateway_transid": "*CHARGE: Test Credit Card* [1506605204]",
"transaction_transaction_type": "Payment",
"transaction_transaction_date_unformatted": "2017-09-28",
"transaction_amount_unformatted": 100
},
{
"transaction_transaction_date": "Sep 28, 2017",
"transaction_transaction_method": "Paid by Check",
"transaction_transaction_detail": 56,
"transaction_amount": "$ 550.00",
"transaction_gateway_transid": 56,
"transaction_transaction_type": "Payment",
"transaction_transaction_date_unformatted": "2017-09-28",
"transaction_amount_unformatted": 550
},
{
"transaction_transaction_date": "Oct 11, 2017",
"transaction_transaction_method": "Visa",
"transaction_transaction_detail": "x1111",
"transaction_amount": "$ 100.00",
"transaction_gateway_transid": "*CHARGE: Test Credit Card* [1507740165]",
"transaction_transaction_type": "Payment",
"transaction_transaction_date_unformatted": "2017-10-11",
"transaction_amount_unformatted": 100
}
],
"_count": 4
}
}