Part 3. Cloud API: APP Service APIs

Retention Endpoints

Click an ▶ API endpoint to expand/collapse its content.
GET/retentions
Purpose: Gets the list of subscription plans and the list of pricing based on the subscription plan.
Notes
Based on different plans, call this API to get the information of Plan Parameter, Pricing, Retention Period, and so on.
Request Method
GET
Changelog
Aug 21, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to take further actions.
Request Parameters
None.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
retentions Array Get the list of the pricing plan.
Return Values in Retention Array
Fields Type Description
retention_id Integer The ID number of the Retention Pricing Plan.
retention_name String The name of the Retention Pricing Plan.
retention_cost Integer The price of the Retention Pricing Plan.
retention_days Integer The retention period of the Retention Pricing Plan.
retention_sequence Integer The sequence of the Retention Pricing Plan.
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "retentions": [{
    "retention_id":"c92be72d-40fc-462f-ae52-9e997e514277",
    "retention_name": "30-day retention period",
    "retention_cost": 500,
    "retention_days": 50,
    "retention_sequence": 3
  }]
}
Unique Error Message of this API
None.

▲ Top

POST/retentions/:retention_id/account/:account_id
Purpose: Invoked to call the purchased plan of the account.
Request Method
POST
Changelog
Aug 21, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The ID number of the account.
Required retention_id String The ID number of retention_id plan.
Required order_name String The name of the purchaser.
Required order_amount Integer The price of the plan.
Required order_tax Integer The tax price of the plan.
Required order_address String The contact address of the purchaser.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
order_id String The ID number of the purchaser’s order pricing plan.
order_status Integer The order status.
  • 0 = Unpaid
  • 1 = Paid
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "order_id": "c92be72d-40fc-462f-ae52-9e997e514277",
  "order_status": 0
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.
400 INVALID_RETENTION_ID The retention_id does not exist.

▲ Top

GET/retentions/orders/:order_id
Purpose: Gets the information of the order.
Notes
Based on the order_id: get the information of the purchaser, order price, tax price, contact address, retention period, payment status, payment method, and so on.
Request Method
GET
Changelog
Aug 21, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required order_id String The ID number of the order.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
order_name String The purchaser of the order.
order_cost Integer The price of the order.
order_tax Integer The tax price of the order.
order_days Integer The pricing plan and its retention period of the order.
order_address String The contact address of the purchaser.
order_status Integer The payment status of the order.
order_paymethod String The payment method of the order.
order_created_time String The time when the order is created by using Timestamp (UTC).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "order_name": "Purchaser’s name",
  "order_cost": 300,
  "order_tax": 10,
  "order_days": 30,
  "order_address": "Da-an District, Taipei, Taiwan",
  "order_status": 1,
  "order_paymethod": "Credit Card",
  "order_created_time": "1304460834"
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ORDER_ID The order_id does not exist.

▲ Top

GET/retentions/orders/account/:account_id
Purpose: Invoked to search all the order information according to the account_id.
Request Method
GET
Changelog
Aug 21, 2017
Permission
Must verify that the app_id and app_key of the Header belong to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required account_id String The ID number of the account.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
orders Array Receive the order list.
Return Values in the orders array
Fields Type Description
order_id String The ID number of the purchaser's order.
retention_name String The name of the plan.
order_amount Integer The price of the order.
order_paymethod Integer The payment method of the order.
order_status Integer The order status:
  • 0 = Unpaid
  • 1 = Paid
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752,
  "orders": [{
    "order_id": "c92be72d-40fc-462f-ae52-9e997e514277",
    "retention_name": "30-day retention period",
    "order_amount": 300,
    "order_paymethod": "Alipay",
    "order_status": 1
  }]
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ACCOUNT_ID The account_id does not exist.

▲ Top

PUT/retentions/orders/:order_id/status/:order_status
Purpose: While the order is being completed, this API is invoked to update the order status, order address, and so on.
Request Method
PUT
Changelog
Aug 21, 2017 First version
Dec 21, 2017 Second version
Permission
Must verify that the app_id and app_key of the Header belongs to the App to take further actions.
Request Parameters
Need Parameter Type Description
Required order_id String The ID number of the order.
Required order_status Integer The order status:
  • 0 = Unpaid
  • 1 = Paid
Optional order_address String The contact address of the purchaser.
Return Values (JSON)
Fields Type Description
time_used Integer The time the request takes (time unit: millisecond).
Sample Response
Sample response when a request has succeeded: 
{
  "time_used": 752
}
Unique Error Message of this API
HTTP Status Code Error Message Description
400 INVALID_ORDER_ID order_id does not exist.
400 INVALID_ORDER_STATUS order_status does not exist.

▲ Top