Create subscription
POST https://api.ecurring.com/subscriptions
Add a new subscription to a customer. A subscription is essentially a relationship between a customer and a subscription plan.
There are only 2 required attributes to create a subscription. If none of the optional attributes are provided we will take care of the mandate management of this subscription.
This means that a mandate confirmation email or text will be sent to the customer, requesting the customer to accept the mandate through the method set in the subscription plan (email
, sms
or ideal
).
Take a look at the example section for more information on how to create subscriptions will existing mandates.
Creating a subscription
Creating a subscription without sending a mandate confirmation email
Creating a subscription with a pre-approved mandate that will be activated immediately
Creating a subscription with a pre-approved mandate that will start in the future
Required attributes
customer_id
integer |
The identifier of the customer. The identifer can be retrieved through the Get customers endpoint. |
subscription_plan_id
integer |
The identifier of the subscription plan. The identifer can be retrieved through the Get subscription plans endpoint. |
Optional attributes
mandate_code
string |
Optional - The unique mandate code for the subscription. Will be randomly generated if left empty. |
mandate_accepted
boolean |
Optional - Indicate whether the mandate has already been accepted through other means. Setting this to true will also prevent us from sending a mandate confirmation email to the customer.
|
mandate_accepted_date
datetime |
Optional - The date on which the mandate has been accepted. Required when mandate_accepted is set to true .
If left empty, this will be set to the date on which the customer accepts the mandate through our confirmation page. In ISO 8601 format.
|
start_date
datetime |
Optional - The start date of the subscription. Transactions will be planned relative from this date. If the start date is in the future, eCurring won't schedule any transactions before this date. Will be set to the current date if left empty. In ISO 8601 format. |
status
string |
Optional - the current status of the subscription. Possible values are active / cancelled / paused / unverified . Will be set to unverified if left empty.
Setting a subscription to active will immediately trigger the scheduling of transactions for this subscription, even if mandate_accepted is not true .
|
cancel_date
datetime |
Optional - The date on which the subscription should automatically be cancelled. In ISO 8601 format. |
resume_date
datetime |
Optional - If a subscription is being created with the status paused , this indicates on which date the subscription should be activated again. In ISO 8601 format.
|
confirmation_sent
boolean |
Optional - This can be used to indicate that a mandate confirmation was already sent to the customer through other means (outside of eCurring). If set to true , eCurring will not send a mandate confirmation email to the customer.
If this is set to true , but mandate_accepted is also true we will NOT send an email to the customer.
|
subscription_webhook_url
string |
Optional - The webhook URL we will call when the status of the subscription changes. Note: The URL must be reachable from the outside. Use a tool like ngrok for testing on your local environment. |
transaction_webhook_url
string |
Optional - The webhook URL we will call when the status of a transaction , scheduled by this subscription, changes. Note: The URL must be reachable from the outside. Use a tool like ngrok for testing on your local environment. |
success_redirect_url
string |
Optional - The URL your customer will be redirected to after accepting the mandate (and thus activating the subscription). It could make sense for the URL to contain a unique identifier - like the subscription ID - so you can show the right page referencing the subscription when your customer returns. |
metadata
mixed |
Optional - We will save this data alongside the subscription. Whenever you fetch the subscription through our API, we’ll return the metadata. This can be either a string, JSON object or JSON array. Limited to approximately 1kB. |
Examples
Creating a subscription
This will create a subscription with the mandate management handled by eCurring. Upon creation eCurring will send an email or SMS to the client asking them to confirm their mandate. This is similar to how subscriptions are created when using our sign-up form.
POST /subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "subscription",
"attributes": {
"customer_id": "1",
"subscription_plan_id": "1"
}
}
}
Creating a subscription without sending a mandate confirmation email
By including the confirmation_sent
attribute we will assume that a confirmation email was already sent, or will be sent manually after the subscription creation.
The confirmation page URL will be returned after creation of the subscription.
POST /subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "subscription",
"attributes": {
"customer_id": "1",
"subscription_plan_id": "1",
"confirmation_sent": true
}
}
}
Creating a subscription with a pre-approved mandate that will be activated immediately
By including the mandate_accepted
and mandate_accepted_date
attributes we will not require mandate confirmation from the client.
This will not immediately activate the subscription, but this can be done by setting the status
to active
.
Including a mandate_code
is optional, if it's not supplied we will generate a unique code.
It is mandatory to accept the mandate before being able to activate the subscription.
POST /subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "subscription",
"attributes": {
"customer_id": "1",
"subscription_plan_id": "1",
"mandate_code": "UNIQUE_MANDATE_REFERENCE",
"mandate_accepted": true,
"mandate_accepted_date": "2017-11-17T00:00:00+01:00",
"status": "active"
}
}
}
Creating a subscription with a pre-approved mandate that will start in the future
By including the start_date
attribute it is possible to only start scheduling transactions after this date.
The start_date
will not activate the subscription however, so make sure to activate it in advance.
POST /subscriptions HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"data": {
"type": "subscription",
"attributes": {
"customer_id": "1",
"subscription_plan_id": "1",
"mandate_code": "UNIQUE_MANDATE_REFERENCE",
"mandate_accepted": true,
"mandate_accepted_date": "2017-11-17T00:00:00+01:00",
"status": "active",
"start_date": "2018-01-01T00:00:00+01:00"
}
}
}