Users
The Users resources allows an application to retrieve information about the tokenized user such as balance, credit, address, and subscriptions. Only the addresses can be updated by applications, and only BoxC owned applications have permission to create and cancel subscriptions.
Subscriptions
A subscription is a recurring payment for a provided service. The specified amount
is deducted from the user's BoxC balance at the start of each interval
- also known as current_period_start
. There are several guidelines for subscriptions:
- Applications can only view, renew, and cancel subscriptions that belong to them.
- Subscriptions automatically renew each interval until cancelled.
- Cancelling a subscription will flag it to be deleted after
current_period_end
. To save a subscription it must be renewed beforecurrent_period_end
. - Subscriptions are automatically removed from the list if their
current_period_end
is less than the current time. - A subscription cannot be modified after creation - only renewed.
- A subscription will not be renewed if the user has insufficient funds.
Actions
GET /users/me |
Retrieves this user |
PUT /users/me |
Updates this user |
POST /users/me/subscriptions |
Creates a subscription for this user |
PUT /users/me/subscriptions/{sub_id} |
Renews a cancelled subscription |
DELETE /users/me/subscriptions/{sub_id} |
Cancels a subscription |
Properties
address |
{ "address": { "company_name": "Terracotta Warriors Ltd, Co", "street1": "4 Jing Shan Qian Jie", "street2": "Dongcheng", "city": "Beijing", "province": "Hebei", "postal_code": "100009", "country": "CN" } } This is the user's personal or company address and may not be the same as the consignor. Optional. company_name: String - The company name. Required.street1: String - The company's street address. Required. street2: String - Additional space for the company's street address. Not required. city: String - The company's city. Required. province: String - The company's province. Required for some countries. postal_code: String - The company's postal code. Required for some countries. country: String - The company's country in ISO 3166-1 alpha-2 format. Required. |
balance |
|
credit_limit |
|
first_name |
|
id |
|
last_name |
|
return_address Deprecated |
{ "return_address": [] } No longer used. |
subscription |
{ "subscription": { "amount": 29.95, "name": "RBB Basic Plan" } } Object - Only used when creating a new subscription. amount: Decimal - The amount to charge each interval in USD. Requiredname: String - The name of the subscription. Required. |
subscriptions |
{ "subscriptions": [ { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": null, "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 14:10:01", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "active" }, { "...": "..." } ] } Array - A list of active and cancelled subscriptions for this user. Present only when retrieving a user. Set by the application. amount: Decimal - The amount charged each interval.application: String - The name of the application that created the subscription. cancelled_at: datetime - The UTC date and time the subscription was cancelled. Default: null. created: datetime - The UTC date and time the subscription was created. currency: String - The currency code for the amount. Always "USD". current_period_end: datetime - The UTC date and time the subscription ends for this interval. current_period_start: datetime - The UTC date and time the subscription started for this interval. id: String - The unique ID of the subscription. interval: String - How often the subscription is renewed and the user is charged. Always "monthly". name: String - The name of the subscription set by the application. status: String - The status of the subscription. Can be "active" or "cancelled". |
timezone |
|
GET /users/me
HTTP/1.1 200 OK
{ "user": { "address": { "company_name": "Terracotta Warriors Ltd, Co", "street1": "4 Jing Shan Qian Jie", "street2": "Dongcheng", "city": "Beijing", "province": "Hebei", "postal_code": "100009", "country": "CN" }, "balance": 1525.46, "credit_limit": 10000, "first_name": "Huang", "id": 1006, "last_name": "Qin", "return_address": [], "subscriptions": [ { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": null, "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 14:10:01", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "active" } ], "timezone": "UTC" } }
PUT /users/me
{ "user": { "address": { "company_name": "Terracotta Warriors Ltd, Co", "street1": "4 Jing Shan Qian Jie", "street2": "Dongcheng", "city": "Beijing", "province": "Hebei", "postal_code": "100009", "country": "CN" } } }
HTTP/1.1 200 OK
{ "user": { "address": { "company_name": "Terracotta Warriors Ltd, Co", "street1": "4 Jing Shan Qian Jie", "street2": "Dongcheng", "city": "Beijing", "province": "Hebei", "postal_code": "100009", "country": "CN" }, "balance": 1525.46, "credit_limit": 10000, "first_name": "Huang", "id": 1006, "last_name": "Qin", "return_address": [], "subscriptions": [ { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": null, "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 14:10:01", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "active" } ], "timezone": "UTC" } }
POST /users/me/subscriptions
{ "subscription": { "amount": 29.95, "name": "RBB Basic Plan" } }
HTTP/1.1 201 Created
{ "subscription": { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": null, "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 15:00:00", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "active" } }
PUT /users/me/subscriptions/sub_578d2a6bb75be
{ "subscription": { "status": "active" } }
HTTP/1.1 20O OK
{ "subscription": { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": null, "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 14:10:01", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "active" } }
DELETE /users/me/subscriptions/sub_578d2a6bb75be
HTTP/1.1 20O OK
{ "subscription": { "amount": 29.95, "application": "Returns By BoxC", "cancelled_at": "2016-08-01 11:43:12", "created": "2016-07-18 14:10:01", "currency": "USD", "current_period_end": "2016-08-18 23:59:59", "current_period_start": "2016-07-18 15:00:00", "id": "sub_578d2a6bb75be", "interval": "monthly", "name": "RBB Basic Plan", "status": "cancelled" } }