Child Users

A Child User is a sub-account type designed for managing customers or businesses that use a Forge-Powered shipping solution. Each Child User can have a unique set of carrier credentials, analytics, and reports, simplifying the management of a platform or marketplace solution.

Beyond organizing activity and CarrierAccounts, the primary advantage of a Child User is that billing flows through the Parent User’s payment information. This allows the Parent User to maintain complete control over customers' postage and pricing.

Structurally, a Child User mirrors the Parent User, meaning its representation includes many properties that may not be actively used. However, creating a Child User requires significantly fewer properties than creating a top-level User.

Endpoints

Production OnlyThis call will only work with your Production API Key.

Create a Child User

A Child User uses the billing information of the parent, and is not able to log in to the website. Any User creation attempt made with an authenticated request (via API key or cookie) is assumed to be the creation of a child of that User.

The name attribute is the only user-settable value on child accounts. It is also optional, as one will be automatically generated if it is not supplied.

Request Parameters

name

i.e. Child Account Name

POST /users

1curl -X POST https://api.easypost.com/v2/users \
2  -u "EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "user": {
6      "name": "Child Account Name"
7    }
8  }'

Response

1{
2  "id": "user_d2539e6862fe4f389f735c7c00aaa37a",
3  "object": "User",
4  "parent_id": "user_060ab38db3c04ffaa60f262e5781a9be",
5  "name": "Test User",
6  "phone_number": "8005550100",
7  "verified": true,
8  "created_at": "2024-01-24T00:07:48Z",
9  "default_carbon_offset": false,
10  "has_elevate_access": false,
11  "children": [],
12  "api_keys": [
13    {
14      "object": "ApiKey",
15      "key": "<REDACTED>",
16      "mode": "test",
17      "created_at": "2024-01-24T00:07:48Z",
18      "active": true,
19      "id": "ak_afdf54db97e24e4aa7354527c8aa3be0"
20    },
21    {
22      "object": "ApiKey",
23      "key": "<REDACTED>",
24      "mode": "production",
25      "created_at": "2024-01-24T00:07:48Z",
26      "active": true,
27      "id": "ak_da39a3c4afd946e1b77a578ec211e816"
28    }
29  ]
30}

Production OnlyThis call will only work with your Production API Key.

Retrieve all Child Users

A list of all Child User objects associated with the given API Key can also be retrieved. See the Pagination section of our docs for more details on retrieving all records when multiple pages are available.

Request Parameters

after_id

i.e. user_...

Optional pagination parameter. Only records created after the given ID will be included.

page_size

i.e. 30

The number of records to return on each page. The maximum value is 100, and default is 20.

GET /users/children

1curl -X GET "https://api.easypost.com/v2/users/children?page_size=5" \
2  -u "EASYPOST_API_KEY":

Response

1{
2  "children": [
3    {
4      "id": "user_0ae8cb7000a1438c8598fa5786fdae84",
5      "object": "User",
6      "parent_id": "user_060ab38db3c04ffaa60f262e5781a9be",
7      "name": "Test User",
8      "phone_number": "8005550100",
9      "verified": true,
10      "created_at": "2022-10-17T17:28:30Z"
11    }
12  ],
13  "has_more": false
14}

Production OnlyThis call will only work with your Production API Key.

Delete a Child User

A Child User may be removed from its parent. The parent's Production API Key must be used for the request; a Child User may not remove itself from its parent.

A successful delete will return a 204 status code and an empty JSON response.

DELETE /users/:child_id

1curl -X DELETE https://api.easypost.com/v2/users/user_... \
2  -u "EASYPOST_API_KEY":

Response

1{}