Update subscription

PATCH https://api.ecurring.com/subscriptions/{id}

Update a subscription. In accordance with the JSON API specification any missing attribute will be interpreted as if they were included with their current value. It's therefore not neccessary to include every attribute of the subscription during a partial update.

Every attribute that can be set during the creation of a subscription can be updated using a PATCH request to the subscription's resource endpoint. With the exception of the following attributes:

mandate_code
string
Once a subscription is created it is not allowed to change the mandate code. If the mandate code changed, a new subscription should be created.
customer_id
integer
When a subscription is created the customer_id will be set as a relationship on the resource. It is not possible to change this aftwards.
subscription_plan_id
integer
When a subscription is created the subscription_plan_id will be set as a relationship on the resource. It is not possible to change this aftwards.

Parameters

Replace {id} in the URL with the identifier of the subscription.

Request attributes

mandate_accepted
boolean
Optional - Indicates whether the mandate has been accepted. Accepting the mandate is required before being able to activate a subscription.
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 status of the subscription. Possible values are active / cancelled / paused / unverified. Setting a subscription to active will required mandate_accepted to be 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 paused by setting the status to 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 sent to the customer. If the value is currently true, setting this to false will trigger a new confirmation email / text, as long the the mandate has not been accepted yet.

Examples

Activating a subscription

Activating a subscription requires nothing more than setting the status to active, as long as the mandate has been accepted.

PATCH /subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
        	"status": "active",
        	"mandate_accepted": true,
        	"mandate_accepted_date": "2017-11-01T00:00+02:00"
        }
    }
}

Pausing a subscription

Pausing a subscription is done by setting the status to paused. Optionally you can include a resume_date to automatically resume the subscription on a specific date.

PATCH /subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
        	"status": "paused",
        	"resume_date": "2018-01-01T00:00+02:00"
        }
    }
}

Resuming a subscription

To resume a paused subscription, simply change the status from paused to active.

PATCH /subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
        	"status": "active"
        }
    }
}

Cancelling a subscription

Unlike pausing, cancelling a subscription is irreversible. Once cancelled a subscription can not be activated again and a new subscription would have to be created if desired.

All future transactions will be cancelled. Any transactions that are currently in progress will still be completed, and any chargebacks on these in-progress transactions will still be followed up (if the storno retry is set in the subscription plan)

The cancel_date property will automatically be set to the date and time of cancellation.

Request

PATCH /subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
        	"status": "cancelled"
        }
    }
}

Response

{
    "links": {
        "self": "https://api.ecurring.com/subscriptions/1"
    },
    "data": {
        "type": "subscription",
        "id": "1",
        "links": {
            "self": "https://api.ecurring.com/subscriptions/1"
        },
        "attributes": {
            "mandate_code": "UNIQUE_MANDATE_REFERENCE",
            "mandate_accepted": true,
            "mandate_accepted_date": "2017-10-13T00:00:00+02:00",
            "start_date": "2017-10-13T00:00:00+02:00",
            "status": "cancelled",
            "cancel_date": "2017-11-23T17:19:04+01:00",
            "resume_date": null,
            "confirmation_page": "https://app.ecurring.com/mandate/accept/1/UNIQUE_MANDATE_REFERENCE",
            "confirmation_sent": true,
            "subscription_webhook_url": null,
            "transaction_webhook_url": null,
            "created_at": "2017-10-13T00:00:00+01:00",
            "updated_at": "2018-02-01T11:21:09+01:00"
        },
        "relationships": {
            "subscription-plan": {
                "data": {
                    "type": "subscription-plan",
                    "id": "1"
                }
            },
            "customer": {
                "data": {
                    "type": "customer",
                    "id": "1"
                }
            },
            "transactions": {
                "links": {
                    "related": "https://api.ecurring.com/subscriptions/1/transactions"
                },
                "data": []
            }
        }
    }
}

Cancelling a subscription in the future

It's also possible to have a subscription automatically be cancelled in the future. Instead of including the status attribute you supply the cancel_date attribute with a date in the future. The subscription will automatically be set to cancelled on this date.

Request

PATCH /subscriptions/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
    "data": {
        "type": "subscription",
        "id": "1",
        "attributes": {
        	"cancel_date": "2019-01-01T00:00:00+01:00"
        }
    }
}

Response

{
    "links": {
        "self": "https://api.ecurring.com/subscriptions/1"
    },
    "data": {
        "type": "subscription",
        "id": "1",
        "links": {
            "self": "https://api.ecurring.com/subscriptions/1"
        },
        "attributes": {
            "mandate_code": "UNIQUE_MANDATE_REFERENCE",
            "mandate_accepted": true,
            "mandate_accepted_date": "2017-10-13T00:00:00+02:00",
            "start_date": "2017-10-13T00:00:00+02:00",
            "status": "active",
            "cancel_date": "2019-01-01T00:00:00+01:00",
            "resume_date": null,
            "confirmation_page": "https://app.ecurring.com/mandate/accept/1/UNIQUE_MANDATE_REFERENCE",
            "confirmation_sent": true,
            "created_at": "2017-10-13T00:00:00+01:00",
            "updated_at": "2018-02-01T11:21:09+01:00"
        },
        "relationships": {
            "subscription-plan": {
                "data": {
                    "type": "subscription-plan",
                    "id": "1"
                }
            },
            "customer": {
                "data": {
                    "type": "customer",
                    "id": "1"
                }
            },
            "transactions": {
                "links": {
                    "related": "https://api.ecurring.com/subscriptions/1/transactions"
                },
                "data": []
            }
        }
    }
}