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.

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"
        }
    }
}