Skip to main content
Vindicia Knowledge Center

The subscription object

The subscription object

Attributes

Subscription

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 CashBox.
created datetime The date/time at which the subscription was requested.
account Account The account receiving the subscription.
billing_plan BillingPlan The billing plan assigned to this subscription. Dictates billing schedule.
payment_method PaymentMethod 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,Bogus AutoBill Status
billing_state enum The financial state of the subscription. Values can be Free/Trial,Billing Completed,Failed To Collect,Free Period,Bogus BillingState
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 SubscriptionItem[] 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 most recent billing transaction conducted or expected for this subscription.
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 Campaign code (coupon or promotion) to apply to plan-level charges, if any.
billing_plan_campaign_id string Read-only; Campaign Identifier of the active plan-level campaign associated with the provided campaign code
mandate Mandate Direct Debit mandate on file for this subscription, if any.
cancel_reason CancelReason 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 AutoBill. 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. AutoBill will not be saved if validation is requested and fails.

SubscriptionItem

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 CashBox.
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 RatePlan 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  
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).
campaign_code string The specific Campaign Code applied to this item.
campaign_id string The Campaign id related to the applied Campaign Code.
replaces SubscriptionItem SubscriptionItem replaced by this item.
replaced_by SubscriptionItem SubscriptionItem which replaced this item.

CancelReason

Name Type Description
object string Value is “CancelReason”
reason_code string The pre-defined code associated with the reason for cancelling this subscription.
description string The description associated with the specified reason_code. Read Only.
  • cURL
  • Java
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": "2016-05-27T05:52:02-07:00",
    "items": {
        "object": "List",
        "data": [
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.1",
                "index": 0,
                "product": {`...`},
                "quantity": 1,
                "created": "2016-05-27T05:52:02-07:00",
                "starts": "2016-05-27T00:00:00-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.2",
                "index": 1,
                "product": {`...`},
                "quantity": 1,
                "created": "2016-05-27T05:52:02-07:00",
                "starts": "2016-05-27T00:00:00-07:00"
            }
        ],
        "total_count": 2
    },
    "minimum_commitment": 0,
    "notify_on_transition": false,
    "next_billing": {`...`}
}	
          
{
    "object": "Subscription",
    "id": "sub_1234",
    "vid": "796db5f7f7a1dea312f6c7e1393aebec1f1ecf1b",
    "account": {`...`},
    "billing_plan": {`...`},
    "payment_method": {`...`},
    "currency": "USD",
    "description": "Subscription_1234",
    "status": "Active",
    "billing_state": "Good Standing",
    "starts": "2016-05-27T05:52:02-07:00",
    "items": {
        "object": "List",
        "data": [
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.1",
                "index": 0,
                "product": {`...`},
                "quantity": 1,
                "created": "2016-05-27T05:52:02-07:00",
                "starts": "2016-05-27T00:00:00-07:00"
            },
            {
                "object": "SubscriptionItem",
                "id": "sub_1234.2",
                "index": 1,
                "product": {`...`},
                "quantity": 1,
                "created": "2016-05-27T05:52:02-07:00",
                "starts": "2016-05-27T00:00:00-07:00"
            }
        ],
        "total_count": 2
    },
    "minimum_commitment": 0,
    "notify_on_transition": false,
    "next_billing": {`...`}
}
          

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top