Skip to main content
Vindicia Knowledge Center

Accounts

Accounts

The Account represents a merchant’s customer. Subscriptions and Transactions must belong to an Account - as such, Accounts will be required in CashBox for billing.

An Account can have any number of children accounts; and may have up to one parent account.

  • cURL
  • Java
 
 

 


Supported Operations

 

GET | list (all; filtered), fetch (individual Account), fetch_credit (individual Account)

POST| create (individual Account), update (individual Account), credit_grant (individual Account)

Note: HTTP request examples in this reference use the Production path. For the ProdTest environment, substitute prodtest.vindicia in place of vindicia; for the Staging, use staging.vindicia
  • cURL
  • Java
 

 


The Account object

The Account object represents your customer. As such it can contain as much or as little information as you collect about the customers (people or organizations) to which you offer billing and subscriptions. An Account owns the “on file” payment methods to be used by it in billing. An Account can have any number of children accounts; and may have up to one parent account.

Attributes

Name Type Description
object string Value is “Account”
id string A merchant-specified unique identifier. If not specified, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. Assigned by CashBox.
created datetime The date/time the Account was created.
parent Account The parent (Account) of this Account.
default_currency string The currency used on subscriptions and transactions belonging to this Account when not explicitly specified. An ISO 4217 Currency Code.
email string The email address associated with this Account.
email_type enum The email format type preferred by this customer. Values can be html,multipart,plaintext
language string The language (code) preferred for communications.
notify_before_billing boolean Whether or not to send this customer pre-billing notification (emails).
company string The company name of the customer if a business Account.
name string The name of the person primarily associated with this Account.
shipping_address Address The primary physical address associated with this Account.
payment_methods PaymentMethod[] The payment methods on file for this Account.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
tax_exemptions TaxExemption[] Tax Exemptions registered for this Account.
tokens TokenAmount[] The token balances for this Account.
credit Credit The account-level credit balances for this Account.
entitlements Entitlement[] The account-level entitlements for this Account.
tax_use_code string Special Tax Handling ruleas defined with merchant’s tax service.
  • cURL
  • Java
Example Object
{
    "object": "Account",
    "id": "cust_1234",
    "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
    "created": "2016-05-18T13:39:03-07:00",
    "default_currency": "USD",
    "email": "cbrown@example.com",
    "email_type": "html",
    "language": "EN-U",
    "notify_before_billing": true,
    "company": "Peanuts",
    "name": "Charlie Brown",
    "shipping_address": {
        "object": "Address",
        "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
        "name": "Charlie Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
    },
    "metadata": {
        "favorite dog": "Snoopy",
        "favorite activity": "flying kites"
    }
}
{
    "object": "Account",
    "id": "cust_1234",
    "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
    "created": "2016-05-18T13:39:03-07:00",
    "default_currency": "USD",
    "email": "cbrown@example.com",
    "email_type": "html",
    "language": "EN-U",
    "notify_before_billing": true,
    "company": "Peanuts",
    "name": "Charlie Brown",
    "shipping_address": {
        "object": "Address",
        "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
        "name": "Charlie Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
    },

    "metadata": {
        "favorite dog": "Snoopy",
        "favorite activity": "flying kites"
    }
}
          

Create an Account

 

Creates a new Account.

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON A full Account object.

Returns

JSON A full Account object.

  • cURL
  • Java
Example Request
curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
"id": "cust_2234",
"name": "Charlie Brown",
"company": "Peanuts",
"shipping_address": {
"object": "Address",
"name": "Charlie Brown",
"line1": "123 Main Street",
"city": "San Francisco",
"district": "CA",
"postal_code": "94105",
"country": "US",
"phone": "415-555-3212"
},
"email": "cbrown@example.com",
"email_type": "html",
"language" : "en-US",
"default_currency" : "USD",
"notify_before_billing" : true,
"metadata" : {
"favorite activity" : "flying kites",
"favorite dog" : "Snoopy"
}
}' "https://api.prodtest.vindicia.com/accounts"
The above command returns JSON structured like this:
{
    "object": "Account",
    "id": "cust_1234",
    "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
    "created": "2016-05-18T13:39:03-07:00",
    "default_currency": "USD",
    "email": "cbrown@example.com",
    "email_type": "html",
    "language": "EN-U",
    "notify_before_billing": true,
    "company": "Peanuts",
    "name": "Charlie Brown",
    "shipping_address": {
        "object": "Address",
        "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
        "name": "Charlie Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
    },
    "metadata": {
        "favorite dog": "Snoopy",
        "favorite activity": "flying kites"
    }
}

 


Fetch an Account

Retrieves a specific Account.

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON A full Account object.

  • cURL
  • Java
Example Request
curl -X GET 
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de
"https://api.prodtest.vindicia.com/accounts/cust_1234"
The above command returns JSON structured like this:
{
    "object": "Account",
    "id": "cust_1234",
    "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
    "created": "2016-05-18T13:39:03-07:00",
    "default_currency": "USD",
    "email": "cbrown@example.com",
    "email_type": "html",
    "language": "EN-U",
    "notify_before_billing": true,
    "company": "Peanuts",
    "name": "Charlie Brown",
    "shipping_address": {
        "object": "Address",
        "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
        "name": "Charlie Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
    },
    "metadata": {
        "favorite dog": "Snoopy",
        "favorite activity": "flying kites"
    }
}

 


 

Update an Account

 

Update a specific Account. Any parameters provided will be updated, leaving other parameters unchanged.

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve Yes

Query Parameters

None.

Accepts

JSON This request supports the same arguments as ‘create’ (a full Account object) excepting the behavior of the ids; providing an id or vid in the URL indicates to CashBox that this is an update, not a create – as such, id and vid cannot be updated.

Returns

JSON A full Account object representing the new version of the Account.

  • cURL
  • Java
Example Request
curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
"email": "charlie.brown@example.com"
}' "https://api.prodtest.vindicia.com/accounts/cust_1234"
The above command returns JSON structured like this:
{
  "object": "Account",
  "id": "cust_1234",
  "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
  "created": "2016-05-18T13:39:03-07:00",
  "default_currency": "USD",
  "email": "charlie.brown@example.com",
  "email_type": "html",
  "language": "EN-U",
  "notify_before_billing": true,
  "company": "Peanuts",
  "name": "Charlie Brown",
  "shipping_address": {
    "object": "Address",
    "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
    "name": "Charlie Brown",
    "line1": "123 Main Street",
    "city": "San Francisco",
    "district": "CA",
    "postal_code": "94105",
    "country": "US",
    "phone": "415-555-3212"
  },
  "metadata": {
  "favorite dog": "Snoopy",
  "favorite activity": "flying kites"
  }
}

 


List all Accounts

Retrieves all Accounts.

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
limit 20 A limit on the number of objects to be returned, between 1 and 100. No
starting_after none A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. No
ending_before none A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. No
email none The email address of the account - if specified, all Accounts with that email address value will be returned. No

Accepts

None.

Returns

JSON A list array with a data property that contains an array of up to limit Accounts, starting after the specified starting_after Account (or ending before the specified ending_before Account).. Each entry in the array is a full Account object. If no more Accounts are available, the resulting array will be empty. This request should never throw an error.

A list of Account objects matching the query. Also:

  • “total_count”: Integer count of the number of Accounts in the returned list.
  • “url”: The query string provided in the request
  • “next”: The route (partial URL) to the next Account object (string to select the “next”); included id should match that of the last object returned here
  • “previous”: The route (partial URL) to the previous Account object (string to select the “previous”); included id should match that of the first object returned here
  • cURL
  • Java
Example Request
curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/accounts?limit=1&ending_before=cust_1235"
The above command returns JSON structured like this:
{
    "object": "List",
    "data": [
        {
        "object": "Account",
        "id": "cust_1234",
        "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
        "created": "2016-05-18T13:39:03-07:00",
        "default_currency": "USD",
        "email": "cbrown@example.com",
        "email_type": "html",
        "language": "EN-U",
        "notify_before_billing": true,
        "company": "Peanuts",
        "name": "Charlie Brown",
        "shipping_address": {
            "object": "Address",
            "vid": "dad524f59d1bd72f10a9162b7d7790caa39678dc",
            "name": "Charlie Brown",
            "line1": "123 Main Street",
            "city": "San Francisco",
            "district": "CA",
            "postal_code": "94105",
            "country": "US",
            "phone": "415-555-3212"
        },
        "metadata": {
            "favorite dog": "Snoopy",
            "favorite activity": "flying kites"
        }
        }
    ],
    "total_count": 1,
    "url": "/accounts?limit=1",
    "next": "/accounts?limit=1&starting_after=cust_1234",
    "previous": "/accounts?limit=1&ending_before=cust_1234"
}

 


 

Grant (add a) credit

Grant a new credit to an Account.

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve Yes

Query Parameters

None.

Accepts

JSON A (new) Credit sub-resource. This represent a brand new “grant” of a particular type of credit to be issued and maintained for the specified Account.

Returns

JSON A (new) Credit sub-resource.

  • cURL
  • Java
 

 


 

Revoke credit

Not Yet Implemented.

Revoke some or all of the remainder of an existing credit grant.

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve Yes
account n/a The id or the vid of the Credit to revoke/reduce Yes

Not specifying a credit will cause CashBox to revoke credit on the oldest “grant” and continue until the full amount specified has been removed (up to the total credit balance on the account - excess amounts are ignored).

Query Parameters

None.

Accepts

JSON An (existing) Credit sub-resource. This request supports the same arguments as 'credit_grant’ (a full Credit object) excepting the behavior of the ids; providing an id or vid in the URL indicates to CashBox that this is an revocation. Providing a negative value will reduce or revoke that amount from the remainder of the existing credit.

Returns

JSON An (existing) Credit sub-resource representing the status after the change.

  • cURL
  • Java
 

 


 

Fetch credits (for an Account)

Revoke some or all of the remainder of an existing credit grant.

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve Yes

Query Parameters

Parameter Default Description Required
limit 20 A limit on the number of objects to be returned, between 1 and 100. No
starting_after none A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. No
ending_before none A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list. No

Accepts

None.

Returns

JSON A list array with a data property that contains an array of up to limit Credits, starting after the specified starting_after Credit (or ending before the specified ending_before Credit). Each entry in the array is a full Credit object for the given Account. If no more Credits are available, the resulting array will be empty. This request should never throw an error.

A list of Credit objects matching the query. Also:

  • “total_count”: Integer count of the number of Credits in the returned list.
  • “url”: The query string provided in the request
  • “next”: The route (partial URL) to the next Credit object (string to select the “next”); included id should match that of the last object returned here
  • “previous”: The route (partial URL) to the previous Credit object (string to select the “previous”); included id should match that of the first object returned here
  • cURL
  • Java
 

 

 

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top