{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"recurring-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\": \"`plan-id`\",\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\": \"`payer-info`\",\n \"2-1\": \"container\",\n \"2-3\": \"Container of [payer-info](doc:payer-info) properties.\",\n \"h-4\": \"Description\",\n \"0-2\": \"**Required** for Create Subscription\",\n \"2-2\": \"Optional\\n*Do not include if sending* `vaulted-shopper-id`\",\n \"3-0\": \"`payment-source`\",\n \"3-1\": \"container\",\n \"3-3\": \"Container of [payment-source](doc:payment-source) properties.\",\n \"3-2\": \"**Required** for Create Subscription if sending `payer-info`\\n\\n**Optional** if sending `vaulted-shopper-id`\",\n \"10-0\": \"`transaction-fraud-info`\",\n \"10-1\": \"container\",\n \"10-2\": \"**Required** for Create Subscription\",\n \"10-3\": \"Container of [transaction-fraud-info](doc:transaction-fraud-info) properties.\",\n \"4-0\": \"`quantity`\",\n \"5-0\": \"`soft-descriptor`\",\n \"7-0\": \"`override-trial-period-days`\",\n \"8-0\": \"`override-recurring-charge-amount`\",\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\\n**Note**: This value must be greater than **`0`**. If the value is set to **`0`**, the property is ignored and the `trial-period-days` 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\": \"`vaulted-shopper-id`\",\n \"1-1\": \"*integer*\",\n \"1-2\": \"Optional\\n*Do not include if sending* `payer-info`\",\n \"1-3\": \"ID of an existing vaulted shopper.\",\n \"11-0\": \"`auto-renew`\",\n \"13-0\": \"`next-charge-date`\",\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 is adjusted accordingly. \\n\\nFormat: yyyy-mm-dd\",\n \"9-0\": \"`override-initial-charge-amount`\",\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, any later changes to the plan's price are not applied to this subscription.\",\n \"12-0\": \"`authorized-by-shopper`\",\n \"12-1\": \"*boolean*\",\n \"12-2\": \"**Required** for SEPA Direct Debit\\n\\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\": \"`descriptor-phone-number`\",\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\": \"`level-3-data`\",\n \"15-1\": \"container\",\n \"15-2\": \"Optional\",\n \"15-3\": \"Container of [level-3-data](doc:level-3-data) properties.\",\n \"16-0\": \"`three-d-secure`\",\n \"16-1\": \"container\",\n \"16-2\": \"Optional\",\n \"16-3\": \"Container of [three-d-secure](doc:three-d-secure) properties.\",\n \"17-0\": \"`transaction-order-source`\",\n \"17-1\": \"*string*\",\n \"17-2\": \"Optional\",\n \"17-3\": \"Identifies the order type.<br />The only option is `MOTO` (**M**ail **O**rder **T**elephone **O**rder). <br />Any other option is ignored.\",\n \"18-0\": \"`initial-tax-reference`\",\n \"19-0\": \"`recurring-tax-reference`\",\n \"18-1\": \"*string*\",\n \"19-1\": \"*string*\",\n \"18-2\": \"Optional\",\n \"19-2\": \"Optional\",\n \"19-3\": \"ID of the tax quote for recurring subscription charges. For details, see [Taxes guide](https://developers.bluesnap.com/v8976-Basics/docs/taxes).\",\n \"18-3\": \"ID of the tax quote for the initial subscription charge. For details, see [Taxes guide](https://developers.bluesnap.com/v8976-Basics/docs/taxes).\"\n },\n \"cols\": 4,\n \"rows\": 20\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\": \"`plan-id`\",\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\": \"`payment-source`\",\n \"18-1\": \"container\",\n \"18-3\": \"Container of [payment-source](doc:payment-source) properties.\",\n \"18-2\": \"Container of [payment-source](doc:payment-source) properties.\",\n \"20-0\": \"`fraud-result-info`\",\n \"20-1\": \"container\",\n \"20-2\": \"*Create Subscription response only*\\n\\nContainer of [fraud-result-info](doc:fraud-result-info) properties.\",\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\\nContainer of [charge](doc:charge) properties.\",\n \"19-3\": \"ID of an existing vaulted shopper.\",\n \"19-1\": \"container\",\n \"0-0\": \"`subscription-id`\",\n \"0-3\": \"\",\n \"0-1\": \"*integer*\",\n \"0-2\": \"BlueSnap identifier for the subscription.\",\n \"2-0\": \"`vaulted-shopper-id`\",\n \"2-1\": \"*integer*\",\n \"2-2\": \"ID of an existing vaulted shopper.\",\n \"17-0\": \"`payer-info`\",\n \"17-1\": \"container\",\n \"17-2\": \"Container of [payer-info](doc:payer-info) properties.\",\n \"3-0\": \"`status`\",\n \"3-1\": \"*string*\",\n \"3-2\": \"Possible values:\\n`ACTIVE`\\n`CANCELED`\\n`ON_HOLD` (the subscription is outside its grace-period)\\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\": \"`soft-descriptor`\",\n \"5-1\": \"*string*\",\n \"5-2\": \"Description of the transaction, which appears on the shopper's credit card statement.\",\n \"7-0\": \"`charge-frequency`\",\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\": \"`trial-period-days`\",\n \"8-1\": \"*integer*\",\n \"8-2\": \"Number of days in the trial period.\\nFor example: `14`\",\n \"10-0\": \"`recurring-charge-amount`\",\n \"10-1\": \"*decimal*\",\n \"10-2\": \"Recurring amount to be charged.\\nFor example: `29.99`\",\n \"11-0\": \"`override-recurring-charge-amount`\",\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\": \"`initial-charge-amount`\",\n \"13-1\": \"*decimal*\",\n \"13-2\": \"Amount of the initial charge.\\nFor example: `99.00`\",\n \"9-0\": \"`override-trial-period-days`\",\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\": \"`override-initial-charge-amount`\",\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\": \"`auto-renew`\",\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\": \"`next-charge-date`\",\n \"16-1\": \"*string*\",\n \"16-2\": \"*Appears only if subscription is ACTIVE*\\nNext charge date.\\nFormat: yyyy-mm-dd\",\n \"6-0\": \"`descriptor-phone-number`\",\n \"6-1\": \"*string*\",\n \"6-2\": \"Description of the transaction, which appears on the shopper's credit card statement.\",\n \"21-0\": \"`level-3-data`\",\n \"21-1\": \"container\",\n \"21-2\": \"Container of [level-3-data](doc:level-3-data) properties.\",\n \"22-0\": \"`three-d-secure`\",\n \"22-1\": \"container\",\n \"22-2\": \"Container of [three-d-secure](doc:three-d-secure) properties.\",\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 \"23-0\": \"`scheduled`\",\n \"23-1\": \"*boolean*\",\n \"24-0\": \"`recurring-tax-reference`\",\n \"24-1\": \"*string*\",\n \"24-2\": \"ID of the tax quote for recurring subscription charges. For details, see [Taxes guide](https://developers.bluesnap.com/v8976-Basics/docs/taxes).\"\n },\n \"cols\": 3,\n \"rows\": 25\n}\n[/block]","updates":[],"order":42,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"61a5208deadb750070998f27","project":"57336fd5a6a9c40e00e13a0b","version":{"version":"8976-XML","version_clean":"8976.0.0-XML","codename":"3.40 Release","is_stable":false,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["61a5208deadb750070998e87","61a5208deadb750070998e88","61a5208deadb750070998e89","61a5208deadb750070998e8a","61a5208deadb750070998e8b","61a5208deadb750070998e8c","61a5208deadb750070998e8d","61a5208deadb750070998e8e","61a5208deadb750070998e8f","61a5208deadb750070998e90","61a5208deadb750070998e91","61a5208deadb750070998e92","61a5208deadb750070998e93","61a5208deadb750070998e94","61a5208deadb750070998e95","61a5208deadb750070998e96","61a5208deadb750070998e97","61a5208deadb750070998e98","61a5208deadb750070998e99","61a5208deadb750070998e9a"],"_id":"61a5208deadb750070998f48","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"60fed269718a45001c25b4a0","createdAt":"2018-04-24T15:24:22.608Z","releaseDate":"2018-04-24T15:24:22.608Z"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Resources","slug":"resources","order":16,"from_sync":false,"reference":false,"_id":"61a5208deadb750070998e93","version":"61a5208deadb750070998f48","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-10-15T16:20:51.519Z","__v":0},"user":"5beb1b96bc2003003ecd645e","createdAt":"2019-07-18T14:37:28.411Z","__v":0,"parentDoc":null}recurring-subscription
plan-id
integer
Required for Create Subscription
ID of the billing plan associated with this subscription.
vaulted-shopper-id
integer
Optional
Do not include if sending payer-info
ID of an existing vaulted shopper.
payer-info
container
Optional
Do not include if sending vaulted-shopper-id
Container of payer-info properties.
payment-source
container
Required for Create Subscription if sending payer-info
Optional if sending vaulted-shopper-id
Container of payment-source properties.
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).
soft-descriptor
string
Optional
Description of the transaction, which appears on the shopper's credit card statement. Maximum 20 characters.
descriptor-phone-number
string
Optional
Merchant's support phone number that appears on the shopper's bank statement. Maximum 20 characters.
override-trial-period-days
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 trial-period-days is used.
override-recurring-charge-amount
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.
override-initial-charge-amount
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, any later changes to the plan's price are not applied to this subscription.
transaction-fraud-info
container
Required for Create Subscription
Container of transaction-fraud-info properties.
auto-renew
boolean
Optional
Optional Update Subscription requests only
Determines whether the subscription automatically continues, or expires at the end of the current period.
authorized-by-shopper
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.
next-charge-date
string
Optional
Create/Update Subscription requests only
Next charge date.
If you change this, the date of future recurring charges is adjusted accordingly.
Format: yyyy-mm-dd
status
string
Optional
Create/Update Subscription requests only
Permitted values:ACTIVECANCELED
transaction-order-source
string
Optional
Identifies the order type.
The only option is MOTO (Mail Order Telephone Order).
Any other option is ignored.
initial-tax-reference
string
Optional
ID of the tax quote for the initial subscription charge. For details, see Taxes guide.
recurring-tax-reference
string
Optional
ID of the tax quote for recurring subscription charges. For details, see Taxes guide.
subscription-id
integer
BlueSnap identifier for the subscription.
vaulted-shopper-id
integer
ID of an existing vaulted shopper.
status
string
Possible values:ACTIVECANCELEDON_HOLD (the subscription is outside its grace-period)SUSPENDEDFINISHED (the subscription reached the plan's max-number-of-charges limit)
quantity
integer
Quantity to apply to the subscription.
Default is 1.
soft-descriptor
string
Description of the transaction, which appears on the shopper's credit card statement.
descriptor-phone-number
string
Description of the transaction, which appears on the shopper's credit card statement.
charge-frequency
string
Possible values:ONCEDAILYWEEKLYEVERY 2 WEEKSMONTHLYEVERY 2 MONTHSQUARTERLYEVERY 6 MONTHSANNUALLYEVERY 2 YEARSEVERY 3 YEARS
trial-period-days
integer
Number of days in the trial period.
For example: 14
override-trial-period-days
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.
recurring-charge-amount
decimal
Recurring amount to be charged.
For example: 29.99
override-recurring-charge-amount
decimal
Recurring amount to be charged. This overrides the charge amount defined for the associated billing plan. The override applies only to this subscription.
initial-charge-amount
decimal
Amount of the initial charge.
For example: 99.00
override-initial-charge-amount
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.
auto-renew
boolean
Determines whether the subscription automatically continues, or expires at the end of the current period.
next-charge-date
string
Appears only if subscription is ACTIVE
Next charge date.
Format: yyyy-mm-dd
fraud-result-info
container
Create Subscription response only
Container of fraud-result-info properties.
scheduled
boolean
Identifies if the transaction is a regularly scheduled event.
Possible values:truefalse (default)
Refer to Card on File Guide.
recurring-tax-reference
string
ID of the tax quote for recurring subscription charges. For details, see Taxes guide.
