Users
The Users resources allows an application to retrieve information about the tokenized user such as balances, personal/company 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 Deprecated |
|
balances |
{ "balances": { "USD": 1201.42, "CNY": 421090 } }Object - A list of balances in different currencies for this user. Set by the system. |
credit_limits |
{ "credit_limit": { "USD": 100000.00, "CNY": 0 } }Object - A list of credit limits in different currencies for this user. Set by the system. |
first_name |
|
id |
|
last_name |
|
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, "balances": { "CNY": 10000, "USD": 381.42 }, "credit_limits": { "CNY": 0, "USD": 10000 }, "first_name": "Huang", "id": 1006, "last_name": "Qin", "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, "balances": { "CNY": 10000, "USD": 381.42 }, "credit_limits": { "CNY": 0, "USD": 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" } }