{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"subscription","type":"basic","slug":"recurring-subscription","excerpt":"Contains information about a specific subscription","body":"###Request\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Required\",\n    \"0-0\": \"`planId`\",\n    \"0-1\": \"*integer*\",\n    \"h-3\": \"Description\",\n    \"0-3\": \"ID of the billing [plan](doc:plan) associated with this subscription.\",\n    \"2-0\": \"`payerInfo`\",\n    \"2-1\": \"container\",\n    \"2-3\": \"Refer to [payerInfo](doc:payer-info).\",\n    \"h-4\": \"Description\",\n    \"0-2\": \"**Required** for Create Subscription\",\n    \"2-2\": \"Optional\\n*Do not include if sending* `vaultedShopperId`\",\n    \"3-0\": \"`paymentSource`\",\n    \"3-1\": \"container\",\n    \"3-3\": \"Refer to [paymentSource](doc:payment-source).\",\n    \"3-2\": \"**Required** for Create Subscription if sending `payerInfo`\\n\\n**Optional** if sending `vaultedShopperId`\",\n    \"10-0\": \"`transactionFraudInfo`\",\n    \"10-1\": \"container\",\n    \"10-2\": \"**Required** for Create Subscription\",\n    \"10-3\": \"Refer to [transactionFraudInfo](doc:transaction-fraud-info).\",\n    \"4-0\": \"`quantity`\",\n    \"5-0\": \"`softDescriptor`\",\n    \"7-0\": \"`overrideTrialPeriodDays`\",\n    \"8-0\": \"`overrideRecurringChargeAmount`\",\n    \"4-1\": \"*integer*\",\n    \"4-2\": \"Optional\\n*Create Subscription requests only*\",\n    \"4-3\": \"Quantity to apply to the subscription.\\nDefault is **1**.\\nFor example, to charge for 10 users in this subscription, set the quantity to 10. If the associated plan's price is $30 per month, then this subscription's recurring payment will be $300 per month (10 x $30).\",\n    \"5-3\": \"Description of the transaction, which appears on the shopper's credit card statement. Maximum 20 characters.\",\n    \"5-1\": \"*string*\",\n    \"5-2\": \"Optional\",\n    \"7-1\": \"*integer*\",\n    \"7-2\": \"Optional\",\n    \"7-3\": \"Number of days in the trial period. This overrides the trial period defined for the associated billing plan. The override applies only to this subscription.\\n\\n**Note**: This value must be greater than **`0`**.  If the value is set to **`0`**, the property is ignored and the `trialPeriodDays` is used.\",\n    \"8-1\": \"*decimal*\",\n    \"8-2\": \"Optional\",\n    \"8-3\": \"Recurring amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.\",\n    \"1-0\": \"`vaultedShopperId`\",\n    \"1-1\": \"*integer*\",\n    \"1-2\": \"Optional\\n*Do not include if sending* `payerInfo`\",\n    \"1-3\": \"ID of an existing vaulted shopper.\",\n    \"11-0\": \"`autoRenew`\",\n    \"13-0\": \"`nextChargeDate`\",\n    \"14-0\": \"`status`\",\n    \"14-3\": \"Permitted values:\\n  * **ACTIVE**\\n  * **CANCELED**\",\n    \"11-1\": \"*boolean*\",\n    \"13-1\": \"*string*\",\n    \"14-1\": \"*string*\",\n    \"14-2\": \"Optional\\n*Create/Update Subscription requests only*\",\n    \"13-2\": \"Optional\\n*Create/Update Subscription requests only*\",\n    \"11-2\": \"Optional\\n*Optional Update Subscription requests only*\",\n    \"11-3\": \"Determines whether the subscription automatically continues, or expires at the end of the current period.\",\n    \"13-3\": \"Next charge date.\\nIf you change this, the date of future recurring charges are adjusted accordingly. Format: yyyy-mm-dd\",\n    \"9-0\": \"`overrideInitialChargeAmount`\",\n    \"9-1\": \"*decimal*\",\n    \"9-2\": \"Optional\",\n    \"9-3\": \"Initial amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.\\nIf you override the price by this property in the request, then any later changes to the plan's price are not applied to this subscription.\",\n    \"12-0\": \"`authorizedByShopper`\",\n    \"12-1\": \"*boolean*\",\n    \"12-2\": \"**Required** for SEPA Direct Debit \\n*Create Subscription requests only*\",\n    \"12-3\": \"Value must be **true**.\\n\\nPass this parameter to indicate that you have obtained the shopper's authorization of the [SEPA Direct Debit mandate](/docs/sepa-direct-debit#section-step-1-collect-a-mandate-acceptance-from-your-shopper).\",\n    \"6-0\": \"`descriptorPhoneNumber`\",\n    \"6-1\": \"*string*\",\n    \"6-2\": \"Optional\",\n    \"6-3\": \"Merchant's support phone number that appears on the shopper's bank statement. Maximum 20 characters.\",\n    \"15-0\": \"`level3Data`\",\n    \"15-1\": \"container\",\n    \"15-2\": \"Optional\",\n    \"15-3\": \"Refer to [level3Data](doc:level3data).\",\n    \"16-0\": \"`threeDSecure`\",\n    \"16-1\": \"container\",\n    \"16-2\": \"Optional\",\n    \"16-3\": \"Refer to [threeDSecure](doc:threedsecure).\",\n    \"17-0\": \"`transactionOrderSource`\",\n    \"17-1\": \"*string*\",\n    \"17-3\": \"Refer to [cardTransaction](https://developers.bluesnap.com/v8976-JSON/docs/card-transaction)\",\n    \"17-2\": \"Optional\"\n  },\n  \"cols\": 4,\n  \"rows\": 18\n}\n[/block]\n###Response\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Required\",\n    \"1-0\": \"`planId`\",\n    \"1-1\": \"*integer*\",\n    \"h-3\": \"Description\",\n    \"1-3\": \"ID of the billing [plan](doc:plan) associated with this subscription.\",\n    \"h-4\": \"Description\",\n    \"1-2\": \"ID of the billing [plan](doc:plan) associated with this subscription.\",\n    \"18-0\": \"`paymentSource`\",\n    \"18-1\": \"container\",\n    \"18-3\": \"Container of [payment-source](doc:payment-source) properties.\",\n    \"18-2\": \"Refer to [paymentSource](doc:payment-source).\",\n    \"20-0\": \"`fraudResultInfo`\",\n    \"20-1\": \"container\",\n    \"20-2\": \"*Create Subscription response only*\\n\\nRefer to [fraudResultInfo](doc:fraud-result-info).\",\n    \"20-3\": \"Container of [transaction-fraud-info](doc:transaction-fraud-info) properties.\",\n    \"19-0\": \"`charge`\",\n    \"19-2\": \"*Create Subscription response only*\\n\\nRefer to [charge](doc:charge).\",\n    \"19-3\": \"ID of an existing vaulted shopper.\",\n    \"19-1\": \"container\",\n    \"0-0\": \"`subscriptionId`\",\n    \"0-3\": \"\",\n    \"0-1\": \"*integer*\",\n    \"0-2\": \"BlueSnap identifier for the subscription.\",\n    \"2-0\": \"`vaultedShopperId`\",\n    \"2-1\": \"*integer*\",\n    \"2-2\": \"ID of an existing vaulted shopper.\",\n    \"17-0\": \"`payerInfo`\",\n    \"17-1\": \"container\",\n    \"17-2\": \"Refer to [payerInfo](doc:payer-info).\",\n    \"3-0\": \"`status`\",\n    \"3-1\": \"*string*\",\n    \"3-2\": \"Possible values:\\n`ACTIVE`\\n`CANCELED`\\n`SUSPENDED`\\n`FINISHED` (the subscription reached the plan's `max-number-of-charges` limit)\",\n    \"4-0\": \"`quantity`\",\n    \"4-1\": \"*integer*\",\n    \"4-2\": \"Quantity to apply to the subscription.\\nDefault is `1`.\",\n    \"5-0\": \"`softDescriptor`\",\n    \"5-1\": \"*string*\",\n    \"5-2\": \"Description of the transaction, which appears on the shopper's credit card statement.\",\n    \"7-0\": \"`chargeFrequency`\",\n    \"7-1\": \"*string*\",\n    \"7-2\": \"Possible values:\\n`ONCE`\\n`DAILY`\\n`WEEKLY`\\n`EVERY 2 WEEKS`\\n`MONTHLY`\\n`EVERY 2 MONTHS`\\n`QUARTERLY`\\n`EVERY 6 MONTHS`\\n`ANNUALLY`\\n`EVERY 2 YEARS`\\n`EVERY 3 YEARS`\",\n    \"8-0\": \"`trialPeriodDays`\",\n    \"8-1\": \"*integer*\",\n    \"8-2\": \"Number of days in the trial period.\\nFor example: `14`\",\n    \"10-0\": \"`recurringChargeAmount`\",\n    \"10-1\": \"*decimal*\",\n    \"10-2\": \"Recurring amount to be charged.\\nFor example: `29.99`\",\n    \"11-0\": \"`overrideRecurringChargeAmount`\",\n    \"11-1\": \"*decimal*\",\n    \"11-2\": \"Recurring amount to be charged. This overrides the charge amount defined for the associated billing plan.  The override applies only to this subscription.\",\n    \"12-0\": \"`currency`\",\n    \"12-1\": \"*string*\",\n    \"12-2\": \"Currency code (ISO 4217) of the amount to be charged. Refer to [Currency codes](/docs/currency-codes).\",\n    \"13-0\": \"`initialChargeAmount`\",\n    \"13-1\": \"*decimal*\",\n    \"13-2\": \"Amount of the initial charge.\\nFor example: `99.00`\",\n    \"9-0\": \"`overrideTrialPeriodDays`\",\n    \"9-1\": \"*integer*\",\n    \"9-2\": \"Number of days in the trial period. This overrides the trial period defined for the associated billing plan. The override applies only to this subscription.\",\n    \"14-0\": \"`overrideInitialChargeAmount`\",\n    \"14-1\": \"*decimal*\",\n    \"14-2\": \"Initial amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.\\nIf you override the price, any later changes to the plan's price are not applied to this subscription.\",\n    \"15-0\": \"`autoRenew`\",\n    \"15-1\": \"*boolean*\",\n    \"15-2\": \"Determines whether the subscription automatically continues, or expires at the end of the current period.\",\n    \"16-0\": \"`nextChargeDate`\",\n    \"16-1\": \"*string*\",\n    \"16-2\": \"*Appears only if subscription is ACTIVE*\\nNext charge date.\\nFormat: yyyy-mm-dd\",\n    \"6-0\": \"`descriptorPhoneNumber`\",\n    \"6-1\": \"*string*\",\n    \"6-2\": \"Merchant's support phone number that appears on the shopper's bank statement.\",\n    \"21-0\": \"`level3Data`\",\n    \"21-1\": \"container\",\n    \"21-2\": \"Refer to [level3Data](doc:level3data).\",\n    \"22-0\": \"`threeDSecure`\",\n    \"22-1\": \"container\",\n    \"22-2\": \"Refer to [threeDSecure](doc:threedsecure).\",\n    \"23-0\": \"`scheduled`\",\n    \"23-1\": \"*boolean*\",\n    \"23-2\": \"Identifies if the transaction is a regularly scheduled event.\\n\\nPossible values:\\n`TRUE` \\n`FALSE` (default)\\n\\nRefer to [Card on File Guide](doc:card-on-file-guide).\"\n  },\n  \"cols\": 3,\n  \"rows\": 24\n}\n[/block]","updates":[],"order":40,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5e5d3aa2dc4d35003d784d8f","project":"57336fd5a6a9c40e00e13a0b","version":{"version":"8976-JSON","version_clean":"8976.0.0-JSON","codename":"Live","is_stable":false,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5e5d3aa2dc4d35003d784cf0","5e5d3aa2dc4d35003d784cf1","5e5d3aa2dc4d35003d784cf2","5e5d3aa2dc4d35003d784cf3","5e5d3aa2dc4d35003d784cf4","5e5d3aa2dc4d35003d784cf5","5e5d3aa2dc4d35003d784cf6","5e5d3aa2dc4d35003d784cf7","5e5d3aa2dc4d35003d784cf8","5e5d3aa2dc4d35003d784cf9","5e5d3aa2dc4d35003d784cfa","5e5d3aa2dc4d35003d784cfb","5e5d3aa2dc4d35003d784cfc","5e5d3aa2dc4d35003d784cfd","5e5d3aa2dc4d35003d784cfe","5e5d57ed1362cf0064910881","5e7a7ac40efab8003ae688c3"],"_id":"5e5d3aa2dc4d35003d784d9d","project":"57336fd5a6a9c40e00e13a0b","__v":2,"forked_from":"5c6c23e4735b81006177d0a4","createdAt":"2018-04-24T15:22:41.561Z","releaseDate":"2018-04-24T15:22:41.561Z"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"JSON Objects","slug":"resources","order":13,"from_sync":false,"reference":false,"_id":"5e5d3aa2dc4d35003d784cfb","version":"5e5d3aa2dc4d35003d784d9d","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-10-15T16:20:51.519Z","__v":0},"user":"5beb1b96bc2003003ecd645e","createdAt":"2019-07-18T15:00:07.315Z","__v":0,"parentDoc":null}

subscription

Contains information about a specific subscription

Request

Property Name
Type
Required
Description

planId

integer

Required for Create Subscription

ID of the billing plan associated with this subscription.

vaultedShopperId

integer

Optional
Do not include if sending payerInfo

ID of an existing vaulted shopper.

payerInfo

container

Optional
Do not include if sending vaultedShopperId

Refer to payerInfo.

paymentSource

container

Required for Create Subscription if sending payerInfo

Optional if sending vaultedShopperId

Refer to paymentSource.

quantity

integer

Optional
Create Subscription requests only

Quantity to apply to the subscription.
Default is 1.
For example, to charge for 10 users in this subscription, set the quantity to 10. If the associated plan's price is $30 per month, then this subscription's recurring payment will be $300 per month (10 x $30).

softDescriptor

string

Optional

Description of the transaction, which appears on the shopper's credit card statement. Maximum 20 characters.

descriptorPhoneNumber

string

Optional

Merchant's support phone number that appears on the shopper's bank statement. Maximum 20 characters.

overrideTrialPeriodDays

integer

Optional

Number of days in the trial period. This overrides the trial period defined for the associated billing plan. The override applies only to this subscription.

Note: This value must be greater than 0. If the value is set to 0, the property is ignored and the trialPeriodDays is used.

overrideRecurringChargeAmount

decimal

Optional

Recurring amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.

overrideInitialChargeAmount

decimal

Optional

Initial amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.
If you override the price by this property in the request, then any later changes to the plan's price are not applied to this subscription.

transactionFraudInfo

container

Required for Create Subscription

autoRenew

boolean

Optional
Optional Update Subscription requests only

Determines whether the subscription automatically continues, or expires at the end of the current period.

authorizedByShopper

boolean

Required for SEPA Direct Debit
Create Subscription requests only

Value must be true.

Pass this parameter to indicate that you have obtained the shopper's authorization of the SEPA Direct Debit mandate.

nextChargeDate

string

Optional
Create/Update Subscription requests only

Next charge date.
If you change this, the date of future recurring charges are adjusted accordingly. Format: yyyy-mm-dd

status

string

Optional
Create/Update Subscription requests only

Permitted values:

  • ACTIVE
  • CANCELED

level3Data

container

Optional

Refer to level3Data.

threeDSecure

container

Optional

Refer to threeDSecure.

transactionOrderSource

string

Optional

Refer to cardTransaction

Response

Property Name
Type
Required

subscriptionId

integer

BlueSnap identifier for the subscription.

planId

integer

ID of the billing plan associated with this subscription.

vaultedShopperId

integer

ID of an existing vaulted shopper.

status

string

Possible values:
ACTIVE
CANCELED
SUSPENDED
FINISHED (the subscription reached the plan's max-number-of-charges limit)

quantity

integer

Quantity to apply to the subscription.
Default is 1.

softDescriptor

string

Description of the transaction, which appears on the shopper's credit card statement.

descriptorPhoneNumber

string

Merchant's support phone number that appears on the shopper's bank statement.

chargeFrequency

string

Possible values:
ONCE
DAILY
WEEKLY
EVERY 2 WEEKS
MONTHLY
EVERY 2 MONTHS
QUARTERLY
EVERY 6 MONTHS
ANNUALLY
EVERY 2 YEARS
EVERY 3 YEARS

trialPeriodDays

integer

Number of days in the trial period.
For example: 14

overrideTrialPeriodDays

integer

Number of days in the trial period. This overrides the trial period defined for the associated billing plan. The override applies only to this subscription.

recurringChargeAmount

decimal

Recurring amount to be charged.
For example: 29.99

overrideRecurringChargeAmount

decimal

Recurring amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.

currency

string

Currency code (ISO 4217) of the amount to be charged. Refer to Currency codes.

initialChargeAmount

decimal

Amount of the initial charge.
For example: 99.00

overrideInitialChargeAmount

decimal

Initial amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.
If you override the price, any later changes to the plan's price are not applied to this subscription.

autoRenew

boolean

Determines whether the subscription automatically continues, or expires at the end of the current period.

nextChargeDate

string

Appears only if subscription is ACTIVE
Next charge date.
Format: yyyy-mm-dd

payerInfo

container

Refer to payerInfo.

paymentSource

container

Refer to paymentSource.

charge

container

Create Subscription response only

Refer to charge.

fraudResultInfo

container

Create Subscription response only

Refer to fraudResultInfo.

level3Data

container

Refer to level3Data.

threeDSecure

container

Refer to threeDSecure.

scheduled

boolean

Identifies if the transaction is a regularly scheduled event.

Possible values:
TRUE
FALSE (default)

Refer to Card on File Guide.