Skip to main content
POST
Modify a Subscription (Update)

Authorizations

​
Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

​
ID
string
required

The id or the vid of the Subscription to modify A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged.

Maximum string length: 128

Query Parameters

​
bill_prorated_period
boolean
default:false

Indicates whether to prorate for unused service portions.

​
effective_date
string<date-time>

Billing date at which changes take effect; today or nextBill.

​
new_billing_date
string<date-time>

Use this parameter to change the billing date and have Subscribe automatically prorate the charges thereby extending or shortening the billing cycle.

Note: If you don't want to have proration while changing the billing date, use the Change the Subscription Billing Day call instead. You can change the billing date to a later date (extend the billing cycle), or change the billing date to an earlier date (shorten the billing cycle) for monthly billing cycles only.

Important: To change and prorate the billing date, you must also set bill_prorated_period query parameter to true, which allows Subscribe to calculate the prorated changes.

Extend the billing cycle example: A $30 monthly subscription bills on the 1st of the month. On February 20,new_billing_date is set to the 16th of March, effective immediately. Subscribe calculates a new charge for the period 3-1 through 3-15, for an immediate prorated charge of $15. Next regular monthly billing is performed on the 16th of March.

Shorten the billing cycle example: A $30 monthly subscription bills on the 1st of the month. On February 10,new_billing_date is set to the 16th of February, effective immediately. Subscribe calculates a refund for the period 2-16 through 2-28 and applies it against the initial charge of $30 billed on February 1st. Next regular monthly billing is performed on the 16th of February.

Note: This parameter supports monthly billing cycles only. Other billing cycle frequencies such as weekly, quarterly, or yearly ar not supported.

​
dryrun
boolean
default:false

Indicates whether to commit changes or return results without execution

Body

application/json

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 call. Therefore, id and vid cannot be updated. The following changes will modify the subscribed service:

  • Plan Change: Providing a new Billing Plan will change the billing plan/schedule for the subscription as of the effective_date.
  • Replacing an existing/active Item with a new Item: Include a new Subscription Item populating the replaces attribute (in the Subscription Item) with the id of the existing item being replaced.
  • Add a new Item: Include a new Subscription Item (leaving undefined the replaced_by and replaces parameters in the Subscription Item).
  • Remove an existing Item: Include a new but empty/undefined Subscription Item populating ONLY the replaces attribute with the id of the existing item being removed. All changes will take effect as of the effective_date provided; Proration calculations, when required, will use the period between the last scheduled billing and the effective_date (calculated to whole days).
  • Apply a Campaign Code to a Subscription Item: Use the replaced_by and replaces attributes (in the Subscription Item) to apply a Campaign Code to a Subscription Item by replacing the existing item with the same item and including the Campaign Code.
​
object
enum<string>
required

Value is "Subscription".

Available options:
Subscription
​
id
string
required

A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged.

Maximum string length: 128
​
account
object
required

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 CashBox for billing. Read More in our User Guide

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.

​
status
enum<string>
required

The status of the subscription from a service and entitlement perspective.

Available options:
Pending Activation,
Active,
Pending Cancel,
Cancelled,
Expired,
Processing,
Deleted,
Dryrun,
Unknown,
Upgraded,
Legacy Suspended,
Bogus AutoBill Status
​
items
object
required

The product-based line items for the subscription.

​
vid
string

A Globally Unique Identifier (GUID) for this object. This value is generated by Vindicia.

Maximum string length: 128
​
created
string

The date/time at which the subscription was requested.

​
billing_plan
object
​
payment_method
object
​
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

​
billing_state
enum<string>

The financial state of the subscription.

Available options:
Free/Trial,
Billing Completed,
Failed To Collect,
Free Period,
Bogus BillingState
​
starts
string<datetime>

The date/time the subscription starts service.

​
ends
string<datetime>

The date/time the subscription ends service.

​
entitled_through
string<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.

​
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 CSP 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
object

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.

​
most_recent_refunds
object[]

A list of any refunds associated with the Transaction in most_recent_billing.

​
next_billing
object

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.

​
metadata
object

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
object

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

​
statement_format
enum<string>

Instructions for if/how to include the invoice statement for this subscription. Values can be Attachment, DoNotSend,Inline

Available options:
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 AutoBill 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. Only supported for Single Discount.

​
billing_plan_campaign_id
string

The unique identifier for a Campaign applied to this AutoBill’s BillingPlan. This is a read-only field returned by Vindicia for informational purposes. Values sent in with a SOAP call will be ignored. Read only. Only supported for Single Discount.

​
unkonwn_starts
boolean

Used to create a Subscription Pending Activation.

​
balance
number
​
mandate
object

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.

​
cancel_reason
object
​
policy
object

The policy object governing Subscription behavior.

​
billing_plan_discount_tickets
object[]

Only supported for Stackable Discounts.

Response

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

​
object
enum<string>
required

Value is "Subscription".

Available options:
Subscription
​
id
string
required

A unique identifier. Optionally, this object can also be identified by its vid. Using a unique custom identifier is strongly encouraged.

Maximum string length: 128
​
account
object
required

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 CashBox for billing. Read More in our User Guide

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.

​
status
enum<string>
required

The status of the subscription from a service and entitlement perspective.

Available options:
Pending Activation,
Active,
Pending Cancel,
Cancelled,
Expired,
Processing,
Deleted,
Dryrun,
Unknown,
Upgraded,
Legacy Suspended,
Bogus AutoBill Status
​
items
object
required

The product-based line items for the subscription.

​
vid
string

A Globally Unique Identifier (GUID) for this object. This value is generated by Vindicia.

Maximum string length: 128
​
created
string

The date/time at which the subscription was requested.

​
billing_plan
object
​
payment_method
object
​
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

​
billing_state
enum<string>

The financial state of the subscription.

Available options:
Free/Trial,
Billing Completed,
Failed To Collect,
Free Period,
Bogus BillingState
​
starts
string<datetime>

The date/time the subscription starts service.

​
ends
string<datetime>

The date/time the subscription ends service.

​
entitled_through
string<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.

​
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 CSP 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
object

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.

​
most_recent_refunds
object[]

A list of any refunds associated with the Transaction in most_recent_billing.

​
next_billing
object

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.

​
metadata
object

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
object

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

​
statement_format
enum<string>

Instructions for if/how to include the invoice statement for this subscription. Values can be Attachment, DoNotSend,Inline

Available options:
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 AutoBill 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. Only supported for Single Discount.

​
billing_plan_campaign_id
string

The unique identifier for a Campaign applied to this AutoBill’s BillingPlan. This is a read-only field returned by Vindicia for informational purposes. Values sent in with a SOAP call will be ignored. Read only. Only supported for Single Discount.

​
unkonwn_starts
boolean

Used to create a Subscription Pending Activation.

​
balance
number
​
mandate
object

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.

​
cancel_reason
object
​
policy
object

The policy object governing Subscription behavior.

​
billing_plan_discount_tickets
object[]

Only supported for Stackable Discounts.