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

An introduction

Basics

Customers

Invoice Lines

Invoices

Subscription Plans

Subscriptions

Transactions