NAV
cURL Java

Overview

The Rest API for Subscribe provides predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

Additional Resources

Our User Guides are always a good starting point for Subscribe related questions as well as our Knowledge Base.

Swagger

See our ever-growing Swagger Rest API Reference: https://app.swaggerhub.com/apis-docs/Amdocs_Media/Subscribe_API

Environments

Subscribe provides two distinct environments for testing and production, ProdTest for staging and testing, and a single environment for Production. Your API User and Key will be specific to a given environment.

The ProdTest environment allows you to test your application against the code currently running in Production.

https://api.prodtest.vindicia.com

The Production environment is for real-world use for actual billing and subscription activity.

https://api.vindicia.com

Interacting with the API

Making Requests

As per RESTful design patterns, the Subscribe API implements following HTTP verbs:

Verb Description
GET Retrieve resources (as a list or single record fetch)
POST Create new resources or update existing ones (overloading during create/update is permitted where specified)
DELETE Remove an ownership or hierarchical association between certain resources

When making requests, arguments must be passed as JSON with the Content-Type header set to application/json. All responses will be made in JSON as well.

Example

POST /transactions
Content-Type: application/json
Content-Length: 94

{
    "object" : "Transaction",
    "id" : "tx_1234",
    "created" : "2020-01-01T00:55:47Z"
}

Status Codes

Subscribe uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a payment failed, etc.), and codes in the 5xx range indicate an error with Vindicia’s servers (these are rare). When an error occurs additional information will be returned in the error response.

Code Status Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized Couldn’t authenticate your request
403 Forbidden Authentication failed - check your username and password
404 Not Found The requested resource doesn’t exist
429 Too Many Requests Too many requests hit the API too quickly.
500 Internal Server Error We had a problem with our server. Try again later.
503 Service Unavailable We’re temporarily offline for maintenance. Please try again later.

Example Basic HTTP Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 150
Request-Id: d837becba3325b62adddb2b0f1d7ab48824ff248
Connection: close

{
    "object" : "Transaction",
    "id" : "tx_1234",
    "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e",
    "created" : "2020-01-01T00:55:47Z"
}

Fields

All resources are represented by a unique, Vindicia identifier - a vid. Many resources also provide an id field for you to record your unique identifier which can contain any alphanumeric character but must not contain a /.

When referring to a resource either the vid or the id may be used.

GET https://api.vindicia.com/transactions/:id

GET https://api.vindicia.com/transactions/:vid

Resources also have an object field which represents the resource type.

Example Call

{
    "object" : "Transaction",
    "id" : "tx_1234",
    "vid" : "40f24148bdc282640b46ad281eec31f7dfd9202e",
    "created" : "2020-01-01T00:55:47Z",
    "url" : "/transactions/tx_1234"
}

Timestamps

All timestamps are represented in ISO8601 format. Timestamps may be submitted in any timezone but will be returned in US-PACIFIC (UTC Time standard pending).

Strings

All strings are 1,024 characters unless otherwise noted. Submitting values in excess of this limit will return an error.

Enumerable Values

Some fields like object have a constant set of values. Submitting any value other than those documented will result in an error being returned with a status code of 400.

Arrays and Lists

The API returns multiple resources as list objects containing JSON array. Lists provide the ability to sparsely represent the resources they contain. Additional data can be accessed through pagination.

Example Request (Excerpt)

{
    "object" : "Subscription",
    "id" : "sub_1234",

    "items": [
       {
        "object": "SubscriptionItem",
        "id": "sub_1234.1",
        "product": {
            "object": "Product",
            "id": "prod_1234"
        }
       },
       {
        "object": "SubscriptionItem",
        "id": "sub_1234.2",
        "product": {
            "object": "Product",
            "id": "prod_1235"
        }
       }
      ]
      ...
}

Example Response (Excerpt)

{
    "items": {
        "object": "List",
        "data": [
           {
            "object": "SubscriptionItem",
            "id": "sub_1234.1",
            "index": 0,
            "product": {...},
            "quantity": 1,
            "created": "2020-05-27T05:52:02-07:00",
            "starts": "2020-05-27T00:00:00-07:00"
           },
           {
            "object": "SubscriptionItem",
            "id": "sub_1234.2",
            "index": 0,
            "product": {...},
            "quantity": 1,
            "created": "2020-05-27T05:52:02-07:00",
            "starts": "2020-05-27T00:00:00-07:00"
           }
        ],
    "total_count": 2
}

Creating and Updating Objects

For expedience and convince most object create calls allow for the creation of subobjects when doing the initial creation. However, updating is purposefully always an atomic operation to prevent accidental data loss.

For example: When creating an Account you can create a new Payment Method but in order to update a Payment Method on an existing Account you will need to use the Payment Methods endpoints.

Authentication

Authentication to the API is performed via HTTP Basic Auth using your environment specific API user and key as the username and password.

Example cURL Api Key Usage

curl "https://api.vindicia.com/subscriptions"
  -u acaff38d462f9430d5cbcbaf:a575771fc679b9de

Example JavaScript Api Key Usage

const subscribe_api_key = "acaff38d462f9430d5cbcbaf:a575771fc679b9de";

Pagination

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call.

To make it easier, the API will assign the next call into next attribute together with all the currently used pagination parameters. You know that you have paginated all the results when the return is empty (next value will be undefined, as well).

Using cursor-based pagination protects against the situation when the resulting object list changes during pagination (new resource gets added or removed).

The default limit is set to 20 but values up to 100 are permitted.

Parameter Description
limit optional A limit on the number of objects to be returned, between 1 and 100.
starting_after optional 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.
ending_before optional 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.

Example Call

GET /foos
Content-Type: application/json
Content-Length: 32509

Example Collection Pagination

{
  "object": "List",
  "data": [...],
  "total_count": 31,
  "url": "/foos",
  "next": "/foos?starting_after=Montly+Stream",
  "previous": "/foos?ending_before=Daily+Stream"
}

Errors

All error responses will return an error object.

Attributes

Name Type Description
object string Value is “Error”
message string A human-readable message providing more detailed information about the error.

Example Error JSON

{
   "object" : "Error",
   "message" : "Not implemented yet."
}

Versioning

The API version is based on the date of the last breaking change.

The current version is 2019-05-01.

To set the API version on a specific request send an X-API-Version header.

Most additions to the API will not require a new version of the API.

If no version is specified your default API version will be used. Your default API version is set automatically the first time you make a request.

Request Ids

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Metadata

Metadata are sets of key-value pairs and are useful for storing additional, unstructured information on an object. This object is used to store a list of keys, which you create and associate with text string values.

The metadata field supports key-value pairs with the following limitations:

In some cases metadata from one object will be inherited automatically from one object to another that is spawned from it. e.g. metadata on a Subscription and SubscriptionItem will be inherited by all Transactions and TransactionItems that result from them.

Example Metadata JSON

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

Endpoints

The Subscribe REST API exposes key resources as endpoints which can be manipulated using standard methods. Critical sub-resources which only work in the context of their parent are defined here under their endpoint; other sub-resources, shared between other objects but not directly manipulated are documented in the Resources section.

Accounts

The Account represents a merchant’s 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. Subscriptions and Transactions must belong to an Account - as such, Accounts will be required in Subscribe for billing.

An Account can have any number of children accounts and may have up to one parent account. Read more in our User Guide.

An Account owns the “on file” payment methods to be used by it in billing.

Supported Operations

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

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

The Account object

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 Subscribe.
created datetime The datetime the Account was created. Read only.
external_id string An additional merchant-specified unique identifier for when you have two external (non-Subscribe) systems using two different identification schemes for the same customer. It can be used in place of vid or id
parent Account The parent Account object id or vid 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 Payment Method[] 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 Tax Exemption[] Tax Exemptions registered for this Account.
tokens Token Amount[] 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 rules defined with merchant’s tax service.

Example Object

{
    "object": "Account",
    "id": "cust_1234",
    "vid": "f147870b2c86a00fb1264fb64c0a8b58fcd95b4d",
    "created": "2020-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 object in Subscribe. When creating an Account you can create its sub-objects such as Payment Methods.

HTTP Request

POST https://api.vindicia.com/accounts

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Account object.

Returns

JSON - A full Account object.

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"

Fetch an Account

Retrieves a specific Account by your merchant set ID or the Subscribe set VID.

HTTP Request

GET https://api.vindicia.com/accounts/: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.

Example Request

curl -X GET
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de
"https://api.prodtest.vindicia.com/accounts/cust_1234"

Update an Account

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

HTTP Request

POST https://api.vindicia.com/accounts/:account

Route (URL) Parameters

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

Query Parameters

Parameter Default Description Required
update_behavior none Can be Validate, CatchUp, CatchUpOrValidate
replace_on_all_subscriptions false If false, then the a Payment Method will not be applied to any subscriptions. If it is true, it will be applied to all.
ignore_avs false Overrides any custom or default avs policy.
ignore_cvn false Overrides any custom or default cvn policy.

Accepts

JSON - This request supports the same arguments as ‘create’ (a full Account object) excepting the behavior of the id; providing an id or vid in the URL indicates to Subscribe 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.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
  "id": "cust_1234",
  "email": "charlie.brown@example.com"
}' "https://api.prodtest.vindicia.com/accounts/cust_1234"

List all Accounts

Retrieves all Accounts.

HTTP Request

GET https://api.vindicia.com/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
created_before none Used to limit results to Accounts created before a specified datetime. No
created_after none Used to limit results to Accounts created after a specified datetime. No
email none The email address of the account - if specified, all Accounts with that email address value will be returned. No
payment_method none This method will return a list of accounts that have the specified Payment Method id or vid associated with them. No
payment_method.boleto.fiscal_number none Limit list to accounts with the Boleto payment method and specified Boleto fiscal number. No
payment_method.carrier_billing.encoded_phone_number none Limit list to accounts with the CarrierBilling payment method and specified Carrier Billing encoded phone number. No
payment_method.carrier_billing.phone_number none Limit list to accounts with the CarrierBilling payment method and specified Carrier Billing billing phone number. No
payment_method.credit_card.account none Limit list to accounts with the Credit Card payment method and specified account number. No
payment_method.direct_debit.account none Limit list to accounts with the Direct Debit payment method and specified account number. No
payment_method.direct_debit.bank_sort_code none Limit list to accounts with the Direct Debit payment method and specified bank sort code. No
payment_method.ecp.account none Limit list to accounts with the ACH (aka ECP) payment method and specified account number. No
payment_method.ecp.routing_number none Limit list to accounts with the ACH (aka ECP) payment method and specified routing number. No
payment_method.merchant_accepted_payment.last_digits none Limit list to accounts with the Merchant Accepted Payment (Pay By Invoice) payment method and specified last digits. No
payment_method.merchant_accepted_payment.payment_id none Limit list to accounts with the Merchant Accepted Payment (Pay By Invoice) payment method and specified payment id. No
payment_method.paypal.paypal_email none Limit list to accounts with the PayPal payment method and specified email address. 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:

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/accounts?limit=1&ending_before=cust_1235"

Modify a Currency Credit

Update an existing Currency Credit Amount, including incrementing/decrementing the amount or Revoking the remainder of the Credit. Using a Currency Amount Object, manipulate the amount by providing positive values to increase the credit amount, negative values to decrease the credit amount, or a negative for the full remaining credit amount to revoke the currency credit entirely.

HTTP Request

POST https://api.vindicia.com/accounts/:account/currency_amount_changes

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) Currency Amount sub-resource. The Currency Amount object represents the the change in the Currency Credit.

Returns

JSON - A (new) Currency Amount sub-resource.

Fetch Currency Credit Amount Change

Fetch a specific Currency Credit Amount Change to see additional details of the adjustment to the Credit.

HTTP Request

GET https://api.vindicia.com/accounts/:account/currency_amount_changes/:currency_amount

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve currency credit amount changes for. Yes
currencyAmount n/a The vid of the Currency Amount that was updated. Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - the specified Currency Amount sub-resource in full.

Fetch All Currency Credit Amount Changes

Fetch all Currency Credit Amount Changes for an Account.

HTTP Request

GET https://api.vindicia.com/accounts/:account/currency_amount_changes

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve currency credit amount changes for Yes

Query Parameters

Parameter Type Default Description Required
limit integer 20 A limit on the number of objects to be returned, between 1 and 100. No
starting_after string 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 string 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 Currency Amounts, starting after the specified starting_after Currency Amount (or ending before the specified ending_before Currency Amount). If no more Currency Amounts are available, the resulting array will be empty. This request should never throw an error.

A list of Currency Amount objects matching the query. Also:

Modify a Token Credit

Update an existing Token Credit Amount, including incrementing/decrementing the amount or Revoking the remainder of the Credit. Using a Token Amount Object manipulate the amount by providing positive values to increase the token credit amount, negative values to decrease the token credit amount, or a negative for the full remaining token credit amount to revoke the token credit entirely.

HTTP Request

POST https://api.vindicia.com/accounts/:account/token_amount_changes

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to modify a token credit amount Yes

Query Parameters

None.

Accepts

JSON - A (new) Token Amount sub-resource.

Returns

JSON - A (new) Token Amount sub-resource.

Fetch Token Credit Amount Change

Fetch a specific Token Credit Amount Change to see additional details of the adjustment to the Credit.

HTTP Request

GET https://api.vindicia.com/accounts/:account/token_amount_changes/:token_amount

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to fetch the token credit amount changes for. Yes
tokenAmount n/a The vid of the Token Amount that was updated

Query Parameters

None.

Accepts

None.

Returns

JSON - the specified Token Amount sub-resource in full.

Fetch All Token Credit Amount Changes

Fetch all Token Credit Amount Changes for an Account.

HTTP Request

GET https://api.vindicia.com/accounts/:account/token_amount_changes

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account to retrieve all token amount changes for. Yes

Query Parameters

Parameter Type Default Description Required
limit integer 20 A limit on the number of objects to be returned, between 1 and 100. No
starting_after string 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 string 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 Token Amounts, starting after the specified starting_after Token Amount (or ending before the specified ending_before Token Amount). If no more Token Amounts are available, the resulting array will be empty. This request should never throw an error.

A list of Token Amount objects matching the query. Also:

Add Child Account

Subscribe supports two-level account hierarchies for payment and reporting; that is, you may define parent and children accounts. A parent can have multiple children, but a child may have only one parent, and a child may not be a parent to another Account.

A parent can pay for its own Subscriptions or one-time transactions, or for any of its children’s Subscriptions or one-time transactions. (This is handled by allowing a parent’s Payment Method to be on an Subscription with the child’s Account.)

Children may have Payment Methods that differ from their Parent’s, and may use either theirs or their parent’s to pay for their Subscriptions.

HTTP Request

POST https://api.vindicia.com/accounts/:account/children

Route (URL) Parameters

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

Query Parameters

Parameter Default Description Required
force false force will override any existing parent accounts of the child account No
payer_replacement_behavior ReplaceOnlyFutureAutoBills Can be ReplaceOnAllAutoBills, ReplaceOnlyFutureAutoBills No

Accepts

JSON - A new or existing Account.

Returns

JSON - An Account object.

Fetch All Child Accounts

Retrieves all child accounts for a specified parent account.

HTTP Request

GET https://api.vindicia.com/accounts/:account/children

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Child Accounts, starting after the specified starting_after Account (or ending before the specified ending_before Account). 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:

Fetch Account Family

Return the family of the specified account.

HTTP Request

GET https://api.vindicia.com/accounts/:account/family

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Family Accounts, starting after the specified starting_after Account (or ending before the specified ending_before Account). 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:

Remove Child Account

Remove parent relationship on a specified child account.

HTTP Request

DELETE https://api.vindicia.com/accounts/:account/children/:child

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the parent Account Yes
child n/a The id or the vid of the Child Account to remove from the parent Account Yes

Query Parameters

Parameter Default Description Required
payer_replacement_behavior ReplaceOnlyFutureAutoBills Can be ReplaceOnAllAutoBills, ReplaceOnlyFutureAutoBills No

Accepts

None.

Returns

None.

Grant Entitlement

The grant Entitlement method grants an Account-level Entitlement to an Account.

HTTP Request

POST https://api.vindicia.com/accounts/entitlements

Route (URL) Parameters

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

Query Parameters

Parameter Default Description Required
note none Note (freeform string) associated with granting the Entitlement No

Accepts

JSON - A new or existing Entitlement.

Returns

JSON - An Account object.

Revoke Entitlement

Revokes entitlement from an Account.

HTTP Request

DELETE https://api.vindicia.com/accounts/entitlements/:entitlement

Route (URL) Parameters

Parameter Default Description Required
account n/a The id or the vid of the Account Yes
entitlement n/a The id or the vid of the Entitlement to be revoked Yes

Query Parameters

Parameter Default Description Required
note none A freeform string associated with granting the Entitlement no

Accepts

JSON - A new or existing Entitlement.

Returns

JSON - An Account object.

Activities

The Activity object enables you to record activities (events) on your site that are not direct purchase transactions, such as when customers access for-pay content like song downloads. That information can serve as evidence for chargeback disputes should they occur.

You make calls available for the Activity object to submit the activity data once per event. Alternatively, queue and submit the data periodically in a batch process. Usually, you collect events of interest only. For example, you need not record every page view by a customer, only those page views that contain for-pay content that the customer accessed or downloaded.

Supported Operations

GET | list (filtered), fetch (individual Activity)

POST | create (individual Activity record)

The Activity object

To record an activity, fill in as many of the data-member fields of the Activity object as possible. The more information you collect, the more useful it will be for Vindicia to dispute chargebacks on your behalf should they occur.

The following table lists and describes the data members of the Activity object.

Attributes

Name Type Description
object string Value is “Activity”
vid string A Globally Unique Identifier (GUID) for this object. Assigned by Subscribe.
account Account Required. The customer account id or vid for which you are recording this activity.
subscription Subscription The subscription id or vid for which you are recording this activity.
transaction Transaction The transaction id or vid for which you are recording this activity.
invoice Invoice The invoice id or vid for which you are recording this activity.
timestamp datetime Required. A time stamp that specifies the date and time of when the event you are recording took place.
type enum Can be Cancellation, Email, Fulfillment, Login, Logout, NamedValue, Note, Phone, URIView, Usage
login_args Activity Login The IP address from which a login originated.
logout_args Activity Logout The IP address from which a logout originated.
uriview_args Activity URI View A customer’s visit to a Web page, and possible download activity.
phone_args Activity Phone A phone contact that relates to the Activity object.
email_args Activity Email An email event.
fulfillment_args Activity Fulfillment The status of your fulfillment of a customer order.
usage_args Activity Usage The amount of use of a resource (such as the number of downloads) you provide to the customer.
namedvalue_args Activity Named Value An activity defined by you. With this data structure, you create Activity objects that are unique to your business, and that are not described by the predefined Activity events in Activity Types. Creating such an activity implies that it will likely occur regularly with your customers.
cancellation_args Activity Cancellation The customer’s cancellation of a service or product.
note_args Activity Note An optional memo on the Activity object.

Create an Activity (Record)

Report non-transaction activities to Vindicia.

HTTP Request

POST https://api.vindicia.com/activities

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - An Activity object.

Returns

JSON - A full Activity object.

Fetch a specific Activity Record

Retrieve a specific activity record.

HTTP Request

GET https://api.vindicia.com/activities/:activity

Route (URL) Parameters

Parameter Default Description Required
activity n/a The vid of the Activity record to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Activity object.

List all Activities

Retrieves filtered list of recorded activities.

HTTP Request

GET https://api.vindicia.com/activities

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
account n/a The account id or vid to return a list of activity for No
subscription n/a The subscription id or vid to return a list of activity for No
transaction n/a The transaction id or vid to return a list of activity for No
invoice n/a The invoice id or vid to return a list of activity for No

Accepts

None.

Returns

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

A list of Activity objects matching the query. Also:

Billing Plans

A Billing Plan represents a pre-defined billing and pricing schedule. Every subscription is billed according to its assigned Billing Plan. A Billing Plan can be a complex object made up of one or more Billing Periods, each of which have configurable rules for how many cycles they repeat, as well as other billing, entitlement, and communication rules.

Supported Operations

GET | list (all; filtered), fetch (individual BillingPlan)

POST | create (individual BillingPlan), update (individual BillingPlan)

The Billing Plan object

The Billing Plan object is the schedule and, optionally, pricing rules for a subscription; every Subscription must have a Billing Plan assigned.

Attributes

Name Type Description
object string Value is “BillingPlan”
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 Subscribe.
created datetime The date and time the plan was created. Read only.
description string A Merchant-specified description of this offering.
status enum Merchants may define whether they want to declare a plan as available to offer. Values can be Active,Suspended
tax_classification string The tax classification or code to be used with any plan-level charges.
br_tax_category enum Enum used for Brazilian tax calculations. Values can be Goods, Services
trial Billing Plan Period Optionally declares an initial trial period for this plan.
periods Billing Plan Period[] Defines the sequential billing periods in the plan, each with its own billing schedule and terms.
billing_notification_days integer Number of days prior to schedule billing at which Subscribe will send email notification.
trial_end_notification_days integer For the trial period, this replaces billing_notification_days, indicating the # of days prior to end of a trial to send the trial end email.
skip_initial_billing_notification boolean Determines whether to send a billing notification for the initial period.
end_of_life datetime The date after which the plan should not be offered.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
entitlements Entitlement[] Entitlements granted by active subscriptions on this plan.
billing_descriptor string Optional “soft descriptor” to send to the payment processor for transactions associated with a subscription using this billing plan.
grace_period_override integer Number of days after the billing date when, if payment is not received, the Subscription is stopped and the customer is disentitled; overrides the global merchant default setting, if both are set.
minimum_commitment integer Number of billing cycles the customer is contractually obligated to complete before cancelling. The only impact this has is upon the cancelling a Subscription.
cancel_fees Billing Plan Cancel Fee[] List of early cancel fees for various currencies.
times_to_run string The number of times the sequence of Billing Periods should be repeated. Valid input includes positive integers. (Default is null.) Advanced Setting
entitlements_valid_for string The length of time for which Entitlements are valid after the last Billing date. (Default is null.) Advanced Setting
repeat_every string If a Billing Period set repeats, this value defines the length of time after the first billing that the set should repeat. Advanced Setting
season_set Season Set The SeasonSet to which the Billing Plan applies. (May be null.)
days_before_season_to_bill integer Optional setting when using a season set to control the integer number of days before a season starts to bill. Advanced Setting
days_entitled_before_season integer Optional setting when using a season set to control the integer number of days customer is entitled before a season starts Advanced Setting
days_entitled_after_season integer Optional setting when using a season set to control the integer number of days after a season ends a customer remains entitled. Advanced Setting
entitled_off_season boolean Optional setting when using a season set to continue entitling customer between seasons. Advanced Setting
used_on_subscriptions boolean Signifies if Billing Plan has been used on an Active Subscription Read Only

Example Billing Plan Object

{
   "object":"BillingPlan",
   "id":"plan_1234",
   "vid":"1d557e85e70a13140dcc9bd4fd18a02f63f09084",
   "created":"2020-05-27T14:42:08-07:00",
   "description":"Simple Monthly Billing Plan",
   "status":"Active",
   "periods":{
      "object":"List",
      "data":[
         {
            "object":"BillingPlanPeriod",
            "type":"Month",
            "quantity":1,
            "cycles":0,
            "prices":{
               "object":"List",
               "data":[
                  {
                     "object":"BillingPlanPrice",
                     "amount":0,
                     "currency":"USD"
                  }
               ],
               "total_count":1
            }
         }
      ],
      "total_count":1
   },
   "end_of_life":"2099-12-31T00:00:00-08:00",
   "metadata":{
      "CatalogID":"plan1234"
   },
   "entitlements":{
      "object":"List",
      "data":[
         {
            "object":"Entitlement",
            "id":"plan_1234",
            "description":"plan_1234"
         }
      ],
      "total_count":1
   }
}

Create a Billing Plan

Creates a new Billing Plan object.

HTTP Request

POST https://api.vindicia.com/billing_plans

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Billing Plan object.

Returns

JSON - A full Billing Plan object.

Example Request

curl -X POST
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
    "object": "BillingPlan",
    "id": "plan_1235",
    "description": "Simple Monthly Plan with Trial",
    "trial": {
        "object": "BillingPlanPeriod",
        "type": "Day",
        "quantity": 7,
        "cycles": 1,
        "prices": [
            {
              "object": "BillingPlanPrice",
              "amount": 0,
              "currency": "USD"
            }
        ]
    },
    "periods": [
        {
          "object": "BillingPlanPeriod",
          "type": "Month",
          "quantity": 1,
          "cycles": 1,
          "prices": [
            {
              "object": "BillingPlanPrice",
              "amount": 49.99,
              "currency": "USD"
            }
        ]
        }
    ],
    "metadata": {
      "plan info": "trial billing plan"
    },
    "entitlements": [
        {
          "object": "Entitlement",
          "id": "ent_p1235",
          "description": "Access to ent_p1235"
        }
    ]
    }' \
"https://api.prodtest.vindicia.com/billing_plans"

Fetch a specific BillingPlan

Retrieves a specific Billing Plan.

HTTP Request

GET https://api.vindicia.com/billing_plans/:billingplan

Route (URL) Parameters

Parameter Default Description Required
BillingPlan n/a The id or the vid of the billing plan to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Billing Plan object.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/billing_plans/plan_1234"

Update a BillingPlan

Update a specific Billing Plan.

HTTP Request

POST https://api.vindicia.com/billing_plans/:billingplan

Route (URL) Parameters

Parameter Default Description Required
BillingPlan n/a The id or the vid of the Billing Plan to retrieve Yes

Query Parameters

None.

Accepts

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

Returns

JSON - A full Billing Plan object.

List all BillingPlans

Retrieves all Billing Plans.

HTTP Request

GET https://api.vindicia.com/billing_plans

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
limit 20 Allows for setting the max length of the returned array in the paginated results. Allowed values are between 1- 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

A JSON list object that contains an array of Billing Plans, starting after the specified starting_after Billing Plan (or ending before the specified ending_before Billing Plan). If no more Billing Plans are available, the resulting array will be empty.

Additional list data included:

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/billing_plans?limit=1"

The above command returns JSON structured like this:

{
    "object": "List",
    "data": [
        {
        "object": "BillingPlan",
        "id": "TESTPLAN0",
        "vid": "7835983e7d0608d36d4f40b01ab8843e011ab8d9",
        "created": "2013-04-15T10:21:43-07:00",
        "description": "TESTPLAN0 $0 Monthly",
        "status": "Active",
        "periods": {
            "object": "List",
            "data": [
                {
                "object": "BillingPlanPeriod",
                "type": "Month",
                "quantity": 1,
                "cycles": 0,
                "prices": {
                    "object": "List",
                    "data": [
                        {
                        "object": "BillingPlanPrice",
                        "amount": 0,
                        "currency": "USD"
                        }
                    ],
                    "total_count": 1
                    }
                }
            ],
            "total_count": 1
            },
        "metadata": {
            "plansource": "External",
            "plangroup": "April2013"
        },
        "billing_descriptor": "TESTPLAN0"
        }
    ],
    "total_count": 1,
    "url": "/billing_plans?limit=1",
    "next": "/billing_plans?limit=1&starting_after=TESTPLAN0",
    "previous": "/billing_plans?limit=1&ending_before=TESTPLAN0"
}

Campaigns

Subscribe’s Campaigns allow you to offer special discounts on your existing Products and/or Billing Plans. Campaigns are discounts given over a period of time for a service or subscription, and may be applied to multiple Products and Billing Plans.

Supported Operations

GET | list (all; filtered), fetch (individual Campaign)

POST| create (individual Campaign), update (individual Campaign)

The Campaign object

The Campaign object encapsulates the information for a Campaign, including Campaign Type, Status.

Attributes

Name Type Description
object string Value is “Campaign”
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 Subscribe.
name string Name of campaign. Note: Read-only once the Campaign is Active.
description string Description of the Campaign. Note: Read-only once the Campaign is Active.
state enum Can be Active, Canceled, Complete, Inactive, MatchAnyState, Pending, Undefined
offer_start_date datetime The first date on which the offers may be redeemed.
offer_end_date datetime The last date on which the offers may be redeemed.
campaign_type enum specifies what type of campaign this is: Coupon, Promotion.
percentage_discount decimal Defines the discount as a percentage of the original Product price. Note: flat_amount_discounts and percentage_discount are mutually exclusive. It can be either or but not both
eligible_products Product[] Zero or more eligible Products eligible for this Campaign.
eligible_billing_plans Billing Plan[] Zero or more eligible BillingPlans eligible for this Campaign.
restrict_to_new_subscription boolean If true, Campaign offer only applies to new Subscriptions, not existing ones.
expiration_date datetime Expiration date of a “Fixed” Campaign. “Rolling” Campaigns should leave this blank.
number_of_periods integer Number of times the promotion repeats, e.g. if you want to discount 3 cycles of a biweekly subscription, this would be 3.
promotion_code string The redemption code associated with the Promotion.
promotion_code_aliases string[] An array of alternative redemption codes for the Promotion. Note: Setting this array will replace any existing list of aliases; it will not add new values to an existing list.
coupons Coupon[] An array of Coupons. Each Coupon will serve as the collecting object for an array of Coupon Codes. Read Only

Create a Campaign

Creates a new Campaign.

HTTP Request

POST https://api.vindicia.com/campaigns

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Campaign object.

Returns

JSON - A full Campaign object.

Fetch a specific Campaign

Retrieves a specific Campaign.

HTTP Request

GET https://api.vindicia.com/campaigns/:campaign

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Campaign object.

Update a Campaign

Update a specific Campaign.

HTTP Request

POST https://api.vindicia.com/campaigns/:campaign

Route (URL) Parameters

Parameter Default Description Required
campaign n/a The id or the vid of the Campaign to update Yes

Query Parameters

None.

Accepts

JSON - A full Campaign object.

Returns

JSON - A full Campaign object.

List all Campaigns

Retrieves all Campaigns.

HTTP Request

GET https://api.vindicia.com/campaigns

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
state none Can be Active, Canceled, Complete, Inactive, MatchAnyState, Pending No

Accepts

None.

Returns

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

A list of Campaign objects matching the query. Also:

Activate a specific Campaign

Activates a specific Campaign.

HTTP Request

POST https://api.vindicia.com/campaigns/:campaign/actions/activate

Route (URL) Parameters

Parameter Default Description Required
campaign n/a The id or the vid of the Campaign to activate Yes

Query Parameters

None.

Accepts

None.

Returns

None.

Deactivate a specific Campaign

Deactivates a specific Campaign.

HTTP Request

POST https://api.vindicia.com/campaigns/:campaign/actions/deactivate

Route (URL) Parameters

Parameter Default Description Required
campaign n/a The id or the vid of the Campaign to deactivate Yes

Query Parameters

None.

Accepts

None.

Returns

None.

Cancel a specific Campaign

Cancels a specific Campaign.

HTTP Request

POST https://api.vindicia.com/campaigns/:campaign/actions/cancel

Route (URL) Parameters

Parameter Default Description Required
campaign n/a The id or the vid of the Campaign to cancel Yes

Query Parameters

None.

Accepts

None.

Returns

None.

Cancel Reasons

Merchant specified reason for cancelling a Subscription.

Supported Operations

GET | list (all; filtered), fetch (individual CancelReason)

POST| create (individual CancelReason), update (individual CancelReason)

The Cancel Reason object

Attributes

Name Type Description
reason_code string The reason code assigned for the cancellation. Usually a numeric value. Can be 15 characters or fewer. Note: Codes 0 - 100 are reserved by Subscribe
description string A description of the reason for the cancellation. Can be up to 255 characters.

Create a Cancel Reason

Creates a new Cancel Reason.

HTTP Request

POST https://api.vindicia.com/cancel_reasons

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Cancel Reason object.

Returns

JSON - A full Cancel Reason object.

Fetch a specific Cancel Reason

Retrieves a specific Cancel Reason.

HTTP Request

GET https://api.vindicia.com/cancel_reasons/:cancel_reason

Route (URL) Parameters

Parameter Default Description Required
cancel_reason n/a The id or the vid of the Cancel Reason to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Cancel Reason object.

List all Cancel Reasons

Retrieves all Cancel Reasons.

HTTP Request

GET https://api.vindicia.com/cancel_reasons

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

Accepts

None.

Returns

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

A list of Cancel Reason objects matching the query. Also:

Chargebacks

A chargeback is initiated by a customer to reverse a specific transaction charge on their billing statement.

Supported Operations

GET | list (all; filtered), fetch (individual Chargeback)

POST| create (individual Chargeback), update (individual Chargeback)

The Chargeback object

Each Chargeback object holds information about a chargeback against a specific transaction. This transaction could be a one-time transaction, or a re-billing transaction generated by a Subscribe Subscription object. If you are using ChargeGuard only, and are conducting transactions outside of Subscribe, the transaction is simply a transaction reported by you.

Attributes

Name Type Description
object string Value is “Chargeback”
vid string A Globally Unique Identifier (GUID) for this object. Assigned by Subscribe.
amount decimal This chargeback’s settlement amount, which usually matches the amount of the original transaction. In some cases, customers charge back only part of a transaction. (Vindicia does not provide information on the items that are charged back.)
currency string ISO 4217 Currency Code of this chargeback’s settlement amount. The default is USD.
presentment_amount decimal The amount charged back (in the presentment currency), which usually matches the amount of the original transaction. Specify this attribute if the original transaction was processed with Chase Paymentech in a currency other than USD.
presentment_currency string The ISO 4217 currency code of this transaction at presentment. The default is USD.
division_number string The number of your division or group your payment processor used when processing the original Transaction. Chase Paymentech refers to this number as the Division Number; Litle calls it the Report Group; MeS calls it the Profile ID.
reason_code string The reason code reported by your bank for this Chargeback object. Reason codes vary from bank to bank.
case_number string Your bank’s case number for this Chargeback object, if any.
reference_number string Your bank’s reference number for this Chargeback object, if any.
merchant_number string Your bank’s merchant number, which identifies you as the merchant.
transaction_id string Your unique identifier for the transaction associated with this Chargeback object. If Subscribe generated the transaction, for example, for a recurring bill, Subscribe created this ID for you when processing the transaction with your payment processor. If you did not process the transaction through Subscribe, but only reported it to Vindicia, then this ID must match the order number you used when processing the transaction with your payment processor.
transaction_timestamp datetime A time stamp that specifies the date and time when the original transaction occurred.
processor_received_timestamp datetime A time stamp that specifies the date and time when your bank received the chargeback from the customer.
posted_timestamp datetime A time stamp that specifies the date and time when the chargeback was posted in the Vindicia database. The difference in time between the chargeback, and this posted time stamp, will depend on the frequency at which Vindicia downloads chargebacks from your bank or payment processor.
status_changed_timestamp datetime A time stamp that specifies the date and time for the last status change.
status enum Can be Challenged, CollectionsLost, CollectionsNew, CollectionsWon, Duplicate, Expired, Incomplete, Legitimate, Lost, New, NewSecondChargeback, Pass, Represented, Responded, Retrieval, Won
merchant_user_id string Your unique identifier for the account of the customer who conducted the original transaction.
note string Notes on the Chargeback object. Vindicia personnel might make entries here during the dispute process.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Report a Chargeback

This method is rarely used, because Vindicia usually retrieves chargebacks directly from the bank or payment processor on the merchant’s behalf, and enters them into ChargeGuard. If your bank or payment processor does not allow Vindicia access to that information, you must retrieve the chargebacks yourself, and send the information to Vindicia by calling this method.

HTTP Request

POST https://api.vindicia.com/chargebacks

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Chargeback object.

Returns

JSON - A full Chargeback object.

Fetch a specific Chargeback

Retrieves a specified Chargeback.

HTTP Request

GET https://api.vindicia.com/chargebacks/:chargeback

Route (URL) Parameters

Parameter Default Description Required
chargeback n/a The vid of the Chargeback to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Chargeback object.

Update a Chargeback

Updates a specified Chargeback object. This method is rarely used, because Vindicia usually creates and updates chargebacks by retrieving them directly from your payment processor, and updating their status during the dispute process.

HTTP Request

POST https://api.vindicia.com/billing_plans/:billingplan

Route (URL) Parameters

Parameter Default Description Required
chargeback n/a The vid of the Chargeback to update Yes

Query Parameters

None.

Accepts

JSON - Chargeback object.

Returns

JSON - A full Chargeback object.

List all Chargebacks

Retrieves list of all Chargebacks.

HTTP Request

GET https://api.vindicia.com/chargebacks

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
account n/a Account id or vid to filter list by No
include_children false If filtering by Account, include child accounts No
case_number none Filter Chargebacks list by your banks case number No
reference_number none Filter Chargebacks list by your banks case number No
status none Can be Challenged, CollectionsLost, CollectionsNew, CollectionsWon, Duplicate, Expired, Incomplete, Legitimate, Lost, New, NewSecondChargeback, Pass, Represented, Responded, Retrieval, Won No
transaction none Transaction id or vid to filter chargeback list by No

Accepts

None.

Returns

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

A list of Chargeback objects matching the query. Also:

Charges

Adds a non-recurring charge to a given Subscription or Invoice.

Supported Operations

GET | list (all; filtered Charges), fetch (individual Charge)

POST| create (individual Charge), update (individual Charge)

The Charge object

Attributes

Name Type Description
vid string A Globally Unique Identifier (GUID) for this object. Assigned by Subscribe.
subscription Subscription The subscription to which this additional charge applies
invoice Invoice The invoice to which this additional charge applies
description string A description of the charge. This is a free-form string of 256 or fewer characters.
product Product Product used to determine charge amount added to Subscription.
tax_classification string Tax classification for charge. This field is required UNLESS the price is to be based on the Product, (in which case the tax classification can be based on the associated Product tax classification).
amount decimal Amount to charge. This field is required UNLESS the price is to be based on the Product.
currency Enum ISO 4217 currency code for amount. Either token, OR currency must be specified.
token Token Token associated with amount (if this is a Token-based Subscription). Either token, OR currency must be specified.
quantity integer Optional value to be included in charge. Defaults to 1, if not specified

Create a Charge

Creates a new non-recurring charge on the give Subscription or Invoice.

HTTP Request

POST https://api.vindicia.com/charges

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
dryrun false Boolean flag that, if set to true, will return the updated Subscription, without recording the result in the Subscribe database. No
campaign_code n/a Optional Coupon or Promotion Code, used to obtain a discount on this charge. No

Accepts

JSON - A full Charge object.

Returns

JSON - A full Charge object.

Fetch a specific Charge

Retrieves a specific Charge.

HTTP Request

GET https://api.vindicia.com/charges/:charge

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Charge object.

List all Charges

Retrieves all Charges for a given Subscription or Invoice.

HTTP Request

GET https://api.vindicia.com/charges

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
subscription n/a The Subscription id or vid to fetch charges for.
invoice n/a The Invoice id or vid to fetch charges for.

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Charges, starting after the specified starting_after Charge (or ending before the specified ending_before Charge). Each entry in the array is a full Charge object. If no more Charges are available, the resulting array will be empty.

A list of Charge objects matching the query. Also:

Entitlements

The entitlement object represents the services to which a customer is entitled. Entitlement can reside at the Account (granted directly to the Customer) or the Subscription level (granted due to purchase or presence of an active subscription).

Supported Operations

GET | list (all, filtered)

The entitlement object

Attributes

Name Type Description
object string Value is “Entitlement”
id string A merchant-specified unique identifier.
description string The Merchant-specified description of the entitled service.
account Account The Account responsible for granting the Entitlement (if at account-level).
subscription Subscription The Subscription responsible for granting the Entitlement (if at subscription-level).
billing_plan Billing Plan The Billing Plan associated with the entitlement (when at subscription-level and provided due to Billing Plan assignment).
subscription_item Subscription Item The Subscription Item associated with the Entitlement (when at subscription-level and provided due to an active SubscriptionItem with a product granting this Entitlement).
product Product The Product associated with the entitlement (when at subscription-level and provided due to an active Subscription Item with this product).
starts datetime The date/time at which entitlement did or will begin.
ends datetime The date/time at which entitlement did or will end.
active boolean Indicates whether this Entitlement is currently active.

Example Object

{
   "object":"Entitlement",
   "id":"ent_1234",
   "description":"Sample Entitlement",
   "account":{
      "object":"Account",
      "id":"cust_2234",
      "vid":"07ac3365421741777c1f936480918c61aba85759"
   },
   "subscription":{
      "object":"Subscription",
      "id":"sub_1234",
      "vid":"400dc2e6524e754914d8bd40e495f05f53939ddc"
   },
   "subscription_item":{
      "object":"SubscriptionItem",
      "id":"sub_1234.1",
      "vid":"7fb1cdb3fcfa1541c5d31b70332e97cc38cfeab8"
   },
   "product":{
      "object":"Product",
      "id":"prod_1234",
      "vid":"63143baaeb00f89c796681ea1c3298a8b66f6d5e"
   },
   "starts":"2020-05-27T05:52:02-07:00",
   "ends":"2026-08-04T00:00:00-07:00",
   "active":true
}

List Entitlements

Retrieves a list of filtered Entitlements. The list must be constrained to a particular Account (or Account family), or by Entitlement id.

HTTP Request

GET https://api.vindicia.com/entitlements

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
account none Limit the entitlement list to a specified account id or vid - if specified, all Entitlements associated with that Account. No
include_children false Indicates whether or not to return any existing child accounts’ entitlements when an account is specified.

Accepts

None.

Returns

JSON - A list array of Entitlements filtered by the given Query Parameters. Each entry in the array is a full Entitlement object. If no more objects are available, the resulting array will be empty. This request should never throw an error.

A list of Entitlement objects matching the query. Also:

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/entitlements?account=cust_2234"

The above command returns JSON structured like this:

{
   "object":"List",
   "data":[
      {
         "object":"Entitlement",
         "id":"ent_1234",
         "description":"Sample Entitlement",
         "account":{
            "object":"Account",
            "id":"cust_2234",
            "vid":"07ac3365421741777c1f936480918c61aba85759"
         },
         "subscription":{
            "object":"Subscription",
            "id":"sub_1234",
            "vid":"400dc2e6524e754914d8bd40e495f05f53939ddc"
         },
         "subscription_item":{
            "object":"SubscriptionItem",
            "id":"sub_1234.1",
            "vid":"7fb1cdb3fcfa1541c5d31b70332e97cc38cfeab8"
         },
         "product":{
            "object":"Product",
            "id":"prod_1234",
            "vid":"63143baaeb00f89c796681ea1c3298a8b66f6d5e"
         },
         "starts":"2020-05-27T05:52:02-07:00",
         "ends":"2026-08-04T00:00:00-07:00",
         "active":true
      }
   ],
   "total_count":1,
   "url":"/entitlements?account=cust_2234"
}

Events

The Event object represents a specific measured/reported usage record. You can create, retrieve, list, and edit (update) individual usage event records using the Event object.

Supported Operations

GET | list (all), fetch (individual Event)

POST| create (individual Event), update (individual Event)

Attributes

Name Type Description
object string Value is “Event”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe
date_received datetime The date/time at which the event was recorded into Subscribe.
event_date datetime The date/time at which the event occurred (for billing purposes).
description string A Merchant-specified description of the event.
subscription_item Subscription Item The subscription item under which the event is to be recorded and billed.
account Account The account associated with the recorded event.
subscription Subscription The subscription associated with the recorded event.
product Product The product under which the event is to be recorded and billed.
amount decimal The amount of usage units to be billed.
billed_status enum Value can be Billed,Unbilled
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Example Object

{
  "object": "Event",
  "id": "c720b8c1ae181e75a7574e4a05bd43b865c75a64",
  "vid": "c720b8c1ae181e75a7574e4a05bd43b865c75a64",
  "date_received": "2020-01-13T10:46:33-08:00",
  "event_date": "2020-01-13T00:00:00-08:00",
  "subscription_item": {
    "object": "SubscriptionItem",
    "vid": "a4293a900b5b8c96b2b02893595da153c1aba0cc"
  },
  "account": {
    "object": "Account",
    "id": "Account 15",
    "vid": "eead84014a7dce4121b5450d23067b0458f4fd59"
  },
  "subscription": {
    "object": "Subscription",
    "id": "Test 05",
    "vid": "279ff7f98ac4a70bfcc1e5762f6badcadba15114"
  },
  "product": {
    "object": "Product",
    "id": "Basic $100 Product",
    "vid": "a0a793e4498f22a827599fdcce1832fd81b9e939"
  },
  "billed_status": "Billed"
}

List events

Fetch a list of all events on an Account, Subscription, Product, or Rate Plan.

HTTP Request

GET https://api.vindicia.com/events

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
account none The Account id or vid to filter Events by. No
subscription none The Subscription id or vid to filter Events by. No
product none The Product id or vid to filter Events by. No
rate_plan none The Rate Plan id or vid to filter Events by. No
billed none Boolean to filter return by only Events with a billing_status of Billed No

Accepts

None.

Returns

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

A list of Event objects matching the query. Also:

Example Return

{
  "object": "List",
  "data": [
    {
      "object": "Event",
      "id": "2d3dc066b8661d9d7035511b261c3cd8f19aec17",
      "vid": "2d3dc066b8661d9d7035511b261c3cd8f19aec17",
      "date_received": "2020-01-13T09:57:03-08:00",
      "event_date": "2020-01-13T00:00:00-08:00",
      "subscription_item": {
        "object": "SubscriptionItem",
        "vid": "65fc1b6a2988674411f46f309495012aec1bff67"
      },
      "account": {
        "object": "Account",
        "id": "Test Account 12",
        "vid": "a8bb62c9eb3032fd462b4c982f7aa962debd5b24"
      },
      "subscription": {
        "object": "Subscription",
        "id": "Hi 02",
        "vid": "42f130646772d5cb688c9d6262fd2365660eaa54"
      },
      "product": {
        "object": "Product",
        "id": "Basic $20 Product",
        "vid": "cf9d9ed3fc896487e20ce36b7e1d4b71bccc9e4f"
      },
      "billed_status": "Billed"
    },
    {
      "object": "Event",
      "id": "c720b8c1ae181e75a7574e4a05bd43b865c75a64",
      "vid": "c720b8c1ae181e75a7574e4a05bd43b865c75a64",
      "date_received": "2020-01-13T10:46:33-08:00",
      "event_date": "2020-01-13T00:00:00-08:00",
      "subscription_item": {
        "object": "SubscriptionItem",
        "vid": "a4293a900b5b8c96b2b02893595da153c1aba0cc"
      },
      "account": {
        "object": "Account",
        "id": "Test Account 15",
        "vid": "eead84014a7dce4121b5450d23067b0458f4fd59"
      },
      "subscription": {
        "object": "Subscription",
        "id": "Refund Me 05",
        "vid": "279ff7f98ac4a70bfcc1e5762f6badcadba15114"
      },
      "product": {
        "object": "Product",
        "id": "Basic $100 Product",
        "vid": "a0a793e4498f22a827599fdcce1832fd81b9e939"
      },
      "billed_status": "Billed"
    }
  ],
  "total_count": 2,
  "url": "/events",
  "next": "/events?starting_after=5484ec665b3bd4a707c486e1f5096ab7dcc94a68",
  "previous": "/events?ending_before=2d3dc066b8661d9d7035511b261c3cd8f19aec17"
}

Fetch an event

Fetch a specific event detail.

HTTP Request

GET https://api.vindicia.com/events/:event

Route (URL) Parameters

None.

Query Parameters

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

Accepts

None.

Returns

JSON - A full Event object.

Record (Create) events

Record one or more events.

HTTP Request

POST https://api.vindicia.com/events

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - An array of one or more usage Events.

Returns

JSON - An array of one or more usage Events.

Update or Edit an event.

Edit an existing event.

HTTP Request

POST https://api.vindicia.com/events/:event

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
event n/a The id or the vid of the Event to update Yes

Accepts

JSON - Updates/changes/additions to the Event detail.

Returns

JSON - A full Event object representing the changed Event detail.

Invoices

An Invoice presents the details for a particular billing - including the charges, taxes, credits, and payments related for a particular one-time purchase or subscription billing period. The API allows you to retrieve individual Invoices as well as a list of all of your Invoices using defined filters and/or pagination.

Supported Operations

GET | list (all; filtered), fetch (individual Invoice)

The Invoice object

Attributes

Name Type Description
object string Value is “Invoice”
id string A Subscribe-specified identifier for the invoice, aka Invoice Number.
vid string A read-only Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
invoice_date datetime The billing date of the invoice. Typically the 1st day of the billed service period. This is the day when the invoice status goes from Open to Due.
due_date datetime The due date of the invoice. Typically the same as the “invoice date” unless Net Terms are specified for the Subscription.
billing_service_period_start datetime Start of the billing/service period covered by this invoice.
billing_service_period_end datetime End of the billing/service period covered by this invoice.
status enum The status of the invoice. Values can be Open, Due, Paid, Overdue, Closed, Written Off.
invoice_currency string An ISO 4217 Currency Code. An invoice’s charges must be in a single currency.
original_invoice_amount decimal The original net total of the invoice (in the currency identified as the invoice_currency).
invoice_balance decimal The current balance due of the invoice (in the currency identified as the invoice_currency).
gross_charges_total decimal The original gross charges total of the invoice (in the currency identified as the invoice_currency). Represents the pre-tax, pre-discount sub-total of all charge/purchase items.
tax_charges_total decimal The original tax total of the invoice (in the currency identified as the invoice_currency).
credit_total decimal The original discount and credit total of the invoice (in the currency identified as the invoice_currency).
payments_received_total decimal The current currency total of all payments successfully processed against this invoice.
invoice_line_items Invoice Item[] The purchase or charge-based line items for the invoice.
invoice_tax_items Invoice Item[] The tax-related line items for the invoice.
invoice_credit_items Invoice Item[] The discount or credit line items for the invoice.
invoice_payments Transaction[] Transactions which paid some or all of the invoice balance.
account Account The account invoiced. Minified: includes id and vid only
subscription Subscription The subscription for which this invoice bills. Minified: includes id and vid only
billing_sequence integer The subscription’s billing cycle for which this invoice charges. As a zero-based index, this indicates the renewal number.
invoice_terms integer Invoice terms from the owning Subscription. Represents Days after the invoice date at which a bill is considered delinquent, if the Subscription](#subscriptions) payment method is of type Merchant Accepted Payment. The value will be undefined for all other payment method types.
affiliate string Affiliate or channel identifier, if any, under which the subscription was submitted.
sub_affiliate string A more granular or subordinate affiliate identifier.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information. Invoice metadata is be inherited from the owning Subscription’s metadata.

Example Object

{
    "object": "Invoice",
    "id": "sub_1234-00000004",
    "invoice_date": "2020-06-16T00:00:00-07:00",
    "due_date": "2020-06-16T00:00:00-07:00",
    "billing_service_period_start": "2020-06-16T00:00:00-07:00",
    "billing_service_period_end": "2020-07-15T23:59:59-07:00",
    "status": "Paid",
    "invoice_currency": "USD",
    "original_invoice_amount": 15,
    "invoice_balance": 0,
    "gross_charges_total": 15,
    "tax_charges_total": 0,
    "credit_total": 0,
    "payments_received_total": 15,
    "invoice_line_items": {
       "object": "List",
       "data": [
          {
             "object": "InvoiceItem",
             "index_number": 0,
             "type": "RecurringCharge",
             "sku": "prod_1234",
             "description": "Product 1",
             "quantity": 1,
             "unit_amount": 0,
             "tax_classification": "TaxExempt",
             "item_added": "2020-06-16T00:00:00-07:00",
             "item_removed": null
          },
          {
             "object": "InvoiceItem",
             "index_number": 1,
             "type": "RecurringCharge",
             "sku": "prod_1235",
             "description": "Product 2",
             "quantity": 1,
             "unit_amount": 5,
             "tax_classification": "TaxExempt",
             "item_added": "2020-06-16T13:56:35-07:00",
             "item_removed": null
          },
          {
             "object": "InvoiceItem",
             "index_number": 2,
             "type": "RecurringCharge",
             "sku": "bZ3oRYFwBNcx7sNtZGCZQBGS1XY",
             "description": "Test Product Description",
             "quantity": 1,
             "unit_amount": 10,
             "tax_classification": "TaxExempt",
             "item_added": "2020-06-16T13:56:35-07:00",
             "item_removed": null
          }
       ],
       "total_count": 3
    },
    "invoice_tax_items": {
       "object": "List",
       "data": [
          {
             "object": "InvoiceItem",
             "index_number": 3,
             "type": "Tax",
             "sku": "VIN_SALES_TAX",
             "description": "Sales Tax Total",
             "quantity": 1,
             "unit_amount": 0,
             "tax_classification": "TaxExempt",
             "item_added": "2020-06-16T13:56:35-07:00",
             "item_removed": null
          }
       ],
       "total_count": 1
    },
    "invoice_payments": {
       "object": "List",
       "data": [
          {...transaction...}
       ],
       "total_count": 1
    },
    "account": {
       "object": "Account",
       "id": "cust_1234",
       "vid": "11b9b85935256c8b0a1351298ec9c7b88047061a"
    },
    "subscription": {
       "object": "Subscription",
       "id": "sub_1234",
       "vid": "566baf52d8add85a7c796e16a7b542fc3eecf583"
    },
    "billing_sequence": 5,
    "invoice_terms": null,
    "affiliate": null,
    "sub_affiliate": null,
    "metadata": {
       "from_subscription": "1084518"
    }
 }

Fetch a specific invoice

Retrieves a specific Invoice.

HTTP Request

GET https://api.vindicia.com/invoices/:invoice

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Invoice object.

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/invoices/sub_1234-00000004"

List invoices

Retrieves a list of Invoices (all or filtered). This can be used to get a cross-account list of invoices, or for a given Subscription using the “subscription” query parameter (see example).

HTTP Request

GET https://api.vindicia.com/invoices

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
order asc Order the List in Ascending asc or Descending desc order.
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
account none Limit the invoice list to a specified account id or vid. No
subscription none Limit the invoice list to a specified subscription id or vid. No
status none Limit the invoice list to a specified status. No
due_date none Limit the invoice list to invoices due on a specified date. No
invoice_date none Limit the invoice list to invoices with a specified invoice_date No
due_date_after none Limit the invoice list to invoices due after a specified datetime. No
due_date_before none Limit the invoice list to invoices due before a specified datetime. No
invoice_date_after none Limit the invoice list to invoices with an invoice date after a specified datetime. No
invoice_date_before none Limit the invoice list to invoices with an invoice date before a specified datetime. No

Accepts

None.

Returns

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

A list of Invoice objects matching the query. Also:

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/invoices?subscription=sub_1234&limit=10"

The above command returns JSON structured like this:

{
  "object": "List",
  "data": [
     {
        "object": "Invoice",
        "id": "sub_1234-00000000",
        "invoice_date": "2020-06-16T00:00:00-07:00",
        "due_date": "2020-06-16T00:00:00-07:00",
        "billing_service_period_start": "2020-06-16T00:00:00-07:00",
        "billing_service_period_end": "2020-07-15T23:59:59-07:00",
        "status": "Paid",
        "invoice_currency": "USD",
        "original_invoice_amount": 15,
        "invoice_balance": 0,
        "gross_charges_total": 15,
        "tax_charges_total": 0,
        "credit_total": 0,
        "payments_received_total": 15,
        "invoice_line_items": {...},
        "invoice_tax_items": {...},
        "invoice_payments": {...},
        "account": {...},
        "subscription": {...},
        "billing_sequence": 0,
        "invoice_terms": null,
        "affiliate": null,
        "sub_affiliate": null,
        "metadata": {...}
      },
      {
        "object": "Invoice",
        "id": "sub_1234-00000001",
        "invoice_date": "2020-07-16T00:00:00-07:00",
        "due_date": "2020-07-16T00:00:00-07:00",
        "billing_service_period_start": "2020-07-16T00:00:00-07:00",
        "billing_service_period_end": "2020-08-15T23:59:59-07:00",
        "status": "Due",
        "invoice_currency": "USD",
        "original_invoice_amount": 15,
        "invoice_balance": 15,
        "gross_charges_total": 15,
        "tax_charges_total": 0,
        "credit_total": 0,
        "payments_received_total": 0,
        "invoice_line_items": {...},
        "invoice_tax_items": {...},
        "account": {...},
        "subscription": {...},
        "billing_sequence": 1,
        "invoice_terms": null,
        "affiliate": null,
        "sub_affiliate": null,
        "metadata": {...}
      }
  ],
  "total_count": 2,
  "url": "/invoices?sub_1234",
  "next": "/invoices?subscription=sub_1234&starting_after=sub_1234-00000001",
  "previous": "/invoices?subscription=sub_1234&starting_before=sub_1234-00000000"
}

Write Off an invoice

Writes off a specific Invoice.

HTTP Request

GET https://api.vindicia.com/invoices/:invoice/actions/write_off

Route (URL) Parameters

Parameter Default Description Required
invoice n/a The id or vid of the Invoice to write off Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Invoice object.

Payment Methods

The Payment Method object represents an “on-file” payment instrument, e.g. credit card, PayPal, ECP, direct debit. The API allows you to create, fetch, and update Payment Methods. You can retrieve individual Payment Methods, as well as a list of all.

Supported Operations

GET | list (all; filtered), fetch (individual PaymentMethod)

POST| create (individual PaymentMethod), update (individual PaymentMethod)

The Payment Method object

Attributes

Name Type Description
object string Value is “PaymentMethod”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The date/time the object was created.
type enum Values can be Amazon,ApplePay,Boleto,CarrierBilling,CreditCard,DirectDebit,ECP,HostedPage,MerchantAcceptedPayment,PayPal,Skrill,Token
credit_card Credit Card Credit Card details.
ecp ECP ACH (aka ECP) details.
direct_debit Direct Debit Direct Debit details (vary by country/system)
paypal PayPal PayPal Express Checkout account details.
amazon Amazon Amazon Payments account details.
skrill Skrill Skrill digital wallet details.
boleto Boleto Boleto Bancario details.
hosted_page Hosted Page Externally Hosted Payment Page details.
token Token Token (payment method) details.
merchant_accepted_payment Merchant Accepted Payment Pay By Invoice details.
carrier_billing Carrier Billing Telco carrier billing details.
external_billing External Billing External Billing details.
apple_pay ApplePay Apple Pay details.
google_pay GooglePay Google Pay details.
military_star Military Star Military Star details.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
account_holder string Name of the account holder.
billing_address Address The official billing address associated with this payment method.
customer_specified_type string Optional merchant- or customer-specified type description.
customer_description string Optional merchant- or customer-specified card (method) description.
currency string An ISO 4217 Currency Code.
primary boolean Primary/default payment method for the account.
active boolean Active and available for use.
validation_status Transaction Status Transaction status of Transaction used to validate this payment method.
policy hash The policy object governing Payment Method behavior.

Example Object

{
    "object": "PaymentMethod",
    "id": "paym_1235",
    "vid": "97b0915f6e65614462fdee6ffbc8385f3308188f",
    "created": "2020-05-24T17:41:29-07:00",
    "type": "CreditCard",
    "credit_card": {
        "object": "CreditCard",
        "vid": "0f0c86caef22b95b80f430cd4f8fc2df52a03f97",
        "account": "422277XXXXXX9507",
        "bin": "422277",
        "last_digits": "9507",
        "account_length": 16,
        "expiration_date": "201805"
        },
    "account_holder": "Sally W. Brown",
    "billing_address": {
        "object": "Address",
        "vid": "2eec375cdf13cd4998346796995099146448a651",
        "name": "Sally Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
        },
    "customer_specified_type": "VI",
    "primary": true,
    "active": true
}

Create a Payment Method

Creates a new Payment Method object without association to a specific Account or Subscription or Transaction.

Generally the same behavior will be experienced when creating a PaymentMethod as part of creating or updating a containing object (Account, Subscription, Transaction).

HTTP Request

POST https://api.vindicia.com/payment_methods

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Payment Method object with Payment Method Type sub-object detail.

Returns

JSON - A full Payment Method object with Payment Method Type sub-object detail.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
    "object": "PaymentMethod",
    "id": "paym_1234",
    "type": "CreditCard",

    "credit_card": {
        "object": "CreditCard",
        "account": "341111111111111",
        "expiration_date": "202605"
        },

    "account_holder": "Charles X. Brown",
    "billing_address": {
        "object": "Address",
        "name": "Charlie Brown",
        "line1": "123 Main Street",
        "city": "San Francisco",
        "district": "CA",
        "postal_code": "94105",
        "country": "US",
        "phone": "415-555-3212"
        },

    "customer_specified_type": "Personal Amex",
    "primary": true,
    "policy": {
        "min_chargeback_probability": 100,
        "validate": 1
    }
}' "https://api.prodtest.vindicia.com/payment_methods"

Fetch a specific payment method

Retrieves a specific Payment Method.

HTTP Request

GET https://api.vindicia.com/payment_methods/:payment_method

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Payment Method object with Payment Method Type subobject detail.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/payment_methods/paym_1235"

Update a payment method

Update an existing Payment Method.

HTTP Request

POST https://api.vindicia.com/payment_methods/:payment_method

Route (URL) Parameters

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

Query Parameters

None.

Accepts

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

Returns

JSON - A full Payment Method object with Payment Method type subobject detail.

List all payment methods

Retrieves Payment Methods filtered by Account.

HTTP Request

GET https://api.vindicia.com/payment_methods?account=cust_1234

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
account none Specify a particular account by id or vid Yes
include_children false include child account Payment Methods in results No

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Payment Methods, starting after the specified starting_after Payment Method (or ending before the specified ending_before Payment Method). Each entry in the array is a full Payment Method object. If no more Payment Methods are available, the resulting array will be empty.

A list of Payment Methods objects matching the query. Also:

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/payment_methods?limit=1&account=cust_1235"

The above command returns JSON structured like this:

{
   "object":"List",
   "data":[
      {
         "object":"PaymentMethod",
         "id":"paym_1235",
         "vid":"97b0915f6e65614462fdee6ffbc8385f3308188f",
         "created":"2020-05-24T17:41:29-07:00",
         "type":"CreditCard",
         "credit_card":{
            "object":"CreditCard",
            "vid":"0f0c86caef22b95b80f430cd4f8fc2df52a03f97",
            "account":"422277XXXXXX9507",
            "bin":"422277",
            "last_digits":"9507",
            "account_length":16,
            "expiration_date":"202605"
         },
         "account_holder":"Sally W. Brown",
         "billing_address":{
            "object":"Address",
            "vid":"2eec375cdf13cd4998346796995099146448a651",
            "name":"Sally Brown",
            "line1":"123 Main Street",
            "city":"San Francisco",
            "district":"CA",
            "postal_code":"94105",
            "country":"US",
            "phone":"415-555-3212"
         },
         "customer_specified_type":"VI",
         "primary":true,
         "active":true
      }
   ],
   "total_count":1,
   "url":"/payment_methods?limit=1&account=cust_1235",
   "next":"/payment_methods?limit=1&account=cust_1235&starting_after=paym_1235",
   "previous":"/payment_methods?limit=1&account=cust_1235&ending_before=paym_1235"
}

Products

The Product object represents a unique merchant product, with its own pricing, description and entitlement assignments. The API allows you to create, fetch, and update products. You can retrieve individual Product objects, as well as a list of all.

Supported Operations

GET | list (all), fetch (individual Product)

POST| create (individual Product), update (individual Product)

The Product object

Attributes

Name Type Description
object string Value is “Product”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The date/time the object was created.
descriptions Product Description[] Language-specific product/service descriptions
status enum Merchants may define whether they want to declare a product as available to offer. Value can be Active,Suspended
tax_classification string The tax classification or code for this product.
br_tax_category enum Can be: Goods or Services
default_billing_plan Billing Plan Billing Plan to assign to subscriptions where this product is the “primary” and no plan has set.
default_rate_plan Rate Plan The Rate Plan to assign to subscription items assigned to this product, where using rated pricing.
end_of_life datetime The date/time after which this product should be treated as out-of-service.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
entitlements Entitlement[] Entitlements granted by active subscriptions using this product on one or more subscription items.
inherited_entitlements Entitlement[] If a Product has other products bundled with it, the Entitlements for the Products in the bundle will be returned
billing_descriptor string Optional “soft descriptor” to send to the payment processor for transactions associated with a subscription using this product.
credit_granted Credit Credits to be granted upon purchase of this product.
prices Product Price[] Default (i.e. “List”) prices for the product; one price per currency code. Prices can be overridden at purchase or with modification.
bundled_products Product[] Other Products considered “bundled” under this one; purchase of this product’s SKU under a single price, grants the entitlements associated with it and with all bundled products (as of the time of creation).

Example Object

{
   "object":"Product",
   "id":"prod_1234",
   "vid":"190828347a650eeca011ac8a6be550416d4cf9a0",
   "created":"2020-05-15T23:45:06-07:00",
   "descriptions":{
      "object":"List",
      "data":[
         {
            "object":"ProductDescription",
            "language":"EN",
            "description":"prod_1234"
         }
      ],
      "total_count":1
   },
   "status":"Active",
   "tax_classification":"DownloadableElectronicData",
   "default_billing_plan":{...},
   "metadata":{
      "COA_CODE":"GNGX102"
   },
   "entitlements":{...},
   "credit_granted":{...},
   "prices":{
      "object":"List",
      "data":[
         {
            "object":"ProductPrice",
            "amount":2,
            "currency":"USD"
         }
      ],
      "total_count":1
   }
}

Create a Product

Creates a new Product object.

HTTP Request

POST https://api.vindicia.com/products

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Product object.

Returns

JSON - A full Product object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d ' {
    "object": "Product",
    "id": "prod_2234",
    "status": "Active",
    "tax_classification": "TaxExempt",
    "prices": [
        {
        "object": "ProductPrice",
        "amount": 2.00,
        "currency": "USD"
        }
    ]
}' "https://api.prodtest.vindicia.com/products"

Fetch a specific product

Retrieves a specific Product.

HTTP Request

GET https://api.vindicia.com/products/:product

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Product object.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/products/prod_1234"

Update a product

Update an existing product.

HTTP Request

POST https://api.vindicia.com/products/:product

Route (URL) Parameters

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

Query Parameters

None.

Accepts

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

Returns

JSON - A full Product object.

List all products

Retrieves all Product objects.

HTTP Request

GET https://api.vindicia.com/products

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
entitlement none Filters list for Products by Entitlement id No
status none Filters list for Products in a given status No
account none Filters list of Products by Account id or vid that have Purchased that Product No
include_children false If filtering by Account this also returns Children Accounts No

Accepts

None.

Returns

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

A list of Product objects matching the query. Also:

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \  
"https://api.prodtest.vindicia.com/products?limit=3&starting_after=prod_1234"

The above command returns JSON structured like this:

{
   "object":"List",
   "data":[
      {
         "object":"Product",
         "id":"prod_1234",
         "vid":"acaff38d462f9430d5cbcbafa575771fc679b9de",
         "name":"Charlie Brown",
         "shipping_address":{
            "line1":"123 Main St.",
            "city":"Jamestown",
            "district":"NY",
            "postal_code":"12345",
            "country":"US"
         },
         "email":"charlie.brown@peanuts.com",
         "email_type":"html",
         "language":"en-US",
         "currency":"USD",
         "notify_before_billing":true,
         "metadata":{
            "favorite activity":"flying kites",
            "favorite dog":"Snoopy"
         },
         "url":"/products/prod_1234"
      }
   ],
   "count":4,
   "next":"/products?starting_after=prod_1234&limit=1",
   "url":"/products",
   "filter":"limit=1"
}

Rate Plans

Rate Plans represents a pre-defined rating schedule - tier-based pricing for rated products (e.g. usage). Both pre-paid (aka License-based) and post-paid (metered, aka usage-based) services use pre-defined tiers to rate recorded events. Rate Plans support flat and per-unit pricing, volume discounts, standard consumption-based prices, included units with overage, and maximum/minimum charge limits.

Supported Operations

GET | list (all), fetch (individual Rate Plan)

POST| create (individual Rate Plan), update (individual Rate Plan)

The Rate Plan object

Attributes

Name Type Description
object string Value is “RatePlan”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The date/time the object was created.
description string Optional description of the rated service offering.
multiply_rated_units_by enum Tier pricing rule. EachRespective charges units “in” that tier at its price; HighestApplicable is volume pricing, charging at the peak unit level’s tier for all units. Values can be EachRespectiveTier,HighestApplicableTier
rated_unit Rated Unit Defined rating unit of measure.
tier Rate Plan Tier[] Successive pricing tiers based on unit “from/to” limits
rounding_decimals integer Number of digits for rounding; Excel’s ROUND function: 0 = nearest integer, 2 = 2 decimal places, -2 means = nearest hundred, etc.
included_units decimal Number of units included for free; tier 1 starts after included units have been recorded.
minimum_fee Rate Plan Price[] Minimum charge per billing period (one price per currency)
maximum_fee Rate Plan Price[] Maximum charge per billing period (one price per currency)
rate_plan_model enum Determines pre-paid (licenses or seats billed in advance) or post-paid (usage recorded throughout the period and billed at period end. Values can be LicenseBased,UsageBased
status enum Merchants may define whether they want to declare a plan as available to offer. Values can be Active,Suspended
has_event_recorded boolean Read-only field that tells whether this RatePlan has had any events recorded on it or not.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Example Object

{
   "object":"RatePlan",
   "id":"rateplan_1234",
   "vid":"90f519aca94d5ea79dbc6512fade7a7f09a8e214",
   "description":"Combo:  Each, Usage, Flat1",
   "multiply_rated_units_by":"EachRespectiveTier",
   "rated_unit":{
      "object":"RatedUnit",
      "name_singular":"License",
      "name_plural":"Licenses"
   },
   "tier":[
      {
         "object":"RatePlanTier",
         "name":"Tier 1",
         "rate_price":[
            {
               "object":"RatePlanPrice",
               "amount":11,
               "currency":"USD"
            }
         ],
         "charge_customer":"FlatFee",
         "begins_at_level":1
      },
      {
         "object":"RatePlanTier",
         "name":"Tier 2",
         "rate_price":[
            {
               "object":"RatePlanPrice",
               "amount":5,
               "currency":"USD"
            }
         ],
         "charge_customer":"FlatFee",
         "begins_at_level":11
      }
   ],
   "rounding_decimals":0,
   "included_units":0,
   "minimum_fee":[
      {
         "object":"RatePlanPrice",
         "amount":0,
         "currency":"USD"
      }
   ],
   "maximum_fee":[],
   "rate_plan_model":"UsageBased",
   "status":"Active",
   "has_event_recorded":true
}

Create a new Rate Plan.

Creates a new RatePlan object.

HTTP Request

POST https://api.vindicia.com/rateplans

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Rate Plan object.

Returns

JSON - A full Rate Plan object.

Fetch a specific Rate Plan

Retrieves a specific Rate Plan.

HTTP Request

GET https://api.vindicia.com/rateplans/:rateplan

Route (URL) Parameters

Parameter Default Description Required
RatePlan n/a The id or the vid of the Rate Plan to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Rate Plan object.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/rate_plans/rateplan_1234"

Update an existing Rate Plan

Update an existing RatePlan.

HTTP Request

POST https://api.vindicia.com/rateplans/:rate_plan

Route (URL) Parameters

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

Query Parameters

None.

Accepts

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

Returns

JSON - A full Rate Plan object.

List all Rate Plans

Retrieves all Rate Plans.

HTTP Request

GET https://api.vindicia.com/rateplans

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

Accepts

None.

Returns

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

A list of Rate Plan objects matching the query. Also:

Refunds

The Refund object provides a way to reverse a charge, refunding money to the customer. You can create, and retrieve individual Refunds; as well as list all existing Refunds. Refunds require a transaction – a refund can only be executed against an existing, successfully captured transaction. Refunds can be issued for any valid amount (in the currency of the original transaction) up to the as-yet un-refunded balance of the original transaction. You can issue any number of refunds on a given transaction (until it has been fully refunded).

Supported Operations

GET | list (all; filtered), fetch (individual Refund)

POST| create (individual Refund)

The Refund object

Attributes

Name Type Description
object string Value is “Refund”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid. Excepting externally “reported” refunds, this is ready-only, this field will be assigned by Subscribe.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The date/time at which the refund was requested.
transaction Transaction The transaction to refund.
refund_items Refund Item[] For item-level refunds, specifies the transaction items to refund with details.
refund_distribution_strategy enum Defines strategy for distributing refund amount across the original TransactionItems. Can be None, SpecifiedItems, RemainingBalance. Default: None
amount decimal Amount of the refund. Must be positive (non-zero) and less than or equal to the as-yet-un-refunded balance of the specified transaction. Ignored if refundItems are specified.
amount_includes_tax boolean whether the amount is tax-inclusive or -exclusive
currency string ISO 4217 Currency Code of this transaction; defaults to USD.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
reference_string string Read-only. Information provided by payment processor.
note string Free-form merchant-specified notes about refund.
token_action enum Action to take with any Tokens paid on transaction. Default: None. Values can be CancelNegativeBalance,CancelZeroBalance,None
credit Credit Read-only. Credits reversed by refund.
status enum Processing status of refund. Values can be Complete,Failed,Processing,Reported

Example Object

{
    "object": "Refund",
    "id": "FLX200001561",
    "vid": "64a6bad051bdf489c7cf90ed52fca549c0048d3d",
    "created": "2020-05-24T17:50:47-07:00",
    "transaction": {...},
    "refund_distribution_strategy": "None",
    "amount": 14.99,
    "amount_includes_tax": false,
    "currency": "USD",
    "metadata": {...},
    "note": "Refund 14.99USD",
    "token_action": "None",
    "status": "Complete"
}

Create a refund

Creates a new Refund against an existing transaction.

HTTP Request

POST https://api.vindicia.com/transactions/:transaction/refunds

Route (URL) Parameters

Parameter Default Description Required
transaction n/a The id or the vid of the Transaction Yes

Query Parameters

None.

Accepts

JSON - A full Refund object.

Returns

JSON - A full Refund object.

Example Request

 curl -X POST \
 -u acaff38d462f9430d5cbcbaf:a575771fc679b9de \  
 -d '{
    "object": "Refund",
    "id": "FLX200001541REF",
    "refund_distribution_strategy": "None",
    "amount": 14.99,
    "amount_includes_tax": false,
    "currency": "USD",
    "note": "Refund REQUEST VIA WEB FLX200001541REF",
    "token_action": "None"
}' "https://api.prodtest.vindicia.com/transactions/FLX200001541/refunds"

Fetch a specific refund

Retrieves a specific Refund.

HTTP Request

GET https://api.vindicia.com/transactions/:transaction/refunds/:refund

Route (URL) Parameters

Parameter Default Description Required
transaction n/a The id or the vid of the Transaction to retrieve Yes
refund n/a The id or the vid of the Refund to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Refund object.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \  
"https://api.prodtest.vindicia.com/transactions/tx_1234/refunds/refund_1234"

Update a specific refund

Updates a specific Refund.

HTTP Request

POST https://api.vindicia.com/transactions/:transaction/refunds/:refund

Route (URL) Parameters

Parameter Default Description Required
transaction n/a The id or the vid of the Transaction to retrieve Yes
refund n/a The id or the vid of the Refund to retrieve Yes

Query Parameters

None.

Accepts

Updated Refund object.

Returns

JSON - A full Refund object.

List all refunds (for a transaction)

Retrieves all Refunds issued against a specified transaction.

HTTP Request

GET https://api.vindicia.com/transactions/:transaction/refunds

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

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

A list of Refund objects matching the query. Also:

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \  
"https://api.prodtest.vindicia.com/transactions/FLX200001501/refunds?limit=3"

The above command returns JSON structured like this:

{
   "object":"List",
   "data":[
      {
         "object":"Refund",
         "id":"FLX200001561",
         "vid":"64a6bad051bdf489c7cf90ed52fca549c0048d3d",
         "created":"2020-05-24T17:50:47-07:00",
         "transaction":{...},
         "refund_distribution_strategy":"None",
         "amount":14.99,
         "amount_includes_tax":false,
         "currency":"USD",
         "metadata":{...},
         "note":"Refund 14.99USD",
         "token_action":"None",
         "status":"Complete"
      }
   ],
   "total_count":1,
   "url":"/transactions/FLX200001501/refunds?limit=3",
   "next":"/transactions/FLX200001501/refunds?limit=3&starting_after=FLX200001561",
   "previous":"/transactions/FLX200001501/refunds?limit=3&ending_before=FLX200001561"
}

Season Sets

A Season Set object allows you to create groups of time intervals, which may be used with Billing Plans to define both Billing Cycles, and Entitlement grants.

Supported Operations

GET | list (all; filtered), fetch (individual SeasonSet)

POST| create (individual SeasonSet), update (individual SeasonSet)

The Season Set object

The Season Set object defines an array of seasons, with an identifier.

Attributes

Name Type Description
object string Value is “SeasonSet”
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 Subscribe.
created datetime The date and time the plan was created.
seasons Season[] An array of Seasons that make up the Season Set.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Create a Season Set

Creates a new Season Set Object.

HTTP Request

POST https://api.vindicia.com/season_sets

Route (URL) Parameters

None.

Query Parameters

None.

Accepts

JSON - A full Season Set object.

Returns

JSON - A full Season Set object.

Fetch a specific Season Set

Retrieves a specific Season Set.

HTTP Request

GET https://api.vindicia.com/season_sets/:season_set

Route (URL) Parameters

Parameter Default Description Required
seasonSet n/a The id or the vid of the Season Set to retrieve Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Season Set object.

Update a Season Set

Update a specific SeasonSet.

HTTP Request

POST https://api.vindicia.com/season_sets/:season_set

Route (URL) Parameters

Parameter Default Description Required
seasonSet n/a The id or the vid of the Season Set to update Yes

Query Parameters

None.

Accepts

JSON - A full Season Set object.

Returns

JSON - A full Season Set object.

List all Season Sets

Retrieves all Season Sets.

HTTP Request

GET https://api.vindicia.com/season_sets

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
in_season datetime
off_season datetime

Accepts

None.

Returns

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

A list of Season Sets objects matching the query. Also:

List Seasons

Retrieves all seasons for a specified Season Set.

HTTP Request

GET https://api.vindicia.com/season_sets/:season_set/seasons

Route (URL) Parameters

Parameter Default Description Required
seasonSet n/a The id or the vid of the Season Set Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Season. Each entry in the array is a full Season object. If no more Seasons are available, the resulting array will be empty. This request should never throw an error.

A list of Season objects matching the query. Also:

Subscriptions

Subscriptions allow you to bill an Account over time and/or on a recurring basis. A subscription ties an Account to a particular billing plan and set of purchased products (subscription items) you’ve created. The API allows you to create, update and amend/modify your subscriptions. You can retrieve individual Subscriptions as well as a list of all your Subscriptions.

Supported Operations

GET | list (all; filtered), fetch (individual Subscription)

POST| create (individual Subscription), update (individual Subscription), change billing day (individual Subscription), cancel (individual Subscription), pause (individual Subscription), resume (individual Subscription)

The Subscription Object

Attributes

Name Type Description
object string Value is “Subscription”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid. Using a unique custom identifier is strongly encouraged.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The date/time at which the subscription was requested.
account Account The account receiving the subscription.
billing_plan Billing Plan The billing plan assigned to this subscription. Dictates billing schedule.
payment_method Payment Method The payment method assigned to pay for this subscription.
currency string An ISO 4217 Currency Code. A subscription’s charges must be in a single currency.
description string An optional customer-facing identifier or descriptive name for the subscription
status enum The status of the subscription from a service and entitlement perspective. Values can be Pending Activation,Active,Pending Cancel, Cancelled, Expired, Processing, Deleted,Dryrun, Unknown, Upgraded, Legacy Suspended,Pending Pause, Paused, Pending Resume
billing_state enum The financial state of the subscription. Values can be Billing Completed, Failed To Collect, Free Period, Free/Trial, Good Standing, Grace Period, In Retry, Legacy Unknown BillingState, Overdue, Pending Acceptance, Terminated, Unbilled, Unknown, Unusable PaymentMethod, Paused, Pending Resume
starts datetime The date/time the subscription starts service.
ends datetime The date/time the subscription ends service.
entitled_through datetime The date/time to which the subscription will entitle service if no further payments are made – a “paid thru” date based on billing schedule and grace period.
items Subscription Item[] The product-based line items for the subscription.
source_ip string Optional source IP Address at sign-up.
billing_descriptor string Optional “soft descriptor” to send to the payment processor for transactions from this subscription.
billing_day integer The day of the month on which the subscription is (typically) billed. Often called an “anniversary date.”
minimum_commitment integer Number of billing cycles customer is obligated to maintain the subscription. Cancelling before this time requires merchant to “force” cancellation.
affiliate string Affiliate or channel identifier, if any, under which the subscription was submitted.
sub_affiliate string A more granular or subordinate affiliate identifier.
notify_on_transition boolean Indicates whether to send an expiration or trial-end email notification using the days-in-advance configuration in the Billing Plan.
most_recent_billing Transaction The initial Transaction for new Subscriptions.
most_recent_refunds Refund[] A list of any refunds associated with the Transaction in most_recent_billing.
next_billing Transaction The next scheduled billing transaction expected for this subscription.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information. Subscription metadata will be inherited by resulting transactions.
credit Credit Credit balance of the subscription.
statement_format enum Instructions for if/how to include the invoice statement for this subscription. Values can be Attachment,DoNotSend,Inline
invoice_terms integer Net Terms (in days); after this many days from a billing, the invoice will be considered delinquent.
statement_offset integer Days before scheduled billing to deliver the statement.
statement_template string Template to use for statement generation.
billing_plan_campaign_code string The Campaign code redeemed on this Subscription against the price of the Billing Plan. To apply a Campaign, use this field to pass in a valid Coupon or Promotion code. Note: This data member will not be returned.
billing_plan_campaign_id string The unique identifier for a Campaign applied to this Subscription’s BillingPlan. This is a read-only field returned by Subscribe for informational purposes. Values sent in with a SOAP call will be ignored. Read only.
unknown_starts boolean used to create a Subscription Pending Activation.
balance decimal
mandate Mandate Direct Debit mandate on file for this subscription, if any.
cancel_reason Cancel Reason Code for the reason a subscription was cancelled. Codes must be pre-defined by merchants or use the pre-built codes available.
policy hash The policy object governing Subscription behavior.
policy: ignore_cvn_policy boolean Indicates whether to evaluate any custom or default CVN (card security code) policy.
policy: ignore_avs_policy boolean Indicates whether to evaluate any custom or default AVS (card Address Verification Service) policy.
policy: min_chargeback_probability integer If Chargeback Probability from risk scoring is greater than this, the transaction will fail. Default is 100.
policy: immediate_auth_failure_policy enum How to respond to Authorization failure while processing first Transaction for an Subscription. Values can be doNotSaveAutoBill,putAutoBillInRetryCycle,putAutoBillInRetryCycleIfPaymentMethodIsValid. Defaults to doNotSaveAutoBill if unspecified.
policy: validate_for_future_payment boolean Validate the payment method for future payments if initial Transaction is not being created/Authorized. Subscription will not be saved if validation is requested and fails.

Example Object

{
    "object": "Subscription",
    "id": "sub_1234",
    "vid": "796db5f7f7a1dea312f6c7e1393aebec1f1ecf1b",
    "account": {...},
    "billing_plan": {...},
    "payment_method": {...},
    "currency": "USD",
    "description": "Subscription_1234",
    "status": "Active",
    "billing_state": "Good Standing",
    "starts": "2020-05-27T05:52:02-07:00",
    "items": {
        "object": "List",
        "data": [
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.1",
                "index": 0,
                "product": {...},
                "quantity": 1,
                "created": "2020-05-27T05:52:02-07:00",
                "starts": "2020-05-27T00:00:00-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.2",
                "index": 1,
                "product": {...},
                "quantity": 1,
                "created": "2020-05-27T05:52:02-07:00",
                "starts": "2020-05-27T00:00:00-07:00"
            }
        ],
        "total_count": 2
    },
    "minimum_commitment": 0,
    "notify_on_transition": false,
    "next_billing": {...}
}

Create a subscription

Creates a new Subscription object.

HTTP Request

POST https://api.vindicia.com/subscriptions

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
dryrun false Indicates whether to commit changes or return results without execution No

Accepts

JSON - A full Subscription object.

Returns

JSON - A full Subscription object.

Example Request

 curl -X POST \
 -u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
 -d ' {
    "object": "Subscription",
    "id": "sub_1234",
    "account": {
       "object": "Account",
       "id": "cust_1234"
    },
    "billing_plan": {
       "object": "BillingPlan",
       "id": "plan_1234"
    },
    "payment_method": {
       "object": "PaymentMethod",
       "id": "paym_1234"
    },
    "currency": "USD",
    "description": "Subscription_1234",
    "starts": "2020-05-27T05:52:02-07:00",
    "items": [
       {
          "object": "SubscriptionItem",
          "id": "sub_1234.1",
          "product": {
             "object": "Product",
             "id": "prod_1234"
          }
       },
       {
          "object": "SubscriptionItem",
          "id": "sub_1234.2",
          "product": {
             "object": "Product",
             "id": "prod_1235"
          }
       }
    ],
    "minimum_commitment": 0,
    "policy": {
       "ignore_cvn_policy": 1,
       "ignore_avs_policy": 1,
       "min_chargeback_probability": 99,
       "immediate_auth_failure_policy": "doNotSaveAutoBill",
       "validate_for_future_payment": 0
    }
 }' "https://api.prodtest.vindicia.com/subscriptions"

Fetch a specific subscription

Retrieves a specific Subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Subscription object.

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/subscriptions/sub_1234"

List (all) Subscriptions

Retrieves a list of Subscriptions. This can be used to get a cross-account list of subscriptions, or for a given account using the “account” query parameter (see example).

HTTP Request

GET https://api.vindicia.com/subscriptions

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
account none Limit the subscription list to a specified account id or vid - if specified, all Subscriptions associated with that Account. No
include_children false Indicates whether or not to return any existing child accounts’ subscriptions for a given returned Subscription/account combination.
email none Limit the Subscription list to those associated with a specific email No
primary_product none …. No
product none Limit the Subscription list to those that have a specified product id or vid as a SubscriptionItem No

Accepts

None.

Returns

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

A list of Subscription objects matching the query. Also:

Example Request

curl -X GET  \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/subscriptions?limit=3&account=cust_2234"

The above command returns JSON structured like this:

{
    "object": "List",
    "data": [
        {
            "object": "Subscription",
            "id": "sub_1234",
            "vid": "400dc2e6524e754914d8bd40e495f05f53939ddc",
            "created": "2020-05-27T14:54:45-07:00",
            "account": {...},
            "billing_plan": {...},
            "payment_method": {...},
            "currency": "USD",
            "description": "Subscription_1234",
            "status": "Active",
            "billing_state": "Good Standing",
            "starts": "2020-05-27T05:52:02-07:00",
            "entitled_through": "2020-07-05T00:00:00-07:00",
            "items": {
                "object": "List",
                "data": [
                    {...Subscription Item...},
                    {...Subscription Item...}
                ],
                "total_count": 2
            },
            "billing_day": 27,
            "minimum_commitment": 0,
            "notify_on_transition": false,
            "next_billing": {...}
        },
        {...Subscription...}
    ],
    "total_count": 2,
    "url": "/subscriptions?limit=3&account=cust_2234",
    "next": "/subscriptions?limit=3&account=cust_2234&starting_after=sub_1234x",
    "previous": "/subscriptions?limit=3&account=cust_2234&ending_before=sub_1234"
}

Cancel a subscription

Cancel a subscription, with options to select immediate disentitlement versus registering the cancel now to take affect at the end of the current period; to select whether any pre-paid services should get a prorated refund; and to select whether or not an existing minimum commitment should be honored. The reason for the cancellation can also be tracked using Cancel Reason codes (which can use pre-defined codes or codes you’ve designed yourself in advance).

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/actions/cancel

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to cancel Yes

Query Parameters

Parameter Default Description Required
disentitle false Indicates whether or not to dis-entitle immediately or leave service in effect until the end of the current billing period. No
force false Indicates whether to ignore unsatisfied minimum commitments No
settle false Indicates whether to issue a prorated refund for any pre-paid unconsumed services and to rate unbilled usage. No
send_cancellation_notice true Indicates whether to send a special cancellation notice to the customer No
reason_code n/a The predefined Cancel Reason code for cancelling this subscription. No
dryrun false If true, all computations will be done, but no result from this operation will be recorded in Vindicia’s database. If it did not exist before, it won’t exist afterward; if it did exist before, it won’t change. This is useful for computing the cost of an Subscription without committing to the change. No
cancel_policy WAIVE_CANCEL_FEE Policy for handling the cancel fee. Can be WAIVE_CANCEL_FEE, PRORATE_CANCEL_FEE, FULL_CANCEL_FEE

Accepts

None.

Returns

JSON - A full Subscription object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/subscriptions/sub_1234x/actions/cancel?reason_code=101&settle=false&disentitle=false"

Change the Subscription’s billing day

Change the standard billing day of the month assigned to a subscription. Commonly referred to as the “anniversary day” or “billing day” - this value is an integer between 1 and 31 representing which day of the month is used for any recurring billing based on some number of months in term. While not meaningful for subscriptions whose plan includes daily, weekly, or mixed term period lengths, it is a useful predictor often shared with customers for monthly, quarterly, and annual plans (e.g. billed on the 1st of every month; billed on the 1st of January every year, etc.)

This operation supports changing the billing day temporarily or permanently. Note: moving the billing day of an active subscription forward can have the effect of granting extra time as proration is not automatically added when the pre-paid billing period is extended.

to_date to_day and by_days are mutually exclusive methods for moving a next billing day in conjunction with the option to make the change permanent (perm).

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/billing_day_changes

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription requiring a billing day change Yes

Query Parameters

Parameter Default Description Required
to_date n/a Date for the next billing (when moving the subscription to bill on a new, specific date) No
to_day n/a Integer value (1 - 31) to assign as the next “billing day” for the subscription moving the next billing to that day in the same calendar month in which it was scheduled; when used with ‘perm’ parameter this will become the new billing day permanently. No
by_days n/a Integer specify the number of days from the current next billing to delay; when used with 'perm’ parameter this will become the new billing day permanently. No
perm false Boolean: Indicates whether the change should be permanent (true) or just apply to the next billing (false).

Accepts

None.

Returns

JOSN A full Subscription object representing the resulting changes.

Modify a subscription (Update)

Update, amend, or modify a Subscription. See Vindicia Knowledge Base regarding various modify scenarios and additional approaches. REST approaches for the most common modifications are below (see “Accepts” section for this operation). * Billing Plan Change * Add or Remove a Subscription Item * Replace an existing Subscription Item with a new one

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to modify Yes

Query Parameters

Parameter Default Description Required
bill_prorated_period false Indicates whether to prorate for unused service portions. No
effective_date today Billing date at which changes take effect; today or nextBill No
new_billing_date none …. No
dry_run false Indicates whether to commit changes or return results without execution No

Accepts

JSON - This request supports the same arguments as 'create’ (a full Subscription object) excepting the behavior of the id; providing an id or vid in the URL indicates to Subscribe that this is an update, not a create – as such, id and vid cannot be updated. Certain changes will modify the subscribed service:

Returns

JSON - A full Subscription object representing the new version of the Subscription.

Example Request (multiple modifications)

Billing Plan Change, Replace an Item, Remove an Item, add an Item

curl -X POST -u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d ' {
    "object": "Subscription",
    "id": "sub_2",
    "billing_plan": {
       "object": "BillingPlan",
       "id": "plan_2234"
    },
    "items": [
       {
          "object": "SubscriptionItem",
          "id": "sub_2.1a",
          "product": {
             "object": "Product",
             "id": "prod_2234"
          },
          "replaces": "sub_2.1"
       },
       {
          "object": "SubscriptionItem",
          "replaces": "sub_2.2"
       },
       {
          "object": "SubscriptionItem",
          "id": "sub_2.4",
          "product": {
             "object": "Product",
             "id": "prod_3234"
          }
       }
    ]
 }' "https://api.prodtest.vindicia.com/subscriptions/sub_2?effective_date=today&bill_prorated_period=true&dry_run=false"

Activate a specific Subscription

Activate a specific Subscription in status Pending Activation that has a future or unknown start date.

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/actions/activate

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to activate Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Subscription object.

Pause a subscription

Pause a Subscription with immediate effect. If no other action is taken upon the Subscription, it will remain paused for 5 years and then cancel.

Only Active/Good Standing Subscriptions can be paused.

Paused Subscriptions can only be resumed or cancelled.

Entitlements granted from any Product or the Billing Plan of the Subscription are stopped on the date of the pause request.

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/actions/pause

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to pause Yes

Query Parameters

None

Accepts

None.

Returns

JSON - A full Subscription object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https:///subscriptions/#subscription/actions/pause"

Resume a subscription

Resume a Subscription with immediate effect. Only paused Subscriptions can be resumed.

The billing date will be on the next billing date after the resume date as if the Subscription was never paused. E.g., if the Subscription started on the 22 day of the month and is on a monthly billing cycle when it was paused, the Subscription will bill on the next 22 day of the current or next month after it is resumed.

Subscription.ends will be set to the next billing date plus the configured expiration offset.

Entitlements granted from any Product or the Billing Plan of the Subscription are resumed on the date of the resume request.

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/actions/resume

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to resume Yes

Accepts

None.

Returns

JSON - A full Subscription object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https:///subscriptions/#subscription/actions/resume?settle=0&dryrun=0"

Fetch Subscription Item history

Retrieves the Subscription Item history for a specified subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/subscription_item_history

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to retrieve Subscription Item history Yes

Query Parameters

None.

Accepts

None.

Returns

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

A list of Subscription objects matching the query. Also:

Fetch billing plan history

Retrieves the Billing Plan history for a specified subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/billing_plan_history

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to retrieve Billing Plan history Yes

Query Parameters

None.

Accepts

None.

Returns

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

A list of Subscription objects matching the query. Also:

Fetch Future Transactions

Retrieves the future Transactions for a specified subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/future_transactions

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription to retrieve future Transactions Yes

Query Parameters

None.

Accepts

None.

Returns

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

A list of Transaction objects matching the query. Also:

Grant or Revoke Currency Credit

Grant, Revoke, increment or decrement an Subscription Level Currency Credit.

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/currency_amount_changes

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription Yes

Query Parameters

None.

Accepts

JSON - A (new) Currency Amount sub-resource. The Currency Amount object represents the the change in the Currency Credit.

Returns

JSON - A (new) Currency Amount sub-resource.

Fetch Currency Credit Amount Change

Fetch a specific Currency Credit Amount Change to see additional details of the adjustment to the Credit.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/currency_amount_changes/:currency_amount

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the subscription Yes
currencyAmount n/a The vid of the Currency Amount that was updated

Query Parameters

None.

Accepts

None.

Returns

JSON - the specified Currency Amount sub-resource in full.

Fetch All Currency Credit Amount Changes

Fetch all Currency Credit Amount Changes for a Subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/currency_amount_changes

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the subscription Yes

Query Parameters

Parameter Type Default Description Required
limit integer 20 A limit on the number of objects to be returned, between 1 and 100. No

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Currency Amount, starting after the specified starting_after Currency Amount (or ending before the specified ending_before Currency Amount). If no more Currency Amounts are available, the resulting array will be empty. This request should never throw an error.

A list of Currency Amount objects matching the query. Also:

Grant or Revoke Token Credit

Grant, Revoke, increment or decrement an Subscription Level Token Credit.

HTTP Request

POST https://api.vindicia.com/subscriptions/:subscription/token_amount_changes

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription Yes

Query Parameters

None.

Accepts

JSON - A (new) Token Amount sub-resource.

Returns

JSON - A (new) Token Amount sub-resource.

Fetch Token Credit Amount Change

Fetch a specific Token Credit Amount Change to see additional details of the adjustment to the Credit.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/token_amount_changes/:token_amount

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the subscription Yes
tokenAmount n/a The vid of the Token Amount that was updated

Query Parameters

None.

Accepts

None.

Returns

JSON - the specified Token Amount sub-resource in full.

Fetch All Token Credit Amount Changes

Fetch all Token Credit Amount Changes for an Subscription.

HTTP Request

GET https://api.vindicia.com/subscriptions/:subscription/token_amount_changes

Route (URL) Parameters

Parameter Default Description Required
subscription n/a The id or the vid of the Subscription Yes

Query Parameters

Parameter Type Default Description Required
limit integer 20 A limit on the number of objects to be returned, between 1 and 100. No

Accepts

None.

Returns

JSON - A list array with a data property that contains an array of up to limit Token Amount, starting after the specified starting_after Token Amount (or ending before the specified ending_before Token Amount). If no more Token Amounts are available, the resulting array will be empty. This request should never throw an error.

A list of Token Amount objects matching the query. Also:

Transactions

The Transaction object provides a way to charge a customer. You can create one-time transactions, retrieve individual transactions, fetch individual transactions, and list all Transactions for a given account or subscription.

Posting with a new Transaction creates a new one-time Transaction object. If “to_be_captured” is false, the request will trigger an authorization attempt (based on the provided payment method’s authorization process). If successfully authorized, a subsequent post to the transaction’s actions/capture endpoint will capture the authorized transaction. If you post a new transaction with “to_be_captured” true, it will authorize and immediately capture the transaction if successful.

To refund transactions, use the refunds endpoint.

Supported Operations

GET | list (all; filtered), fetch (individual Transaction)

POST| create (authorize a new one-time Transaction with option for auto-capture), capture (capture), cancel (individual Transaction)

The Transaction object

Attributes

Name Type Description
object string Value is “Transaction”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid. For transactions created automatically, this field will be assigned by Subscribe.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
created datetime The time this transaction was initiated.
amount decimal The net amount of the charge presented by this transaction, as a decimal. Must be positive (zero allowed).
original_amount decimal Used with a partial payment; this read-only field reflects the original amount of the transaction, as a decimal.
currency string ISO 4217 Currency Code of this transaction
division_number string The Merchant’s division, reporting or processing group as defined with their payment processor.
previous_id string The identifier of a previous version of this transaction.
account Account The account (customer) associated with this transaction.
source_payment_method Payment Method The Payment Method (e.g., a credit card) associated with charges for this transaction. In the case of a Subscribe transaction, this payment method will be used to perform the actual billing. For ECP/ACH inbound transactions (i.e. merchant is getting paid by a customer) populate this field.
dest_payment_method Payment Method The Payment Method to receive funds from this transaction. Applies only for deposits, ECP/ACH outbound, and transfers.
ecp_transaction_type enum For ECP/ACH-specific types. Values can be All,Inbound,InboundOutbound,NA,Outbound,Transfer
status_log Transaction Status[] A log of various TransactionStatus entries associated with this transaction.
payment_processor string The payment processor used for processing this transaction.
payment_processor_transaction_id string The identifier assigned to the Transaction by the Payment Processor.
shipping_address Address The shipping address associated with this transaction, if any.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information. For transactions resulting from a subscription, the meta data is also inherited from the subscription.
items Transaction Item[] The array of Transaction Items belonging to this transaction. Items correspond to the charges, discounts, credits, and taxes.
affiliate string Merchant’s ID for the channel or affiliate associated with this transaction, if any. This is a free-form string of 128 characters or less.
sub_affiliate string Affiliate ID for a more granular channel component (see merchant_affiliate_id).
user_agent string Information on the source of the transaction, such as the Customer’s user-agent string, as presented by the browser.
preferred_notification_language string ISO language code string. Transaction value will override any language setting on the account.
source_mac_address string MAC address of the customer (primarily intended for ISP usage), may be left blank if unavailable or inappropriate.
source_ip string End-customer’s source IP associated with this transaction.
billing_descriptor string Optional “soft descriptor” to send to the payment processor for this transaction.
sales_tax_address Address An system-generated billing or shipping address actually used in calculation of sales tax.
verification_code string External verification response (e.g. Verified by Visa, MasterCard SecureCode).
subscription_sequence integer The subscription’s billing cycle for which this transaction collects funds. As a zero-based index, this indicates the renewal number.
billing_plan_sequence integer The billing cycle for which this transaction collects funds - as counted as a zero-based index from the last billing plan change for the associated subscription.
mandate Mandate The Direct Debit customer mandate associated with this transaction.
original_billing_date datetime The original scheduled billing date associated with the billing for which this transaction collects funds. For an initial attempt, this is the same as the transaction date; for a retry transaction this is the original attempt date.
billing_attempt integer The zero-based index counting the number of transaction attempts this particular transaction represents in collecting for given subscription billing cycle.
subscription Subscription The subscription for which this transaction collects funds.
score integer The chargeback and fraud risk score generated by Subscribe.
score_calculated datetime The datetime the score was calculated.
score_calculated_orig datetime The datetime the score was originally calculated.
score_codes Score Code[] The reason codes justifying the risk score.
distance_ip_ba decimal The distance from the IP Address to the Billing Address.
avs_code string AVS Code
cvn_code string CVN Code.
cvn_checked boolean Shows if the CVN was checked for this transaction.
policy hash The policy object governing Transaction behavior.
to_be_captured boolean Indicator of whether the transaction is currently pending capture.

Example Object

{
    "object": "Transaction",
    "id": "FLX200001621",
    "vid": "d137d38973040467ed65b1d7c331a22ef14605c8",
    "created": "2020-05-31T15:12:28-07:00",
    "amount": 10.98,
    "currency": "USD",
    "account": {...},
    "source_payment_method": {...},
    "status_log": {
        "object": "List",
        "data": [
            {
                "object": "TransactionStatus",
                "status": "Captured",
                "created": "2020-05-31T15:14:04-07:00",
                "payment_method_type": "CreditCard",
                "credit_card_status": {
                    "object": "TransactionStatusCreditCard",
                    "auth_code": "T00"
                }
            },
            {...},
            {...}
        ],
        "total_count": 3
    },
    "payment_processor": "Test",
    "payment_processor_transaction_id": "FLX200001621",
    "shipping_address": {...},
    "metadata": {
        "vin:RetryNumber": "0",
        "vin:recurring": "1",
        "vin:BillingCycle": "0"
    },
    "items": {
        "object": "List",
        "data": [
            {
                "object": "TransactionItem",
                "sku": "plan_1234",
                "index_number": 1,
                "item_type": "Purchase",
                "name": "Simple Monthly Billing Plan",
                "quantity": 1,
                "tax_classification": null,
                "service_period_starts": "2020-05-27T00:00:00-07:00",
                "service_period_ends": "2020-06-26T00:00:00-07:00",
                "tax_type": "Exclusive Sales",
                "total": 0
            },
            {...},
            {...},
            {...}
        ],
        "total_count": 4
    },
    "sales_tax_address": {...},
    "subscription_sequence": 1,
    "billing_plan_sequence": 1,
    "original_billing_date": "2020-05-27T00:00:00-07:00",
    "billing_attempt": 0,
    "subscription": {...},
    "to_be_captured": true
}

Create a Transaction (Authorization)

Posting with a new Transaction creates a new one-time Transaction object.
* If to_be_captured is false, the request will trigger an authorization attempt (based on the provided payment method’s authorization process).
* If you post a new transaction with to_be_captured true it will authorize and immediately capture the transaction if successful.

HTTP Request

POST https://api.vindicia.com/transactions

Route (URL) Parameters

None.

Query Parameters

Parameter Default Description Required
dryrun false Run the Transaction without sending it for processing No

Accepts

JSON - A full Transaction object.

Returns

JSON - A full Transaction object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
    "object": "Transaction",
    "id": "tx1234",
    "account": {
       "object": "Account",
       "id": "cust_1235"
    },
    "source_payment_method": {
       "object": "PaymentMethod",
       "id": "paym_1235"
    },
    "shipping_address": {
       "object": "Address",
       "name": "c/o Charlie Brown",
       "line1": "123 Main Street",
       "city": "San Francisco",
       "district": "CA",
       "postal_code": "94105",
       "country": "US"
    },
    "items": [
       {
          "object": "TransactionItem",
          "sku": "sku_1234",
          "name": "Widgets",
          "price": 37.95,
          "quantity": 1
       }
    ],
    "source_ip": "63.201.132.182",
    "policy": {
       "min_chargeback_probability": 99,
       "send_email_notification": 0
    },
    "to_be_captured": false
 }' "https://api.prodtest.vindicia.com/transactions"

Capture a Transaction

Capture an authorized Transaction. Note: you can also have a transaction captured (complete charge) during creation – see Create a Transaction.

HTTP Request

POST https://api.vindicia.com/transactions/:transaction/actions/capture

Route (URL) Parameters

Parameter Default Description Required
transaction n/a The id or the vid of the Transaction to capture Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A minified Transaction object.

Example Request

curl -X POST \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
-d '{
   "object":"Transaction",
   "id":"tx1234",
   "account":{
      "object":"Account",
      "id":"cust_1235"
   },
   "source_payment_method":{
      "object":"PaymentMethod",
      "id":"paym_1235"
   },
   "shipping_address":{
      "object":"Address",
      "name":"c/o Charlie Brown",
      "line1":"123 Main Street",
      "city":"San Francisco",
      "district":"CA",
      "postal_code":"94105",
      "country":"US"
   },
   "items":[
      {
         "object":"TransactionItem",
         "sku":"sku_1234",
         "name":"Widgets",
         "price":37.95,
         "quantity":1
      }
   ],
   "source_ip":"63.201.132.182",
   "policy":{
      "min_chargeback_probability":99,
      "send_email_notification":0
   },
   "to_be_captured":false
}' "https://api.prodtest.vindicia.com/transactions"

The above command returns JSON structured like this:

{
  "object": "Transaction",
  "id": "tx1234",
  "vid": "5f5d1ba0ac7b0d492026c909211e8f90a6867068"
}

Finish a Transaction

Finish a Transaction.

HTTP Request

POST https://api.vindicia.com/transactions/:transaction/actions/finish

Route (URL) Parameters

Parameter Default Description Required
transaction n/a The id or the vid of the Transaction to finish Yes

Query Parameters

None.

Accepts

None.

Returns

JSON - A minified Transaction object.

Cancel a Transaction

Cancel a Transaction which has not yet been captured.

HTTP Request

POST https://api.vindicia.com/transactions/:transaction/actions/cancel

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Transaction object.

Fetch a specific transaction

Retrieves the specified Transaction.

HTTP Request

GET https://api.vindicia.com/transactions/:transaction

Route (URL) Parameters

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

Query Parameters

None.

Accepts

None.

Returns

JSON - A full Transaction object.

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/transactions/tx1234"

List all transactions

Retrieves all transactions. To limit the potentially large return size, it is recommended that the account or subscription query parameters be used to filter, in addition to pagination.

HTTP Request

GET https://api.vindicia.com/transactions

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
order asc Order the List of Transactions in either asc, ascending, or desc, descending order.
account none Limit the transaction list to a specified account id or vid - if specified, all Transactions associated with that Account. No
subscription none Limit the transaction list to a specified subscription id or vid - if specified, all Transactions associated with that subscription. No
include_children false Indicates whether or not to return any existing child accounts’ transactions for a given returned Subscription/account combination.
source_payment_method none Limit the transaction list to a specified Payment Method type No

Accepts

None.

Returns

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

A list of Transaction objects matching the query. Also:

Example Request

curl -X GET \
-u acaff38d462f9430d5cbcbaf:a575771fc679b9de \
"https://api.prodtest.vindicia.com/transactions?subscription=sub_1234x"

The above command returns JSON structured like this:

{
    "object": "List",
    "data": [
        {
            "object": "Transaction",
            "id": "FLX200001621",
            "vid": "d137d38973040467ed65b1d7c331a22ef14605c8",
            "created": "2020-05-31T15:12:28-07:00",
            "amount": 10.98,
            "currency": "USD",
            "account": {...},
            "source_payment_method": {...},
            "status_log": {...},
            "payment_processor": "Test",
            "payment_processor_transaction_id": "FLX200001621",
            "shipping_address": {...},
            "metadata": {
                "vin:RetryNumber": "0",
                "vin:recurring": "1",
                "vin:BillingCycle": "0"
            },
            "items": {
                "object": "List",
                "data": [
                    {...transactionitem...},
                    {...transactionitem...},
                    {...transactionitem...},
                    {...transactionitem...}
                ],
                "total_count": 4
            },
            "sales_tax_address": {...},
            "subscription_sequence": 1,
            "billing_plan_sequence": 1,
            "original_billing_date": "2020-05-27T00:00:00-07:00",
            "billing_attempt": 0,
            "subscription": {
                "object": "Subscription",
                "id": "sub_1234x",
                "vid": "796db5f7f7a1dea312f6c7e1393aebec1f1ecf1b"
            },
            "to_be_captured": true
        }
    ],
    "total_count": 1,
    "url": "/transactions?subscription=sub_1234x",
    "next": "/transactions?subscription=sub_1234x&starting_after=FLX200001621",
    "previous": "/transactions?subscription=sub_1234x&starting_before=FLX200001621"
}

Resources

The following resources are exposed under other resource’s endpoints

Activity Cancellation

Attributes

Name Type Description
reason string The reason for cancellation.
confirmation_code integer The confirmation code for the cancellation.
initiator enum Required. The type of initiator for cancellation. Can be: Chargeback, Customer, Merchant

Activity Email

Attributes

Name Type Description
src_email string The sender’s email address.
dest_email string The recipient’s email address.
note string A note on the content of the email message.

Activity Fulfillment

Attributes

Name Type Description
transaction Transaction Transaction id or vid associated with this activity.
shipper string The identifier of the shipping agent (such as UPS or FedEx) if any.
tracking_string string The tracking information on the physical package.
shipping_address Address The shipping address for the product. This data member encapsulates the customer’s mailing address, billing address, or both.
delivered boolean A Boolean flag that, if set to true, indicates that the merchandise delivery is complete.
received_ts datetime A time stamp that corresponds to the date and time reported by the shipping agent of when the merchandise delivery was completed.
receipt_name string The recipient’s name as reported by the shipping agent.

Activity Login

Attributes

Name Type Description
ip string The IP address from which a login originated.

Activity Logout

Attributes

Name Type Description
ip string The IP address from which a logout originated. Set ip to null if the logout is implicit due to, for example, a server timeout.

Activity Named Value

Attributes

Name Type Description
type string Required. The Activity type. For example, if you sell different types of music online, specify in this field the type, such as Rock.
name string Required. The Activity name. For example, if you sell music online, set the value to musicDownload.
value string Required. The Activity value. For example, fill in this field with the name of the artist or song for the download.

Activity Note

Attributes

Name Type Description
note string Notes (maximum of 1,024 characters) on the Activity object.

Activity Phone

Attributes

Name Type Description
type enum Required. An enumerated value that specifies who originated and who received the call. Can be: FromCustomerToMerchant, FromCustomerToOther, FromMerchantToCustomer, FromMerchantToOther, FromOtherToCustomer, FromOtherToMerchant
src_phone_number string The phone number from which the call originated.
dest_phone_number string The phone number of the person who received the call.
cid_phone_number string The caller ID (CID) for the phone number from which the call originated.
ani_phone_number string The Automatic Number Identification (ANI) for the phone number from which the call originated.
duration_seconds integer The length of the phone conversation in seconds.
note string Notes on the phone call.

Activity URI View

Attributes

Name Type Description
ip string The IP address to which the data was transferred.
uri string Required. The URI of the page.
size integer The size of the download.
bytes_transferred integer The number of bytes actually transferred to the customer.
transfer_time integer The length of the data transfer in seconds.
description string A description of the bytes transferred.

Activity Usage

Attributes

Name Type Description
description string The amount of use.
total integer The duration of use.
last_day integer The amount of use on the last day.
last_week integer The amount of use in the last week.
last_month integer The amount of use in the last month.
last_year integer The amount of use in the last year.
last_usage_date datetime The last date of use.

Addresses

The Address object represents a physical or mailing address.

Attributes

Name Type Description
object string Value is “Address”
vid string A Globally Unique Identifier (GUID) for this object. Assigned by Subscribe.
name string The name of the person or contact associated with this address.
line1 string Address Line 1
line2 string Address Line 2
line3 string Address Line 3
city string
county string
district string State, Province, or District
postal_code string
country string
phone string
fax string
latitude decimal
longitude decimal

Billing Plan Cancel Fee

Attributes

Name Type Description
object string Value is “BillingPlanCancelFee”
amount decimal The amount of the fee charged to the customer.
currency string ISO 4217 Currency Code of price.

Billing Plan Period

The Address object represents a physical or mailing address.

Attributes

Name Type Description
object string Value is “BillingPlanPeriod”
type enum Unit of time a period describes. Values can be Day,Week,Month,Year
quantity integer
cycles integer
prices Billing Plan Price[] A price for each defined currency for each period. Optional - Billing Plans do not require pricing (can be priced at the item/product level).

Billing Plan Price

Name Type Description
object string Value is “BillingPlanPrice”
amount decimal price
currency string ISO 4217 Currency Code of price.
price_list_name string Name of price list containing this price. This is free-form string of 255 characters or less
token_amount Token Amount The number of tokens required to purchase (if token-priced)

Code Redeemed By

Name Type Description
date datetime Date of Redemption.
note string Optional note about redemption.
redemption_reversal boolean
merchant_account_id string Account id
account_vid string Account vid

Credits

The Credit object represents a service credit granted to an account or subscription, taking the form of either currency, token, or time amounts.

Attributes

Name Type Description
object string Value is “Credit”
token_amounts Token Amount[] Tokens granted
currency_amounts Currency Amount[] Currency credits granted

Coupons

Attributes

Name Type Description
object string Value is “Coupon”
id string A merchant-specified unique identifier.
index integer
expires datetime
max_redemptions integer
codes_requested integer
codes_generated integer
coupon_prefix string
coupon_code_separator string
requires_activation_before_use boolean
on_demand_codes_allowed boolean

Currency Amounts

The CurrencyAmount object represents the currency credit detail associated with a particular grant of currency credits.

Attributes

Name Type Description
object string Value is “CurrencyAmount”
vid string A Globally Unique Identifier (GUID) for this object. Assigned by Subscribe.
currency string An ISO 4217 Currency Code.
amount decimal The currency amount of the credit.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
sort_value integer Order of precedence value.
description string Text provided upon credit grant.
reason string Text provided upon credit grant.
granted_by_cashbox boolean Indicates whether the credit was automatically granted by the system.
granted datetime The date and time the credit was originally granted.
account Account Beneficiary of credit (account-level).
subscription Subscription Beneficiary of credit (subscription-level).

Errors

The error object presents the error response to a request. See (Errors)[#Errors]

Attributes

Name Type Description
object string Value is “Error”
message string A human-readable message providing more detailed information about the error.

Invoice Item

Attributes

Name Type Description
object string Value is “InvoiceItem”
index_number integer Sequential index of all items on the invoice.
type enum The type of line item. Values can be RecurringCharge,Tax,Payment,Credit.
sku integer The SKU or unique identifier of the product purchased with this item (for one-time transactions this is an ad-hoc value.
description string Merchant-provided name or inherited description of the product purchased or line item explanation.
quantity integer The unit quantity for the item; for license-based products this is the license/seat quantity.
unit_amount decimal currency amount for a single quantity unit of the item
tax_classification string tax classification of the invoice item
item_added datetime The date and time the item was added to the subscription.
item_removed datetime The date and time the item was removed from the subscription.
item_serviceperiod_start datetime The start date for the period the charge on this item covers.
item_serviceperiod_end datetime The end date for the period the charge on this item covers.
subscription_item_id Subscription Item Subscription Item associated with this item.

Mandate

The mandates object represents the end-custom approval for a one-time or recurring billing using their provided bank account details. A common requirement for UK and SEPA direct debit payment methods.

Attributes

Name Type Description
object string Value is “Mandate”
created datetime The date/time at which the mandate was recorded into Subscribe.
identifier string Externally provided unique identifier for the Mandate (agreement).
status enum Current Mandate status. Values can be Active,Cancelled,Expired,Failed,Pending

Payment Provider

The payment providers object represents processor or payment channel used to transact a particular charge.

Attributes

Name Type Description
object string Value is “PaymentProvider”
name string Provider Name
dispute_address Address Contact address for written disputes.
dispute_email string Contact email for electronic disputes.
dispute_uri string Contact URL for online disputes.
auth_expiration_days integer Default expiration timing (days) for un-captured authorizations.
auth_currency_override string Currency override for Authorizations
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.

Phone Number

A phone number.

Attributes

Name Type Description
object string Value is “PhoneNumber”
phone_type enum Type or Use designation for the phone number. Value can be CS,Fax,Home,Main,Mobile,Pager,Unspecified,Work
country_code string Country Code segment of a phone number.
area_code string Area Code segment of a phone number.
local_number string Local segment of a phone number (excluding extension).
extension string Phone number extension.
raw_input string Raw, unfiltered data input by customer.

Price Criteria

Price Criteria details used with telco carrier billing payment methods.

Attributes

Name Type Description
object string Value is “PriceCriteria”
payment_provider Payment Provider Payment Provider selected for Transaction. Limited to Carrier Billing supported providers.
currency string ISO 4217 Currency Code for for either the static_price_inc_salestax, or the dynamic_target_price Overrides CarrierBilling.currency.
country_code string ISO 3166-1 alpha-2 countryCode for customer location. Overrides CarrierBilling.countryCode.
price_point_deviation_policy enum The price deviation policy for dynamic price selection. Value can be HiOnly,HiPreferred,LowOnly,LowPreferred,NearestNoPreference
dynamic_price_mode enum Specifies which price point element is matched by the dynamic pricing algorithm. Values can be PayoutGross,PayoutNet,Price
merchant_service_identifier string Service identifier for Payment Provider/Merchant.
sub_merchant_identifier string Optional identifier of sub-merchant associated with Transaction.
description string
fwd_url string Overrides both the successful transaction forward-to URL and the failed transaction forward-to URL.
static_selection_row_ref integer Row number identifier in the static product/service price matrix
static_price_inc_sales_tax decimal Price including tax (the actual amount the consumer will pay). Used with Transactions with static ‘exact match’ pricing.
dynamic_deviation integer The percent deviation (+/- 1000) from the target value that is acceptable as a price point selection.
dynamic_match integer The percent deviation (+/- 1000) from the target value that is classified as an exact match.
dynamic_target_price decimal Target price in the specified currency for dynamic pricing.

Product Description

Attributes

Name Type Description
language string The 2 character ISO language code in which the product description is written.
description string A description of this product written in language. A free-form string of less than 256 characters.

Product Price

Attributes

Name Type Description
amount decimal Value of the currency amount.
currency string ISO 4217 currency code to be used for this ProductPrice Amount. Defaults to USD. Note: Mutually Exclusive of token
token Token Details of pricing using tokens. Note: Mutually Exclusive of currency

Refund Item

Attributes

Name Type Description
transaction_item_index_number decimal Sequence number assigned upon creation to a Transaction Item by Subscribe. Either the transaction_item_index_number, or the sku, must be specified for each Refund Item.
sku string SKU on the original transaction line item (sku need not be passed in if the transaction_item_index_number is passed in). If the SKU is passed in, and can be used to uniquely identify the transaction item, it will be used, otherwise an error will be returned.
description string Readonly. A description of the Transaction Item, which will be filled in by Subscribe from line item description on the original Transaction.
amount decimal Amount of the requested refund for this item, in the currency of the overall transaction. This amount must not exceed the original Transaction Item amount, minus any discounts and minus the sum of all prior refunds against this item. This field may be left blank if the taxOnly field is set to true
tax_only boolean If this is true, the amount parameter is ignored and the refund amount will be the total of the as yet un-refunded taxes for this item.
taxes Tax Item[] Read-only array to list the taxes from the original Transaction Item that are being refunded.

Rate Plan Tier

Attributes

Name Type Description
name string
rate_price Rate Plan Price[] Required. An array of Rate Plan Price objects, which define the Price (or prices) for this Tier (one price for each currency used).
charge_customer enum Can be: FlatFee which defines a stepped pricing structure, in which the customer is charged the rate price per Tier or PerUnit which defines a graduated pricing structure, in which the customer is charged the number of units accessed, multiplied by the rate price per tier.
begins_at_level decimal The number of Units at which this Tier’s pricing structure takes effect. The number of Units defined for each Tier runs from the minimum value of the Tier, to one Unit less than the minimum value of the next higher Tier. Typically the first tier would have beginsAtLevel = 1. The final, highest tier is unbounded (infinite).

Rate Plan Price

Attributes

Name Type Description
amount decimal Amount
currency string ISO 4217 Currency Code.

Rated Unit

Attributes

Name Type Description
name_singular string Singular name of units.
name_plural string Plural name of units.

Score Code

Score codes indicate risk/fraud scoring rules. A score will include the codes indicated which rules were invoked in calculating the result.

Attributes

Name Type Description
object string Value is “ScoreCode”
id string A Subscribe-specified unique Integer ID of the rule, such as 1
description string String description of the rule, e.g. PRIOR_CB_IN_VERTICAL

Season

Season objects represent a merchant-defined calendar-based “season” indicating when a particular service offering is provided. Often indicates a sporting or entertainment industry season. In Subscribe, most simply stored as a date range with a description; and grouped into Season Sets as needed (to allow for sequential season-based entitlement and billing, from one season to the next where the dates for a given season change each year).

Attributes

Name Type Description
object string Value is “Season”
description string Free-form description of the season, <= 2048 characters.
starts datetime The date/time at which the Season begins.
ends datetime The date/Time at which the Season ends.

Subscription Billing Plan History Record

Attributes

Name Type Description
billing_plan Billing Plan
starts datetime
ends datetime

Subscription Item

Attributes

Name Type Description
object string Value is “SubscriptionItem”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid. We strongly recommend specifying an item-level id.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
index integer Sequential index of all items on the subscription.
product Product The predefined SKU of the product billed by this item.
amount decimal The unit price of the item.
currency string ISO 4217 Currency Code of this item.
rate_plan Rate Plan For rated products, the governing rate_plan
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
quantity decimal The unit quantity for the item; for license-based products this is the license/seat quantity.
token Token Token associated with amount (if this is a Token-based Subscription]). This value will be ignored if amount is null
cycles integer The number of billing cycles for which this item should bill (0 = life of the Subscription)
cycles_remaining integer If a billing cycle limit is defined, this is the number of billing cycles left to bill.
created datetime The datetime this item was added to the subscription.
ends datetime The datetime this item was removed from the subscription (end of service).
starts datetime The datetime this item was effective/started on the subscription (start of service).
replaces Subscription Item SubscriptionItem replaced by this item.
replaced_by Subscription Item SubscriptionItem which replaced this item.

Subscription Item History Record

Attributes

Name Type Description
subscription_item Subscription Item
action enum Can be: Add, Edit, Remove
effective datetime
created datetime

Tax Exemption

A certificate or other recorded tax exemption on file for a customer (account) or specific subscription or transaction.

Attributes

Name Type Description
object string Value is “TaxExemption”
region string Geography or jurisdiction the exemption applies to.
exemption_id string Exemption ID or certificate number filed with tax authority. E.g., a VAT ID, or a US Tax ID.
active boolean If true, this exemption is active.

Tax Item

And individual tax assessed for a specified jurisdiction.

Attributes

Name Type Description
object string Value is “TaxItem”
jurisdiction string The sku for the tax jurisdiction
name string The description for the tax jurisdiction
amount decimal The amount of tax assessed
external_tax_name string The name for the tax or fee as provided by the tax service; corresponds to Imposition in Vertex and TaxName in Avatax.
external_tax_category string The category of tax or fee as provided by the tax service; corresponds to ImpositionType in Vertex and TaxGroup in Avatax
external_jurisdiction_name string The name of the tax jurisdiction for this tax or fee as provided by the tax service; corresponds to Jurisdiction in Vertex and JurisName in Avatax
tax_rate decimal The effective rate used to calculate this tax as provided by the tax service; corresponds to EffectiveRate in Vertex and Rate in Avatax

Time Intervals

The Time Interval object represents the time-based credit detail associated with a particular grant of time credits.

Attributes

Name Type Description
object string Value is “TimeInterval”
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
years integer Number of years
months integer Number of months (remainder after years)
weeks integer Number of weeks (remainder after months)
days integer Number of days (remainder after weeks)
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
sort_value integer Order of precedence value.
description string Text provided upon credit grant.
reason string Text provided upon credit grant.
granted_by_cashbox boolean Indicates whether the credit was automatically granted by the system.
granted datetime The date/time the credit was originally granted.
account_vid string The vid of Beneficiary of credit (account-level).
merchant_account_id string The id of Beneficiary of credit (account-level).
auto_bill_vid string The vid of Beneficiary of credit (subscription-level).
merchant_auto_bill_id string The id of Beneficiary of credit (subscription-level).
source string

Tokens

The token object provides a way to offer virtual currencies or track the balance of a consumable service item.

Attributes

Name Type Description
object string Value is “Token”
id string A merchant-specified unique identifier. Optionally, this object can be identified by its vid. For transactions created automatically, this field will be assigned by Subscribe.
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
description string Text describing the token type.

Token Amounts

The Token Amount object represents the token-based credit detail associated with a particular grant of token credits.

Attributes

Name Type Description
object string Value is “TokenAmount”
token Token The token type for this credit.
amount integer The balance of tokens in the grant.
source string

Transaction Item

Attributes

Name Type Description
object string Value is “TransactionItem”
sku string The SKU or unique identifier of the product purchased with this item (for one-time transactions this is an ad-hoc value.
index_number integer Sequential index of all items on the transaction.
item_type enum(TransactionItemType)
name string Merchant-provided name or inherited description of the product purchased
subscription_item Subscription Item Subscription Item associated with this item.
price decimal unit price of this item
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
quantity decimal The unit quantity for the item; for license-based products this is the license/seat quantity.
tax_classification string The tax code or classification applicable to this item.
tokens Token Amount[] Tokens granted to the account on this transaction for purchasing this item
campaign_code string Campaign code redeemed on this Transaction Item.
campaign_id string The unique identifier for a campaign applied to this item.
campaign_description string Detailed description of the campaign for the discount on this item, if there is one.
service_period_starts datetime The start date for the period the charge on this item covers.
service_period_ends datetime The end date for the period the charge on this item covers.
tax_type string Fixed Tax definition (read only).
tax Tax Item[] array to list the individual tax items associated with the corresponding transactionItem.
related_transactions string[] List of merchantTransactionIds for all Transactions related to this item. e.g. For a credit resulting from the removal of an SubscriptionItem, this will contain the list of all Transactions that originally billed for the item within the time frame covered by the credit.
item_refunds Transaction Item Refund Summary[] Detail on item-level refunds applied to this item.
discount decimal The total discount amount applied to this item.
subtotal decimal The pre-tax (post-discount) subtotal.
total decimal The grand total of this item

Transaction Item Refund Summary

Attributes

Name Type Description
created datetime Timestamp when the refund was issued.
amount decimal Full or partial amount of the refund.
tax decimal Full or partial amount of tax refunded.
tax_only boolean If set to true, then Subscribe refunded only the tax portion of a Transaction Item.
refund Refund Refund id of the Refund object where the refund was issued.

Transaction Refund Item

Attributes

Name Type Description
transaction_item_index_number decimal Sequence number assigned upon creation to a Transaction Item by Subscribe. Either the Transaction Item Index Number, or the SKU must be specified for each Refund Item.
sku string SKU on the original transaction line item (sku need not be passed in if the transaction_item_index_number is passed in). If the SKU is passed in, and can be used to uniquely identify the transaction refund item, it will be used, else an error will be returned.
description string Output only. A description of the Transaction Refund Item which will be filled in by Subscribe from line item description on the original Transaction.
amount decimal Amount of the requested refund for this item, in the currency of the overall transaction. This amount must not exceed the original Transaction Item amount minus discount(s), minus the sum of all prior refunds against this item. Currencies may not be mixed on a single Transaction. This field may be left blank if the tax_only field is set to true.
tax_only boolean If this is true, the amount parameter is ignored and the refund amount will be the total of as-yet-un-refunded taxes for this item.
taxes Tax Items[] Read-only array to list the taxes from the original Transaction Item that are being refunded.

Transaction Status

Attributes

Name Type Description
object string Value is “TransactionStatus”
status enum Status of the Transaction. Values can be New,AuthorizationPending,AuthorizedPending,Authorized,AuthorizedForValidation,Cancelled,Captured,Settled,Refunded,Pending
created datetime The effective datetime of this status
payment_method_type enum Type of Payment Method (clarifies status). Values can be CreditCard, PayPal,ECP ,DirectDebit,Token,HostedPage,Boleto,MerchantAcceptedPayment,CarrierBilling, Amazon,Skrill,ApplePay
credit_card_status Credit Card Status Status details for a credit card based Transaction
ecp_status TransactionStatusECP Status details for an ECP - Electronic Check Processing transaction
boleto_status TransactionStatusBoleto Status details for a Boleto Bancario transaction
hosted_page_status TransactionStatusHostedPage Status details for a HostedPage Transaction
paypal_status TransactionStatusPayPal Status details for a PayPal transaction
direct_debit_status TransactionStatusDirectDebit Status details for a DirectDebit transaction
carrier_billing_status TransactionStatusCarrierBilling Status details for a CarrierBilling Transaction
amazon_status TransactionStatusAmazon Status details for a Amazon Transaction
skrill_status TransactionStatusSkrill Status details for a Skrill Transaction
apple_pay_status TransactionStatusApplePay Status details for an ApplePay Transaction
google_pay_status TransactionStatusGooglePay Status details for an GooglePay Transaction
vin_avs enum AVS result. Values can be FullMatch,PartialMatch,NoMatch,IssuerError,NoOpinion,NotSupported
funding_source_balance decimal The outstanding available balance on the submitted PaymentMethod.
note string Optional note.

Transaction Credit Card Status

Attributes

Name Type Description
object string Value is “TransactionStatusCreditCard”
auth_code string Result code for the status update. In the case of auth, capture, and authCapture this should be the code returned by the payment processor. In the case of cancellations, it should be the reason code returned by the payment processor if that is the cause of the cancellation, or -1 if the decision to cancel was made by you or the customer.
avs_code string AVS response code. When reporting a transaction, if you receive the AVS code as a string along with its authorization code (ie Y:2341234234 or Y-2341234234) just copy it into this field. If you receive the AVS code separate from its authorization code you should concatenate them with a colon as a separator as in the first example.
cvn_code string CVN response code. When reporting a transaction, if you receive the CVN code as a string along with its authorization code (ie M:2341234234 or M-2341234234) just copy it into this field. If you receive the CVN code separate from its authorization code you should concatenate them with a colon as a separator as in the first example.
auth_approval_code sting Authorization approval code. A unique string from the processor confirming the authorization.
extended_card_attributes Extended Card Attributes Additional credit card details returned from Payment Provider
extended_verification Extended Verification Response

Transaction Status ECP

Attributes

Name Type Description
object string Value is “TransactionStatusECP”
auth_code string Result code for the status update. In the case of auth, capture, and authCapture this is the reason code returned by the payment processor. In the case of cancellations, it is the reason code returned by the payment processor if that is the cause of the cancellation, or -1 if the decision to cancel was made by you or the customer.

Transaction Status Boleto

Attributes

Name Type Description
object string Value is “TransactionStatusBoleto”
uri string The URL returned by the payment processor in response to presentment of fiscal number. This should be displayed to the customer for further processing of the Boleto Bancario payment method based transaction

Transaction Status Hosted Page

Attributes

Name Type Description
object string Value is “TransactionStatusHostedPage”
auth_code string Result code for the status update.
redirect_url string The Hosted Pages URL merchant should redirect a customer to complete a HostedPage transaction

Transaction Status PayPal

Attributes

Name Type Description
object string Value is “TransactionStatusPayPal”
token string Token for PayPal ExpressCheckout
paypal_email string Email used in PayPal ExpressCheckout 127 single-byte limit
payer_id string Unique PayPal customer account identification number in PayPal ExpressCheckout 13 single-byte alpha numeric characters limit
auth_code string Result code for the status update.
redirect_url string The PayPal URL merchant should redirect a customer to complete a PayPal transaction

Transaction Status Direct Debit

Attributes

Name Type Description
object string Value is “TransactionStatusDirectDebit”
auth_code string Result code for the status update.

Transaction Status Carrier Billing

Attributes

Name Type Description
object string Value is “TransactionStatusCarrierBilling”
auth_code string Result code for the requested action
buy_url string URL which (when sourced on a customer web browser) generates HTML elements to facilitate processing of a CarrierBilling payment

Transaction Status Amazon

Attributes

Name Type Description
object string Value is “TransactionStatusAmazon”
auth_cod string Result code for the status update.

Transaction Status Skrill

Attributes

Name Type Description
object string Value is “TransactionStatusSkrill”
auth_code string Result code for the status update.
token string Session id for Skrill Gateway
redirect_url string The Skrill URL merchant should redirect a customer to complete a Skrill transaction

Transaction Status Apple Pay

Attributes

Name Type Description
object string Value is “TransactionStatusApplePay”
auth_code string Result code for the status update. In the case of auth, capture, and authCapture this should be the code returned by the payment processor. In the case of cancellations, it should be the reason code returned by the payment processor if that is the cause of the cancellation, or -1 if the decision to cancel was made by you or the customer.

Transaction Status Google Pay

Attributes

Name Type Description
object string Value is “TransactionStatusGooglePay”
auth_code string Result code for the status update. In the case of auth, capture, and authCapture this should be the code returned by the payment processor. In the case of cancellations, it should be the reason code returned by the payment processor if that is the cause of the cancellation, or -1 if the decision to cancel was made by you or the customer.

Payment Method Details

Subscribe supports a large variety of Payment Methods across a number of providers/processors.

Any number of PaymentMethod objects can be associated to a particular Account – and each PaymentMethod is associated to a single Account; each PaymentMethod represents an instance of a particular payment method – so the same Credit Card used by two customers will be represented as two Payment Methods (possibly with identical details), one on each Account.

Payment Method Types are defined as sub-resources of the Payment Method object.

See Payment Method object for general information about manipulating Payment Methods (via the Payment Method object)

This section provides additional detail on the type-specific behaviors and payment-flows associated with each support payment method type:

Credit Cards

Credit Cards includes credit and charge cards, debit cards, and prepaid cards. Which card brands and types are supported will vary based upon a merchant’s payment processor - Subscribe has no restrictions on card types.

The Credit Card object is associated to (and presented with) the Payment Method object on an owning Account, Subscription, Transaction, or Refund.

Credit Card Attributes

This object defines an instance of a specific Credit Card.

Name Type Description
object string Value is “CreditCard”
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
account string The Primary Account Number (PAN) aka Credit Card Number (encrypted/hidden when returned) For non-Subscribe methods (e.g., Transaction::score), this field must be left blank. The precise form used here will vary with the exact payment method.
bin string The first 6 digits of the PAN (Bank Identifier Number). If the account field is provided, this may be left blank and it will be filled in by Vindicia.
last_digits string The last 4 digits of the PAN
account_length integer The number of digits in the PAN
hash_type enum The algorithm used for hashing the account number. If this value is not provided we assume SHA1. Values can be sha1,md5
account_hash string A hash of the full PAN. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this may be left blank and the hash will be calculated by Vindicia. The exact length and format of this string may depend upon the hash algorithm chosen.
expiration_date string Expiration date of the credit card. Should be formatted as YYYYMM. For example, July, 2028 should be sent as 202807.
extended_card_attributes Extended Card Attributes Additional credit card details returned from Payment Provider
cvn string CVV (Card Verification Value) or CVN (Card Verification Number) printed on the card.
last_au_request_date datetime Timestamp of the most recent Account Updater request.
last_update_date datetime Timestamp of the most recent credit card update.
au_response_code string Response code from the payment provider for the most recent Account Updater request.
au_response_message string Reply from the payment provider for the most recent Account Updater request.
{
  "object" : "PaymentMethod",
  "id" : "pm_1234",
  "vid" : "ad427a35c0335f61ee639c6b614eca1c89337eac",
  "active" : true,
  "description" : "Personal Visa",
  "currency" : "EUR",
  "primary" : true,
  "type" : "credit_card",
  "credit_card" : {
    "account" : "4111111111111111",
    "expiration_date" : "202501",
    "cvn" : "123"
  },
  "metadata" : {
    "favorite activity" : "flying kites",
    "favorite dog" : "Snoopy"
  }
}

Extended Card Attributes

This object accompanies a Credit Card. When available it presents additional useful detail about the Credit Card provided by Subscribe and the underlying payment processor (and in some cases from the card association).

Name Type Description
object string Value is “ExtendedCardAttributes”
commercial_card integer Boolean indicator - True = Card is flagged as business/commercial. Applicable Processors: CPT, Litle.
consumer_card integer Boolean indicator - True = Card is flagged as personal/consumer. Applicable Processor: Litle.
credit_card integer Boolean indicator - True = Card is a credit or charge card. Applicable Processors: Litle, MeS, Chase.
debit_card integer Boolean indicator - True = Card is a debit card. Applicable Processors: Litle, MeS, Chase.
signature_debit_card integer Boolean indicator - True = Debit card uses “Signature” scheme. Applicable Processor: CPT.
pinless_debit_card integer Boolean indicator - True = Debit card uses “Pinless” scheme. Applicable Processor: CPT.
gift_card integer Boolean indicator - True = Card is a gift card. Applicable Processors: Litle, MeS.
prepaid_card integer Boolean indicator - True = Card is a pre-paid card. Applicable Processors: CPT, Litle, MeS.
payroll_card integer Boolean indicator - True = Card is a payroll/benefits card. Applicable Processors: CPT, Litle.
healthcare_card integer Boolean indicator - True = Card is a benefits card. Applicable Processors: CPT, Litle, MeS.
virtual_account_number integer Boolean indicator - True = Card is a virtual account. Applicable Processor: Litle.
reloadable integer Boolean indicator - True = Prepaid card is re-loadable. Applicable Processor: Litle.
country_of_issuance string Country Code for issuing bank. Possible values: USA, etc. Applicable Processors: CPT, Litle.
durbin_regulated integer Applicable Processor: CPT.
affluent integer Boolean indicator - True = Account Holder flagged as “affluent”. Applicable Processors: CPT, Litle.
mass_affluent integer Boolean indicator - True = Account Holder flagged as “mass affluent”. Applicable Processor: Litle.
card_description string The returned description for the card. Applicable Processors: Litle, MeS.

Extended Verification Response

Attributes

Name Type Description
object string ExtendedVerificationResponse
redirect_url string The URL merchants should redirect a customer to in order to complete the transaction
post_values hash Optional array of name/value pairs the merchant should POST to the redirectUrl

Using Credit Cards (Operations)

Credit Cards are a standard electronic payment method type; they do not require any special live approvals from the account holder to use. Initial entry typically involves an immediate validation (or validation via authorization if an immediate transaction is present).

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Credit Card Payment Flows

For one-time transactions with Credit Cards:

• A merchant sends a transaction to Subscribe to perform an internal validity check to ensure Account and Payment Method information meets internal consistency check, and optionally calls the ChargeGuard Fraud Screen to determine chargeback probability.

• If the transaction passes the validity check (and is within fraud screen threshold if chargeback probability is calculated), then the transaction is either sent for processing, or the merchant application performs additional work before explicitly submitting the transaction for processing.

• If the transaction fails the validity test, a failure reason code is returned. If chargeback probability is calculated, a fraud screen score is also returned.

• Subscribe submits the transaction to the payment processor and can perform either an Auth/Capture or an Auth that may then be followed by an explicit Capture if more work is needed (for example, ensuring that a tangible good is shipped before capturing the transaction).

• Once the transaction is Captured, a One-Time Inbound Success notification can be sent to the customer and the merchant application sets the customer entitlement.

• If a transaction is refunded, Subscribe can send a Refund notification.

For recurring billing with Credit Cards:

• Subscribe can send a Pre-Bill, End of Trial, or Expiration notification.

• Subscribe performs an internal validity check to ensure Account and Payment Method information meets an internal consistency check.

• If the transaction passes the validity check, processing continues.

• If the transaction fails, then Subscribe can send a Hard Failure notification.

• If the customer opts out of the subscription via the merchant’s customer self-service portal after a Pre-Bill notification has been sent, then Subscribe can send a Cancellation notification.

• The merchant defines how many times/days before subscription expiration that billing should be attempted. For as long as a customer does not opt out of a subscription, Subscribe continues to submit a billing transaction to the payment processor.

• If the transaction Authorization/Capture is successful (determined by the reason code returned from the payment processor), Subscribe can send a Success notification.

• If the payment processor returns a reason code that indicates a failure (for example, a Hard Fail if the card is longer valid or the account is closed, or Soft Fail if there are insufficient funds) Subscribe makes another attempt to process the transaction.

• If the merchant has enabled Card Account Updater with the payment processor, and the response resulted in Hard Fail, Subscribe sends a request for an updated card to the payment processor.

• If the payment processor returns an updated card Subscribe changes the transaction status to Soft Fail. All Soft Fails are resubmitted to the payment processor according to the retry schedule defined by the merchant, and in the meantime Subscribe can send a Soft Fail notification if the merchant has defined one.

• A transactions that results in a Hard Fail is not resubmitted to the payment processor, but Hard Fail notification messages can be sent according to the retry schedule defined by the merchant.

• If a customer updates a Payment Method, a custom merchant application can make a Catch Up Billing call to perform another billing attempt. If successfully captured, Subscribe can send a Success notification.

• If a transaction is refunded, Subscribe can send a Refund notification.

Credit Cards includes credit and charge cards, debit cards, and prepaid cards. Which card brands and types are supported will vary based upon a merchant’s payment processor - Subscribe has no restrictions on card types. The CreditCard object is associated to (and presented with) the PaymentMethod object on an owning Account, Subscription, Transaction, or Refund.

PayPal (Express Checkout)

PayPal Attributes

Name Type Description
object string Value is “PayPal”
paypal_email string PayPal Email Address of User
payer_id string PayerID
return_url string The URL to which you would like customers to be redirected after they have successfully completed payment transactions on the PayPal site. This is often your confirmation page, on which the customer confirms the order and payment or the billing agreement.
cancel_url string The URL to which you would like to redirect customers if PayPal indicates failure after they have completed the payment process on the PayPal site.
request_reference_id boolean When processing the initial Transaction for a Subscription, ask PayPal for a Reference ID that can be used in the future for recurring billing. This works only if you have been previously approved for Reference Transactions by PayPal.
reference_id string PayPal field “REFERENCEID” which is the Billing Agreement ID or Reference Transaction ID associated with a PayPal Billing Agreement. If you enter a value for this data member, set requestReferenceId to false.

Using PayPal Express Checkout (Operations)

PayPal Express Checkout (commonly referred to as just “PayPal”) is an electronic payment method which requires a Billing Agreement which authorizes a merchant to use a customer’s PayPal account to collect charges (see below). Typically, when initially created, this will require a redirect of the consumer/customer to approve the billing agreement with PayPal, after which the agreement can be used in a similar manner as credit cards (charged variable amounts one or more times on demand). If you already have the Billing Agreement Identifier, you can store and/or use a PayPal payment method in Subscribe without any customer interaction wherever payment methods are used.

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

PayPal (Express Checkout) Payment Flows

Both One-Time and (initial) Recurring Transactions using PayPal as a Payment Method step through the following process:

  1. When your customer selects PayPal as their Payment Method, call Subscribe to initiate the transaction, passing Subscribe all relevant purchase information.
  1. Subscribe creates a new Transaction, and calls PayPal (uses the behind-the-scenes PayPal API SetExpressCheckout).

  2. PayPal initiates the session, and returns a token, the PayPal redirect URL, and a reference ID (if requested) to Subscribe.

  3. Note: Request a reference ID from PayPal only for use in recurring AutoBills. The reference ID is not used for One-Time Transactions.

  4. Subscribe then sets the Transaction status to Pending (or Failed), and redirects your customer to you with the PayPal token and redirect URL. (If PayPal returned a Failure, Subscribe redirects your customer to your specified cancel URL.)

  1. Redirect your customer to the PayPal site, using the PayPal redirect URL returned from Subscribe.
  2. “In context” PayPal flow is not supported yet. Subscribe currently offers the standard “redirect” flow.

  3. On the PayPal redirect URL, your customer logs in to PayPal (usually enters their username and password, and clicks Continue, but methods like PayPal’s One-Touch can be used). PayPal authenticates the user, and redirects them to the Payment Method selection page. Your customer selects their payment method, reviews the order, and clicks Approve (or Cancel).

  1. From your Success page, call Subscribe to finalize the transaction. OR From your Cancel page, call Subscribe to cancel the transaction.

  2. Subscribe sets the Transaction Status to Authorized, queues it for batch capture (and behind-the-scenes calls PayPal API ExpressCheckout with the PayPal Token to complete the process).

Transactions are captured in batches throughout the day.

Using PayPal for recurring billing, your customer must participate directly in the initial product purchase, but subsequent billing cycles may be generated and handled automatically by Subscribe and PayPal. During the initial purchase process, the customer must be “validated,” but for subsequent billings, the customer need not be validated again unless the AutoBill requires updating or the AutoBill expires.

ACH (aka ECP)

ACH Attributes

Name Type Description
object string Value is “ECP”
account string The full bank account number for this payment. Be certain to enter this number in full if you are using the associated payment method for Subscribe Transactions. Note: Subscribe does not validate ECP accounts algorithmically, and partially masks the account number when returning it in response to your call.
hash_type enum The type of hash algorithm used if you specify the accountHash field. Subscribe supports SHA1 hashing only. You need not specify this field if the associated payment method is for a Transaction processed through Subscribe. Can be: md5 or sha1
account_hash string A hash of the full account number. Specify this string only if you are not specifying the full account number when reporting a Transaction for ChargeGuard.
routing_number string The bank routing number for an ACH or ECP account. Be certain to enter the correct number if you are using the associated payment method for Subscribe Transactions.
account_type enum Required. The type of bank account that issues this electronic check. Can be: ConsumerChecking, ConsumerSavings, CorporateChecking, CorporateSavings
last_digits string The truncated last part of the full account number, typically the last four or five digits of that number. Specify this string only if you are not specifying the full account number or its hash in the accountHash field for security when reporting transactions to Vindicia for ChargeGuard. You need not specify this field if the associated payment method is for a one-time or recurring transaction processed through Subscribe.
account_length integer The length (number of digits) of the full account number. Specify this string only if you are not specifying the full account number when reporting a Transaction for ChargeGuard.
allowed_transaction_type enum The enumerated Transaction types allowed for ECP- or ACH-based Transactions that use this PaymentMethod object. Can be: All, Inbound, InboundOutbound, NA, Outbound, Transfer

Using ACH/ECP (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

ACH/ECP Payment Flows

Amazon Payments

Amazon Payments Attributes

Name Type Description
object string Value is “Amazon”
billing_agreement_id string The Amazon billing agreement identifier. This value is returned by the OffAmazonPayments getAmazonBillingAgreementId API call and should be passed to Vindicia here.
buyer_name string The name Amazon associates with the billing agreement identifier.
buyer_email string The email Amazon associates with the billing agreement identifier.
physical_address Address The address Amazon associates with the billing agreement identifier.
billing_address Address The billing address Amazon associates wit the buyer’s payment method.
address_verification_code string The address verification code Amazon received when validating the buyer’s payment method.

Using Amazon Payments (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Amazon Payments Flows

Apple Pay

Apple Pay Attributes

Name Type Description
object string Value is “ApplePay”
payment_instrument_name string The paymentInstrumentName field from PKPayment.
payment_network string The paymentNetwork from PKPayment.
transaction_identifier string he transactionIdentifier field from PKPayment.
payment_data string The paymentData field from PKPayment
expiration_date string Returns the expiration date of the credit card used for ApplePay. Will be formatted as YYYYMM. For example, July, 2028 will be returned as 202807.

Using Apple Pay (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Apple Pay Flows

Boleto Bancario

Beleto Bancario Attributes

Name Type Description
object string Value is “Boleto”
fiscal_number string The fiscal number that appears on the customer’s Boleto Bancário payment slip. This number, formally called Casadastro de Pessoas, is formatted in a specific pattern (modulo 11).

Using Boleto Bancario (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Boleto Bancario Flows

Carrier Billing (Mobile Carriers)

Carrier Billing Attributes

Name Type Description
object string Value is “CarrierBilling”
phone_number Phone Number The customer phone number used for the payment.
encoded_phone_number string Read Only. The payment provider-encoded phone number used in the Transaction.
carrier string The identifier for the carrier, either read from the phone or entered by the customer.
payment_provider Payment Provider The payment provider selected for the Transaction.
currency string ISO 4217 Currency Code for either the static_price_inc_salestax, or the dynamic_target_price. (For dynamic pricing, the customer currency will be determined by the customer region/countryCode.)
country_code string ISO 3166-1 alpha-2 Country Code for the customer’s location.
price_criteria Price Criteria PriceCriteria are used when stipulating dynamic pricing for a Transaction. Note that priceCriteria has no meaning (and will be ignored) when creating a new PaymentMethod for an Account. Therefore only include this subobject with the PaymentMethod when processing a Carrier Billing-funded Transaction.

Using Carrier Billing (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Carrier Billing Flows

Direct Debit

Direct Debit Attributes

Name Type Description
object string Value is “DirectDebit”
account string The number of the customer’s bank account from which to deduct payment. To use the associated PaymentMethod object for one-time or recurring transactions, you must specify the full account number.
last_digits string The last part of the account number for display purposes, generally the last four digits. If the account field is provided, this may be left blank and it will be filled in by Vindicia.
account_length integer Length of the total account number. If the full account number is submitted, this field may be left blank; Vindicia will calculate it.
hash_type enum Can be: md5 or sha1
account_hash string A hash of the full account number. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this may be left blank and the hash will be calculated by Vindicia. The exact length and format of this string may depend upon the hash algorithm chosen.
country_code string The ISO-3166-1 two-letter code for the country in which the related bank account is located. This code must match the country code specified in the PaymentMethod object’s billing address.
bank_sort_code string The European bank sort code that identifies the bank that houses the customer’s bank account whose number is specified in the account field. This code is similar to the bank routing number in the United States. Required You if this is for a Transaction processed through Subscribe unless the countryCode attribute is set to NL or BE.
rib_code string The RIB code for an DirectDebit account (France only)
branch_code string The branch code for an Direct Debit account

Using Direct Debit (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Direct Debit Flows

External Billing

External Billing Attributes

Name Type Description
object string Value is “ExternalBilling”
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
bill_receiver string The payment provider. In this case the payment provider is one of the Amdocs Billing systems.—CES, Ensemble, or Optima. Currently CES is the only billing system implemented in the integration.
payment_channel string The customer paymentChannelId in the billing system. Best practice is to set this the same as the Payment Method id.
financial_account string The customer financial account ID in the billing system.

Using External Billing (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

External Billing Flows

Google Pay

Google Pay Attributes

Name Type Description
object string Value is “GooglePay”
payment_token string The encrypted paymentToken you receive after calling GooglePaymentDataRequest.
eci_indicator string
gateway_merchant string
message_identifier string
expiration_date string

Using Google Pay (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Google Pay Flows

Hosted Page

Hosted Page Attributes

Name Type Description
object string Value is “HostedPage”
payment_provider Payment Provider The payment provider selected for the Transaction.
country_code string The ISO 3166 ( alpha-2 ) country code for customer’s location,
return_url string The URL to which you would like customers to be redirected after they have successfully completed the Hosted Page transaction. This is often your confirmation page.
language string Required. The ISO 639-1 language matrix code for the payment pages.
processor_payment_method_id string The payment method to use for the Transaction.
billing_agreement_id string If supported by the processor, the token used to rebill this payment method in the future.

Using Hosted Page (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Hosted Page Flows

Merchant Accepted Payment (Pay By Invoice)

MAP Attributes

Name Type Description
object string Value is “MerchantAcceptedPayment”
amount decimal The amount paid by a customer. This value must be 0 for PaymentMethods attached to Subscriptions. Note: Merchant Accepted Payment Methods may be attached to Subscriptions to indicate that the customer should be invoiced (rather than automatically charged).
currency string The ISO 4217 currency code for the payment. Must match the currency for charges on the Invoice/Subscription.
token Token Token object for the payment. Must match the Token for charges on the Invoice/Subscription.
created datetime The time that payment occurred.
payment_type string The type of payment accepted by the merchant.
payment_id string The ID of the payment accepted by the merchant.
account Account The full account number.
last_digits string The last part of the account number for display purposes, generally the last four digits.
account_length integer Length of the total account number. If the full account number is submitted, this field may be left blank.
hash_type enum The algorithm used to hash the account number. If this value is not provided, Subscribe will use assume SHA1. Can be: md5 or sha1
account_hash string A hash of the full account number. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this may be left blank and the hash will be calculated by Subscribe.
note string An optional memo regarding the payment made.

Using MAP (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

MAP Flows

Military Star

Military Star Attributes

Name Type Description
object string Value is “MilitaryStar”
vid string A Globally Unique Identifier (GUID) for this object. This field is created by Subscribe.
account string The MilitaryStar account number.
account_length integer Length of the total account number. If the full account number is submitted, this field may be left blank; Vindicia will calculate it.
account_last_digits string
account_hash string A hash of the full account number. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this may be left blank and the hash will be calculated by Vindicia. The exact length and format of this string may depend upon the hash algorithm chosen. Currently this value is not returned (i.e. is null) when you fetch this object from Vindicia e.g. via fetched transactions
cid string The Customer Identification Number, of the account holder.
cid_length integer Length of the cid. If the cid is submitted, this field may be left blank; Vindicia will calculate it.
cid_last_digits string The last part of the cid for display purposes, generally the last four digits. If the cid field is provided, this may be left blank and it will be filled in by Vindicia.
cid_hash string A hash of the full cid. Any non-numeric characters should be removed prior to hashing. If the account number is provided, this may be left blank and the hash will be calculated by Vindicia. The exact length and format of this string may depend upon the hash algorithm chosen. Currently this value is not returned (i.e. is null) when you fetch this object from Vindicia e.g. via fetched transactions
hash_type enum Can be: md5 or sha1

Using Military Star (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Military Star Flows

Skrill

Skrill Attributes

Name Type Description
object string Value is “Skrill”
billing_agreement_id string The Skrill 1-Tap billing agreement identifier (rec_payment_id).
pay_from_email string The pay_from_email associated with the Skrill account.
payment_type string The Skrill payment_type code.
return_url string The URL to which you would like to redirect customers after a Skrill-based Transaction is completed.
cancel_url string The URL to which you would like to redirect customers if they do not approve payment via Skrill.

Using Skrill (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Skrill Flows

Token

Token Attributes

See Token object.

Using Tokens (Operations)

….

See Creating a new Payment Method

See Updating an existing Payment Method

See Fetching a specific Payment Method

See Listing all Payment Methods

Token Flows