{"_id":"59a45d467ee621000fc9d429","category":{"_id":"59a45d447ee621000fc9d3c4","version":"59a45d437ee621000fc9d3b7","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-15T16:20:51.519Z","from_sync":false,"order":12,"slug":"resources","title":"Resources"},"user":"560d5913af97231900938124","parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"59a45d437ee621000fc9d3b7","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-08-28T18:13:23.840Z","releaseDate":"2017-08-28T18:13:23.840Z","categories":["59a45d447ee621000fc9d3b8","59a45d447ee621000fc9d3b9","59a45d447ee621000fc9d3ba","59a45d447ee621000fc9d3bb","59a45d447ee621000fc9d3bc","59a45d447ee621000fc9d3bd","59a45d447ee621000fc9d3be","59a45d447ee621000fc9d3bf","59a45d447ee621000fc9d3c0","59a45d447ee621000fc9d3c1","59a45d447ee621000fc9d3c2","59a45d447ee621000fc9d3c3","59a45d447ee621000fc9d3c4","59a45d447ee621000fc9d3c5","59a45d447ee621000fc9d3c6","59a45d447ee621000fc9d3c7"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.22.1","version_clean":"8976.0.0-XML","version":"8976-XML"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-27T12:19:10.487Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":78,"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    \"9-0\": \"`transaction-fraud-info`\",\n    \"9-1\": \"container\",\n    \"9-2\": \"**Required** for Create Subscription\",\n    \"9-3\": \"Container of [transaction-fraud-info](doc:transaction-fraud-info) properties.\",\n    \"4-0\": \"`quantity`\",\n    \"5-0\": \"`soft-descriptor`\",\n    \"6-0\": \"`override-trial-period-days`\",\n    \"7-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.\",\n    \"5-1\": \"*string*\",\n    \"5-2\": \"Optional\",\n    \"6-1\": \"*integer*\",\n    \"6-2\": \"Optional\",\n    \"6-3\": \"Number of days in the trial period. This will override the trial period defined for the associated billing plan. The override applies only to this subscription.\",\n    \"7-1\": \"*decimal*\",\n    \"7-2\": \"Optional\",\n    \"7-3\": \"Recurring amount to be charged. This will override 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    \"10-0\": \"`auto-renew`\",\n    \"12-0\": \"`next-charge-date`\",\n    \"13-0\": \"`status`\",\n    \"13-3\": \"Permitted values:\\n  * **ACTIVE**\\n  * **CANCELED**\",\n    \"10-1\": \"*boolean*\",\n    \"12-1\": \"*string*\",\n    \"13-1\": \"*string*\",\n    \"13-2\": \"Optional\\n*Create/Update Subscription requests only*\",\n    \"12-2\": \"Optional\\n*Create/Update Subscription requests only*\",\n    \"10-2\": \"Optional\\n*Optional Update Subscription requests only*\",\n    \"10-3\": \"Determines whether the subscription will automatically continue, or will expire at the end of the current period.\",\n    \"12-3\": \"Next charge date.\\nIf you change this, the date of future recurring charges will be adjusted accordingly.\",\n    \"8-0\": \"`override-initial-charge-amount`\",\n    \"8-1\": \"*decimal*\",\n    \"8-2\": \"Optional\",\n    \"8-3\": \"Initial amount to be charged. This will override 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 will not be applied to this subscription.\",\n    \"11-0\": \"`authorized-by-shopper`\",\n    \"11-1\": \"*boolean*\",\n    \"11-2\": \"**Required** for SEPA Direct Debit\\n\\n*Create Subscription requests only*\",\n    \"11-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](/v1.0/docs/sepa-direct-debit#section-step-1-collect-a-mandate-acceptance-from-your-shopper).\"\n  },\n  \"cols\": 4,\n  \"rows\": 14\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    \"17-0\": \"`payment-source`\",\n    \"17-1\": \"container\",\n    \"17-3\": \"Container of [payment-source](doc:payment-source) properties.\",\n    \"17-2\": \"Container of [payment-source](doc:payment-source) properties.\",\n    \"19-0\": \"`fraud-result-info`\",\n    \"19-1\": \"container\",\n    \"19-2\": \"*Create Subscription response only*\\n\\nContainer of [fraud-result-info](doc:fraud-result-info) properties.\",\n    \"19-3\": \"Container of [transaction-fraud-info](doc:transaction-fraud-info) properties.\",\n    \"18-0\": \"`charge`\",\n    \"18-2\": \"*Create Subscription response only*\\n\\nContainer of [charge](doc:charge) properties.\",\n    \"18-3\": \"ID of an existing vaulted shopper.\",\n    \"18-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    \"16-0\": \"`payer-info`\",\n    \"16-1\": \"container\",\n    \"16-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  * **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    \"6-0\": \"`charge-frequency`\",\n    \"6-1\": \"*string*\",\n    \"6-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    \"7-0\": \"`trial-period-days`\",\n    \"7-1\": \"*integer*\",\n    \"7-2\": \"Number of days in the trial period.\\nFor example: **14**\",\n    \"9-0\": \"`recurring-charge-amount`\",\n    \"9-1\": \"*decimal*\",\n    \"9-2\": \"Recurring amount to be charged.\\nFor example: **29.99**\",\n    \"10-0\": \"`override-recurring-charge-amount`\",\n    \"10-1\": \"*decimal*\",\n    \"10-2\": \"Recurring amount to be charged. This will override the charge amount defined for the associated billing plan.  The override applies only to this subscription.\",\n    \"11-0\": \"`currency`\",\n    \"11-1\": \"*string*\",\n    \"11-2\": \"Currency code (ISO 4217) of the amount to be charged. See [Currency codes](/v1.0/docs/currency-codes).\",\n    \"12-0\": \"`initial-charge-amount`\",\n    \"12-1\": \"*decimal*\",\n    \"12-2\": \"Amount of the initial charge.\\nFor example: **99.00**\",\n    \"8-0\": \"`override-trial-period-days`\",\n    \"8-1\": \"*integer*\",\n    \"8-2\": \"Number of days in the trial period. This will override the trial period defined for the associated billing plan. The override applies only to this subscription.\",\n    \"13-0\": \"`override-initial-charge-amount`\",\n    \"13-1\": \"*decimal*\",\n    \"13-2\": \"Initial amount to be charged. This will override 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 will not be applied to this subscription.\",\n    \"14-0\": \"`auto-renew`\",\n    \"14-1\": \"*boolean*\",\n    \"14-2\": \"Determines whether the subscription will automatically continue, or will expire at the end of the current period.\",\n    \"15-0\": \"`next-charge-date`\",\n    \"15-1\": \"*string*\",\n    \"15-2\": \"*Appears only if subscription is ACTIVE*\\nNext charge date.\\nFormat: yyyy-mm-dd\"\n  },\n  \"cols\": 3,\n  \"rows\": 20\n}\n[/block]","excerpt":"Contains information about a specific subscription","slug":"recurring-subscription","type":"basic","title":"recurring-subscription"}

Payment API (XML)

Card Transactions

PayPal Transactions

ACH/ECP Transactions

SEPA Direct Debit Transactions

Batch Transactions

Refunds

Vaulted Shoppers

Subscriptions

Marketplace

Wallets

Errors

Resources

Test Data & Codes

Guides & Tools

Mobile SDK

recurring-subscription

Contains information about a specific subscription

Request

Property Name
Type
Required
Description

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.

override-trial-period-days

integer

Optional

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

override-recurring-charge-amount

decimal

Optional

Recurring amount to be charged. This will override 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 will override 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 will not be 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 will automatically continue, or will expire 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 will be adjusted accordingly.

status

string

Optional
Create/Update Subscription requests only

Permitted values:

  • ACTIVE
  • CANCELED

Response

Property Name
Type
Required

subscription-id

integer

BlueSnap identifier for the subscription.

plan-id

integer

ID of the billing plan associated with this subscription.

vaulted-shopper-id

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.

soft-descriptor

string

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

charge-frequency

string

Possible values:

  • ONCE
  • DAILY
  • WEEKLY
  • EVERY 2 WEEKS
  • MONTHLY
  • EVERY 2 MONTHS
  • QUARTERLY
  • EVERY 6 MONTHS
  • ANNUALLY
  • EVERY 2 YEARS
  • EVERY 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 will override 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 will override 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. See Currency codes.

initial-charge-amount

decimal

Amount of the initial charge.
For example: 99.00

override-initial-charge-amount

decimal

Initial amount to be charged. This will override 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 will not be applied to this subscription.

auto-renew

boolean

Determines whether the subscription will automatically continue, or will expire at the end of the current period.

next-charge-date

string

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

payer-info

container

Container of payer-info properties.

payment-source

container

Container of payment-source properties.

charge

container

Create Subscription response only

Container of charge properties.

fraud-result-info

container

Create Subscription response only

Container of fraud-result-info properties.