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

{"balance": 1525.46}

Decimal - The user's current balance with BoxC. A negative amount is an outstanding balance. Set by the system.
credit_limit

{"credit_limit": 10000.00}

Decimal - The user's credit limit with BoxC. Set by the system.
first_name

{"first_name": "Huang"}

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

{"id": 1006}

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

{"last_name": "Qin"}

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