Subscriptions
Attribute | Type | Description |
|
| Name of subscription method. |
|
| ID of the |
|
| The name of the subscription type. |
|
| Human readable ID that identifies the order easily, e.g. |
|
| A short description of the subscription. |
|
|
|
|
| Status for the subscription. Default is |
|
| ID of already created payment method. |
|
| The |
|
| Start date, |
|
| End date of subscription, |
|
| Number of |
|
| The end date of the trial period, |
|
| If |
| number | The date on which the customer was billed last, |
|
| The date on which the customer will be billed next, The next |
|
| The amount prorated. Currency set in |
|
| The date of the last time an amount was prorated. |
|
| The last amount that was billed. |
|
| The number of failed payment attempts in the subscription. See |
|
| Has this been deleted? Default is |
Note: If the user set more than one of the parameters infinite, ending_date or interval_total, the API overrides the parameters with: infinite > ending_date > interval_total.
To create a new subscription, the user needs to choose a plan.
Note: start_now must be set to true for the subscription to start automatically after creation. An associated payment_method must be in the request data.
Attribute | Type | Description |
|
| ID of the |
|
| Name of subscription method. |
|
| ID of already created payment method. |
|
| A short description. |
|
| If |
POST /subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"plan": "5931697ed57ba271c0c7de66","subscription_method": "license"}
HTTP/1.1 200 OKContent-Type: application/json{"company": {"$oid": "57ee9c71d76d431f8511142f"},"active": true,"status": "CREATED","name": "LICENSE","method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"},"deleted": false,"prorate_amount": 0.0,"_cls": "SubscriptionMethod.LicenseSubscription","plan": {"$oid": "5931697ed57ba271c0c7de66"},"payments": [],"infinite": false,"created": {"$date": 1499767018360},"user": {"$oid": "57ee9c72d76d431f85111432"},"updated": {"$date": 1499767018360}}
It is possible to start a subscription once a subscription has been created by providing the subscription_id. It is also possible to update the following information while starting the subscription. For example, maybe the subscription has been paused for awhile and the User would like to restart the subscription and update their payment method at the same time.
Path Parameter | Type | Description |
|
| ID of the subscription to start. |
Body Parameters | Type | Description |
|
| ID of an already created payment method. |
|
| Start date, |
|
| End date, |
|
| Number of intervals, set in the |
|
| If |
POST /subscriptions/<subscription_id>/start HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"payment_method": "<payment-method-id>"}
HTTP/1.1 200 OKContent-Type: application/json​{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": 0.0,"name": "LICENSE","payments": [],"status": "ACTIVE","active": true,"updated": {"$date": 1499768160086},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": false,"starting_date": {"$date": 1499854560000},"ending_date": {"$date": 1511954560000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": false,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}
To stop the subscription, the user can either choose to stop it on a chosen ending_date or immediately, if that value is missing. The remaining amount will be prorated to the user at the next current_billing_date_period_end if the Plan has prorate set true.
Path Parameter | Type | Description |
|
| ID of the subscription to start. |
Body Parameter | Type | Description |
|
| End date, |
POST /subscriptions/<subscription_id>/stop HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-Type: application/json​{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": -428.57,"name": "LICENSE","note": "A note regarding the subscription","payments": [],"status": "NON_RENEWING","active": true,"updated": {"$date": 1499773617984},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": false,"starting_date": {"$date": 1499854560000},"ending_date": {"$date": 1499860512000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": false,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}
The user can update the below fields in the subscription.
Path Parameter | Type | Description |
|
| ID of the subscription to start. |
Body Parameters | Type | Description |
|
| A short description. |
|
| Number of intervals, set in the |
|
| If |
|
| End date, |
|
| ID of an already created |
PUT /subscriptions/5964a0ead57ba2036750a3b4 HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"note": "A note regarding the subscription","infinite": true}
HTTP/1.1 200 OKContent-Type: application/json​{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": 0.0,"name": "LICENSE","note": "A note regarding the subscription","payments": [],"status": "ACTIVE","active": true,"updated": {"$date": 1499773617984},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": true,"starting_date": {"$date": 1499854560000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": false,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}
Path Parameter | Type | Description |
|
| ID of the subscription to start. |
GET /subscriptions/<subscription_id> HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-Type: application/json​{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": -428.57,"name": "LICENSE","note": "A note regarding the subscription","payments": [],"status": "NON_RENEWING","active": true,"updated": {"$date": 1499773617984},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": false,"starting_date": {"$date": 1499854560000},"ending_date": {"$date": 1499860512000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": false,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}
When your users create a recurring order plan, they still need to subscribe to it.
Attribute | Type | Description |
|
| Name of subscription method. |
|
| The name of the subscription type. Default is |
|
| A short note regarding the subscription. |
|
| ​ |
|
| Status for the subscription. This will change according to the subscription’s state. Default is |
|
| The |
|
| The |
|
| The |
|
| Start date, |
|
| End date of subscription, |
|
| The total number of |
|
| If |
|
| The date on which the customer was billed last. |
|
| The next billing date. This will also be the date on which the next current_billing_date_period_start of the subscription starts. |
|
| The amount prorated. Currency set in |
|
| The date of the last time an amount was prorated |
|
| The amount that was subtracted at the last payment. |
|
| The number of failed payment attempts in the subscription. See |
|
| The initial |
|
| List of |
You can create a Recurring Order Subscription from an existing Order by including the plan in the request.
Body Parameters | Type | Description |
|
| ID of the |
|
| ID of the Order associated with the subscription. |
|
| Name of subscription method. |
|
| A short description. |
|
| If |
|
| Starting date for the subscription if |
POST /subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"order": "58b85693d76d439fdacea41b","subscription_method": "recurring_order","plan": {"plan_method": "recurring_order", "interval_unit": "WEEK","currency": "NOK", "billing_interval": "MONTH","recurring_days": [{"day": 3, "hour": 10, "minute": 30}], "total_amount": 100}"starting_date": {"$date": 1499854560000},"payment_method": <payment_method_id>}
HTTP/1.1 200 OKContent-Type: application/json{"company": {"$oid": "57ee9c71d76d431f8511142f"},"active": true,"status": "CREATED","name": "LICENSE","method": "recurring_order","_id": {"$oid": "5964a0ead57ba2036750a3b4"},"deleted": false,"prorate_amount": 0.0,"_cls": "SubscriptionMethod.LicenseSubscription","plan": {"$oid": "5931697ed57ba271c0c7de66"},"payments": [],"infinite": false,"created": {"$date": 1499767018360},"user": {"$oid": "57ee9c72d76d431f85111432"},"updated": {"$date": 1499767018360}."order": {"$oid": "58b85693d76d439fdacea41b"},"starting_date": {"$date": 1499854560000},"payment_method": <payment_method_id>}
You can also create a Recurring Order Subscription while simultaneously creating a Plan and an Order by including the plan and the items you want to place in the order.
Body Parameters | Type | Description |
|
| ID of the |
|
| Name of subscription method. |
|
| A short description. |
|
| If |
|
| Starting date for the subscription if |
POST /subscriptions HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev​{"subscription_method": "recurring_order","plan": {"plan_method": "recurring_order", "interval_unit": "WEEK", "currency": "NOK","billing_interval": "MONTH", "recurring_days":[{"day": 3, "hour": 10, "minute": 30}],"items": [{"product": "Product ID", "quantity": 2},{"product": "Product ID", "quantity":1}]},"starting_date": 1523876899,"payment_method": <payment_method_id>}
HTTP/1.1 200 OKContent-Type: application/json{"company": {"$oid": "57ee9c71d76d431f8511142f"},"active": true,"status": "CREATED","name": "LICENSE","method": "recurring_order","_id": {"$oid": "5964a0ead57ba2036750a3b4"},"deleted": false,"prorate_amount": 0.0,"_cls": "SubscriptionMethod.LicenseSubscription","plan": {"$oid": "5931697ed57ba271c0c7de66"},"payments": [],"infinite": false,"created": {"$date": 1499767018360},"user": {"$oid": "57ee9c72d76d431f85111432"},"updated": {"$date": 1499767018360}."order": {"$oid": "58b85693d76d439fdacea41b"},"starting_date": 1523876899","payment_method": <payment_method_id>}
Important: The Subscription can start now if you add start_now=True in the subscription data; then you don't have to set the starting_date field. See the Recurring Order Plan on how to create a plan for this subscription type.
Path Parameter | Type | Description |
|
| ID of the subscription to start. |
DELETE /subscriptions/<subscription_id> HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <jwt>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
HTTP/1.1 200 OKContent-type: application/json{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": -428.57,"name": "LICENSE","note": "A note regarding the subscription","payments": [],"status": "NON_RENEWING","active": true,"updated": {"$date": 1499773617984},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": false,"starting_date": {"$date": 1499854560000},"ending_date": {"$date": 1499860512000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": true,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}
*Paths listed above and denoted with a star are accessible to both Users and Admins. Additional Admin Role paths are listed below.
Receives a list of all subscriptions associated with a company.
GET /subscriptions/search?method=license HTTP/1.1Content-Type: application/jsonAuthorization: Bearer <service-account-key>X-Builton-Api-Key: <builton-api-key>Host: api.builton.dev
Query Parameters | Type | Description |
|
| Allows for filtering of subscriptions by type of method: |
HTTP/1.1 200 OKContent-type: application/json[{"plan": {"$oid": "5931697ed57ba271c0c7de66"},"payment_method": {"$oid": "<payment-method-id>"},"user": {"$oid": "57ee9c72d76d431f85111432"},"prorate_amount": -428.57,"name": "LICENSE","note": "A note regarding the subscription","payments": [],"status": "NON_RENEWING","active": true,"updated": {"$date": 1499773617984},"_cls": "SubscriptionMethod.LicenseSubscription","infinite": false,"starting_date": {"$date": 1499854560000},"ending_date": {"$date": 1499860512000},"created": {"$date": 1499767018360},"current_billing_date_period_end": {"$date": 1502532960000},"current_billing_date_period_start": {"$date": 1499854560000},"company": {"$oid": "57ee9c71d76d431f8511142f"},"deleted": false,"method": "license","_id": {"$oid": "5964a0ead57ba2036750a3b4"}}]
