How-to use subscriptions
Create subscriptions
Create subscription plan
The first step to be able to create subscriptions is create the plan.
Subscription plan defines the way in which an order is charged for a specific product group
The following parameters must be sent to /order_plans endpoint to create the plan:
| Field | Description |
|---|---|
| name | Name of the subscription plan |
| description | Description of the subscription plan |
| period_count | Number of periods: always = 1 |
| frequency | Number of days to renew the subscription |
| state | Status of the subscription plan (ACTIVE, CANCELED or SUSPENDED) |
| projectID | Internal identifier of the project where subscription plan applies |
| country | Country in ISO code where subscription plan applies |
| categoryID | Internal identifier of product's category where subscription plan can be executed |
| discount | Percentage of discount that will be applied in the first order |
Example:
curl --request POST \
--url 'https://api.scalefast.com/order_plans' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data request_data=%7B%22categoryID%22%3A%20%22CATEGORY_ID%22%2C%22country%22%3A%20%22US%2CEN%22%2C%22description%22%3A%20%22My%20subscription%20plan%20description%22%2C%22discount%22%3A%20%2225%22%2C%22frequency%22%3A%20%2230%22%2C%22name%22%3A%20%22My%20subscription%20plan%22%2C%22period_count%22%3A%20%221%22%2C%22projectID%22%3A%20%22PROJECT_ID%22%2C%22state%22%3A%20%22ACTIVE%22%7D
If you need more info about subscription plan endpoint, click here
Create order
Once we have the plan, the next step is to create an order that contains the products that are in a subscription plan.
You can see all the info related to orders endpoint here
With the order info we will be able to create the subscription.
Create subscription
Once we have the plan and the order, we can create the subscription.
To create a subscription we need to send the following parameters to /subscriptions endpoint:
| Field | Description |
|---|---|
| customerID | Internal identifier of the customer |
| infoID | Internal identifier of the customer billing info |
| orderID | Internal identifier of the order |
| order_planID | Internal identifier of subscription plan |
| paymentID | Internal identifier of the payment |
| periods_left | Number of periods left |
| shippingID | Internal identifier of the shipping |
| shipping_infoID | Internal identifier of the customer shipping info |
| cart_infos | Object |
| cart_infos.currency | Main currency of the order (ISO code) |
| cart_infos.license | Product price license: always 5 |
| cart_infos.productID | Internal identifier of the product |
| cart_infos.quantity | Quantity of the product |
| cart_infos.type | Cart type: SUBSCRIPTION |
Example:
curl --request POST \
--url 'https://api.scalefast.com/order_subscriptions' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data request_data=%7B%22cart_infos%22%3A+%5B%7B%22currency%22%3A+%22EUR%22%2C%22license%22%3A+%225%22%2C%22productID%22%3A+%22PRODUCT_ID%22%2C%22quantity%22%3A+1%2C%22type%22%3A+%22SUBSCRIPTION%22%7D%5D%2C%22customerID%22%3A+%22CUSTOMER_ID%22%2C%22infoID%22%3A+%22INFO_ID%22%2C%22orderID%22%3A+%22ORDER_ID%22%2C%22order_planID%22%3A+SUBSCRIPTION_PLAN_ID%2C%22paymentID%22%3A+%221%22%2C%22periods_left%22%3A+1%2C%22shippingID%22%3A+%22UPS%22%2C%22shipping_infoID%22%3A+%22SHIPPING_INFO_ID%22%7D
If you need more info about subscriptions endpoint, click here
Disable subscription plan
In order to disable a subscription plan, you have to do a PUT API call to /order_plan/planID endpoint
If you need more info about subscription plan endopint, click here
Example:
curl --request PUT \
--url 'https://api.scalefast.com/order_plan/SUBSCRIPTION_PLAN_ID?access_token=ACCESS_TOKEN&clientID=CLIENT_ID' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data request_data=%7B%22state%22%3A%22CANCELED%22%7D
Response:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"order_planID": SUBSCRIPTION_PLAN_ID
}
}
Cancel subscription
If you want to cancel a subscription, you have to do a PUT API call to /order_subscription/subscriptionID endpoint
If you need more info about subscription endopint, click here
Example:
curl --request PUT \
--url 'https://api.scalefast.com/order_subscription/SUBSCRIPTION_ID?access_token=ACCESS_TOKEN&clientID=CLIENT_ID' \
--header 'accept: application/json' \
--header 'content-type: application/x-www-form-urlencoded' \
--data request_data=%7B%22state%22%3A%22CANCELED%22%7D
Response:
{
"result": {
"status": "OK",
"errcode": "0",
"msg": ""
},
"response_data": {
"subscriptionID": SUBSCRIPTION_ID
}
}
Get all subscriptions
In order to get all subscriptions you have, you will need to make a GET API call to /order_subscriptions endpoint:
Example:
curl --request GET \
--url 'https://api.scalefast.com/order_subscriptions?clientID=CLIENT_ID&access_token=ACCESS_TOKEN' \
--header 'accept: application/json'
Response:
{
"result":{
"status":"OK",
"errcode":"0",
"msg":""
},
"response_data":{
"count":"1718",
"subscriptions":[
{
"subscriptionID":"SUBSCRIPTION_ID",
"customerID":"CUSTOMER_ID",
"periods_left":"1",
"creation_date":"2015-01-01 14:21:09",
"renewal_date":"2015-02-01 14:21:09",
"infoID":"INFO_ID",
"shipping_infoID":"SHIPPING_INFO_ID",
"paymentID":"PAYMENT_ID",
"order_planID":"ORDER_PLAN_ID",
"renewal_count":"0",
"resellerID":"RESELLER_ID",
"shippingID":"SHIPPING_ID",
"payment_method":"PAYMENT_METHOD",
"last_orderID":"LAST_ORDER_ID",
"voucher":"",
"renewal_date_changes":"0",
"latest_period_date":"2015-01-01 14:21:09",
"state":"ONGOING",
"order_plan":{
"order_planID":"ORDER_PLAN_ID",
"name":"Delivery every 30 days",
"description":"Delivery every 30 days",
"period_count":"1",
"creation_date":"2014-10-05",
"creation_time":"01:19:07",
"frequency":"30",
"categoryID":"CATEGORY_ID",
"discount":"20",
"state":"ACTIVE",
"country":"REU",
"projectID":"PROJECT_ID"
},
"cart_infos":[
{
"cart_productID":"CART_PRODUCT_ID",
"cartID":"CART_ID",
"productID":"PRODUCT_ID",
"quantity":"1",
"currency":"EUR",
"percent_vat":0,
"type":"SUBSCRIPTION",
"image":"IMAGE",
"price":"25",
"amount":25,
"old_amount":0,
"title":"PRODUCT_NAME",
"short_desc":"PRODUCT_DESC",
"license":"5"
}
],
"customer_infos":{
"billing_info":{
"infoID":"",
"firstname":"",
"lastname":"",
"birthday":"",
"profession":"",
"mobile":"",
"civility":"",
"email":"",
"address":"",
"zipcode":"",
"city":"",
"country":"",
"phone":"",
"fax":"",
"message":"",
"public_info":"",
"address2":"",
"state":""
},
"shipping_info":{
"infoID":"",
"firstname":"",
"lastname":"",
"birthday":"",
"profession":"",
"mobile":"",
"civility":"",
"email":"",
"address":"",
"zipcode":"",
"city":"",
"country":"",
"phone":"",
"fax":"",
"message":"",
"public_info":"",
"address2":"",
"state":""
}
},
"subs_transactions":[
{
"trans_id":"TRANSACTION_ID",
"creation_date":"2015-01-01",
"creation_time":"14:21:09",
"amount":"20",
"productID":"PRODUCT_ID",
"frequency":"30",
"title":"PRODUCT_NAME"
}
],
"shipment_infos":[
{
"address":"ADDRESS",
"address_name":"ADDRESS_NAME",
"delivery_date":null,
"delivery_message":"Waiting for shipping",
"url_tracking":"",
"details":[
{
"orderID":"ORDER_ID",
"shipment_type":"physical",
"quantity":"1",
"productID":"PRODUCT_ID",
"shippingID":"SHIPPING_ID",
"title":"PRODUCT_NAME",
"image":"IMAGE"
}
]
}
]
},
...
]
}
}
Get all subscriptions of a plan
In order to get all subscriptions of a plan, you will need to make a GET API call to /order_plan/planID/order_subscriptions endpoint:
Example:
curl --request GET \
--url 'https://api.scalefast.com/order_plan/SUBSCRIPTION_PLAN_ID/order_subscriptions?clientID=CLIENT_ID&access_token=ACCESS_TOKEN' \
--header 'accept: application/json'
Response:
{
"result":{
"status":"OK",
"errcode":"0",
"msg":""
},
"response_data":{
"count":"1718",
"subscriptions":[
{
"subscriptionID":"SUBSCRIPTION_ID",
"customerID":"CUSTOMER_ID",
"periods_left":"1",
"creation_date":"2015-01-01 14:21:09",
"renewal_date":"2015-02-01 14:21:09",
"infoID":"INFO_ID",
"shipping_infoID":"SHIPPING_INFO_ID",
"paymentID":"PAYMENT_ID",
"order_planID":"ORDER_PLAN_ID",
"renewal_count":"0",
"resellerID":"RESELLER_ID",
"shippingID":"SHIPPING_ID",
"payment_method":"PAYMENT_METHOD",
"last_orderID":"LAST_ORDER_ID",
"voucher":"",
"renewal_date_changes":"0",
"latest_period_date":"2015-01-01 14:21:09",
"state":"ONGOING",
"order_plan":{
"order_planID":"ORDER_PLAN_ID",
"name":"Delivery every 30 days",
"description":"Delivery every 30 days",
"period_count":"1",
"creation_date":"2014-10-05",
"creation_time":"01:19:07",
"frequency":"30",
"categoryID":"CATEGORY_ID",
"discount":"20",
"state":"ACTIVE",
"country":"REU",
"projectID":"PROJECT_ID"
},
"cart_infos":[
{
"cart_productID":"CART_PRODUCT_ID",
"cartID":"CART_ID",
"productID":"PRODUCT_ID",
"quantity":"1",
"currency":"EUR",
"percent_vat":0,
"type":"SUBSCRIPTION",
"image":"IMAGE",
"price":"25",
"amount":25,
"old_amount":0,
"title":"PRODUCT_NAME",
"short_desc":"PRODUCT_DESC",
"license":"5"
}
],
"customer_infos":{
"billing_info":{
"infoID":"",
"firstname":"",
"lastname":"",
"birthday":"",
"profession":"",
"mobile":"",
"civility":"",
"email":"",
"address":"",
"zipcode":"",
"city":"",
"country":"",
"phone":"",
"fax":"",
"message":"",
"public_info":"",
"address2":"",
"state":""
},
"shipping_info":{
"infoID":"",
"firstname":"",
"lastname":"",
"birthday":"",
"profession":"",
"mobile":"",
"civility":"",
"email":"",
"address":"",
"zipcode":"",
"city":"",
"country":"",
"phone":"",
"fax":"",
"message":"",
"public_info":"",
"address2":"",
"state":""
}
},
"subs_transactions":[
{
"trans_id":"TRANSACTION_ID",
"creation_date":"2015-01-01",
"creation_time":"14:21:09",
"amount":"20",
"productID":"PRODUCT_ID",
"frequency":"30",
"title":"PRODUCT_NAME"
}
],
"shipment_infos":[
{
"address":"ADDRESS",
"address_name":"ADDRESS_NAME",
"delivery_date":null,
"delivery_message":"Waiting for shipping",
"url_tracking":"",
"details":[
{
"orderID":"ORDER_ID",
"shipment_type":"physical",
"quantity":"1",
"productID":"PRODUCT_ID",
"shippingID":"SHIPPING_ID",
"title":"PRODUCT_NAME",
"image":"IMAGE"
}
]
}
]
},
...
]
}
}
Updated over 4 years ago