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 before current_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

{"balance": 1525.46}

Decimal - The user's current balance with BoxC in USD. A negative amount is an outstanding balance. Set by the system.
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

{"first_name": "Huang"}

String - The user's first name. Set by the system.
id

{"id": 12006}

Integer - The user's ID. Set by the system.
last_name

{"last_name": "Qin"}

String - The user's last name. Set by the system.
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. Required
name: 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

{"timezone": "America/New_York"}

String - The user's timezone following the format of tz database. Set by the system. Default is "UTC".
GET
/users/me
Retrieves this user
request
GET /users/me
response

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
Updates this user
request
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"
        }
    }
}
response

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
Creates a subscription for this user
request
POST /users/me/subscriptions 
{
    "subscription": {
        "amount": 29.95,
        "name": "RBB Basic Plan"
    }
}
response

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_id}
Renews a cancelled subscription
request
PUT /users/me/subscriptions/sub_578d2a6bb75be 
{
    "subscription": {
        "status": "active"
    }
}
response

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_id}
Cancels a subscription
request
DELETE /users/me/subscriptions/sub_578d2a6bb75be 

		

		

		

			
response

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