Update a sub-entity
Beta

Last updated: March 25, 2026

You may need to update a sub-entity because some of their details have changed, your sub-entity encounters issues when submitting their application, or to fulfill specific verification requirements.

You can update a sub-entity using the API.

Information

When you update a sub-entity, we may conduct further verification checks when necessary. During these checks, your payment and payout capabilities will remain unchanged.

You can update the fields under the contact_details, profile, and company objects.

Note

The profile.default_holding_currency field is not currently updatable. If you need to change it, contact support.

Call the Update entity details endpoint, and provide the sub-entity ID as the {id} path parameter.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

put

https://{prefix}.api.checkout.com/accounts/entities/{id}


1{
2   "seller_category":"Silver",
3   "profile":{
4      "urls":[
5         "https://www.theonlineretailer.com"
6      ],
7      "mccs":[
8         "5551"
9      ],
10      "holding_currencies":[
11         "USD"
12      ],
13      "default_holding_currency":"USD"
14   },
15   "processing_details":{
16      "annual_processing_volume":125000,
17      "average_transaction_value":5000,
18      "highest_transaction_value":10000,
19      "currency":"USD",
20      "target_countries":[
21         "US",
22         "VI"
23      ],
24      "settlement_country":"AL"
25   },
26   "company":{
27      "business_type":"private_corporation",
28      "principal_address":{
29         "country":"US",
30         "address_line1":"123 Anywhere St.",
31         "city":"Anytown",
32         "zip":"123456",
33         "state":"AL"
34      },
35      "representatives":[
36         {
37            "roles":[
38               "ubo"
39            ],
40            "individual":{
41               "first_name":"Toby",
42               "last_name":"Arden",
43               "address":{
44                  "address_line1":"123 Anywhere St.",
45                  "country":"AL",
46                  "zip":"123456",
47                  "city":"Anytown"
48               },
49               "date_of_birth":{
50                  "day":23,
51                  "month":1,
52                  "year":1990
53               },
54               "place_of_birth":{
55                  "country":"AL"
56               }
57            }
58         }
59      ],
60      "trading_name":"TheOnlineRetailer",
61      "date_of_incorporation":{
62         "day":22,
63         "month":2,
64         "year":1990
65      }
66   },
67   "contact_details":{
68      "phone":{
69         "number":"5550005550",
70         "country_code":"US"
71      },
72      "email_addresses":{
73         "primary":"theonlineretailer@example.com"
74      }
75   }
76}


1{
2   "seller_category":"Silver",
3   "profile":{
4      "urls":[
5         "https://www.theonlineretailer.com"
6      ],
7      "mccs":[
8         "5551"
9      ],
10      "holding_currencies":[
11         "USD"
12      ],
13      "default_holding_currency":"USD"
14   },
15   "processing_details":{
16      "annual_processing_volume":12300,
17      "average_transaction_value":12300,
18      "highest_transaction_value":12000,
19      "currency":"USD",
20      "target_countries":[
21         "US",
22         "VI"
23      ],
24      "settlement_country":"AL"
25   },
26   "company":{
27      "business_type":"individual_or_sole_proprietorship",
28      "principal_address":{
29         "country":"US",
30         "address_line1":"123 Anywhere St.",
31         "city":"Anytown",
32         "zip":"123456",
33         "state":"AL"
34      },
35      "representatives":[
36         {
37            "roles":[
38               "ubo"
39            ],
40            "individual":{
41               "first_name":"Toby",
42               "last_name":"Arden",
43               "address":{
44                  "address_line1":"123 Anywhere St.",
45                  "country":"US",
46                  "zip":"123456",
47                  "city":"Anytown"
48               },
49               "date_of_birth":{
50                  "day":23,
51                  "month":1,
52                  "year":1990
53               },
54               "place_of_birth":{
55                  "country":"US"
56               }
57            }
58         }
59      ],
60      "trading_name":"TheOnlineRetailer",
61      "date_of_incorporation":{
62         "day":22,
63         "month":2,
64         "year":1990
65      }
66   },
67   "contact_details":{
68      "phone":{
69         "number":"5550005550",
70         "country_code":"US"
71      },
72      "email_addresses":{
73         "primary":"theonlineretailer@example.com"
74      }
75   }
76}

When you call the Update entity details endpoint, you receive one of the following HTTP responses, depending on the outcome:

200 - Sub-entity updated successfully
422 - Invalid data was sent

If the request is successful, you receive a 200response.

The status is set to pending as the sub-entity needs to undergo verification checks again.


1{
2  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
3  "reference": "superhero1234",
4  "status": "pending",
5  "capabilities": {
6    "payments": {
7      "available": true,
8      "enabled": false
9    },
10    "payouts": {
11      "available": true,
12      "enabled": false
13    },
14    "requirements_due": [],
15    "_links": {
16      "self": {
17        "href": "https://{prefix}.api.sandbox.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
18      }
19    }
20  }
21}

Note

Capabilities are enabled after verification checks have been completed. If you have not received a webhook – either {check}_passed or {check}_failed – it is likely there are outstanding requirements due. See verification requirements to confirm you have sent all the required information.

If you have provided all the information, we may be completing a manual review.

In case of any issues in your request, you receive a 422 response.


1{
2  "request_id": "0HM1I9VJUDPHV:00000002",
3  "error_type": "invalid_request",
4  "error_codes": [
5    "profile_mccs_invalid_for_processing_scope",
6    "principal_address_country_invalid_for_processing_scope"
7  ]
8}

The response also returns the error_codes object that specifies the exact error. See the following table for information on the different error codes.

Possible error codes

Name	Description
`profile_mccs_invalid_for_processing_scope`	The MCCs provided for the sub-entity are outside the processing scope of the platform.
`principal_address_country_invalid_for_processing_scope`	The principal address country provided for the sub-entity is outside the processing scope of the platform.
`company_or_individual_required`	The `company` or `individual` is missing in your request. Include this information and send the request again.
`sub_entity_invalid`	Internal validation error. If you receive this error, contact support.
`existing_sub_entity_type_invalid`	The specified sub-entity type is invalid. This occurs when the company type is used in an individual request, and vice versa.
`<field_name>_invalid` For example, `legal_name_invalid`, or `profile_urls_0_invalid`.	The specified field does not match the validation policies for minimum or maximum length, or formatting. The `company` or `individual` object must be provided in your request. The only two exceptions to this are `sub_entity_invalid` and `existing_sub_entity_type_invalid`, which have different causes.
`<field_name>_required` For example, `legal_name_required` or `representatives_0_first_name_required`.	The specified field is required but was not provided in the request. For example, the field is `null`, contains empty strings, or contains white spaces.

Update a sub-entity
Beta

Information

Update a sub-entity using the API

Note

Information

Request examples

Response examples

200 - Sub-entity updated successfully

Note

422 - Invalid data was sent

Possible error codes