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