Update a sub-entity

Last updated: December 24, 2025

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 Dashboard, or 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.

Sign in to the Dashboard.
Go to Payments > Processing > Sub-entities.
On the Sub-entities page, select the sub-entity to edit.
On the Activity page, select Manage account.
On the Manage account page, select Edit business details.
On the Account Activation page, edit the required details and select Update.

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 [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

put

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


1{
2  "reference": "CAKE12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.thecakeshop.com"],
13    "mccs": ["5814"]
14  },
15  "company": {
16    "business_registration_number": "12345678",
17    "legal_name": "The Cake Shop Inc.",
18    "trading_name": "The Cake Shop",
19    "principal_address": {
20      "address_line1": "654 Example St.",
21      "city": "Edinburgh",
22      "zip": "EH9 2XY",
23      "country": "GB"
24    }
25  },
26  "registered_address": {
27    "address_line1": "123 High St.",
28    "city": "London",
29    "zip": "SW1A 1AA",
30    "country": "GB"
31  },
32  "representatives": [
33    {
34      "first_name": "Ali",
35      "last_name": "Farid",
36      "address": {
37        "country": "GB"
38      }
39    }
40  ]
41}


1{
2  "reference": "DONUTS12345",
3  "contact_details": {
4    "phone": {
5      "number": "7700900000"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.alis-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Ali",
17    "last_name": "Farid",
18    "trading_name": "Ali's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "123 High St.",
22      "city": "London",
23      "zip": "SW1A 1AA",
24      "country": "GB"
25    },
26    "date_of_birth": {
27      "day": 5,
28      "month": 6,
29      "year": 1995
30    }
31  }
32}


1{
2  "reference": "cakeshop678910",
3  "contact_details": {
4    "phone": {
5      "number": "111222333"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.thecakeshop.com"],
13    "mccs": ["5814"]
14  },
15  "company": {
16    "business_registration_number": "452349600005",
17    "legal_name": "The Cake Shop Inc.",
18    "trading_name": "The Cake Shop",
19    "principal_address": {
20      "address_line1": "90 Tottenham Court Road",
21      "city": "London",
22      "zip": "W1T4TJ",
23      "country": "GB"
24    },
25    "registered_address": {
26      "address_line1": "90 Tottenham Court Road",
27      "city": "London",
28      "zip": "W1T4TJ",
29      "country": "GB"
30    },
31    "representatives": [
32      {
33        "first_name": "Chrisi",
34        "last_name": "Webster",
35        "address": {
36          "address_line1": "123 ABC Close",
37          "city": "London",
38          "zip": "E1 5DP",
39          "country": "GB"
40        },
41        "date_of_birth": {
42          "day": 5,
43          "month": 6,
44          "year": 1995
45        },
46        "identification": {
47          "document": {
48            "type": "Passport",
49            "front": "file_jxaps37jnfaupfu6bsei7rj5iu",
50            "back": "file_zn6v47bgphjuljjvhlpk7dnpby"
51          }
52        }
53      }
54    ]
55  }
56}


1{
2  "reference": "cakeshop0123456",
3  "contact_details": {
4    "phone": {
5      "number": "2345678910"
6    },
7    "email_addresses": {
8      "primary": "[email protected]"
9    }
10  },
11  "profile": {
12    "urls": ["https://www.daniels-donuts.com"],
13    "mccs": ["5814"]
14  },
15  "individual": {
16    "first_name": "Daniel",
17    "last_name": "Yubi",
18    "trading_name": "Daniel's Donuts",
19    "national_tax_id": "1234567",
20    "registered_address": {
21      "address_line1": "90 Tottenham Court Road",
22      "city": "London",
23      "zip": "W1T4TJ",
24      "country": "GB"
25    },
26    "date_of_birth": {
27      "day": 5,
28      "month": 6,
29      "year": 1995
30    },
31    "identification": {
32      "document": {
33        "type": "Passport",
34        "front": "file_jxaps37jnfaupfu6bsei7rj5iu"
35      }
36    }
37  }
38}

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 200 - Sub-entity updated successfully response.


1{
2  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
3  "reference": "CAKE12345",
4  "status": "pending",
5  "capabilities": {
6    "payments": {
7      "available": true,
8      "enabled": false
9    },
10    "payouts": {
11      "available": false,
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}

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.

If you're using the hosted onboarding flow, and your sub-entity encounters issues when submitting their application, or is missing required verification information, you can update the sub-entity's details yourself using the API.

Note

You can only use the API to complete the sub-entity's application on their behalf, as the application is not accessible from the Dashboard.

To update a sub-entity in a hosted onboarding flow:

Call the Update entity details endpoint, and provide the sub-entity ID as the {id} path parameter.
Make the required changes to the fields in the API request.
Depending on how you want the application to be submitted, set the is_draft field to one of the following:
- true - To allow the sub-entity to submit the application themselves at a later time.
- false - To submit the application on the sub-entity's behalf.

Information

Your base URL [prefix] is unique. To learn how to retrieve your unique base URLs for the sandbox and production environments, see API endpoints.

put

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


1{
2  "reference": "acme0123456",
3  "is_draft": false,
4  "contact_details": {
5    "invitee": {
6      "email": "[email protected]"
7    },
8    "phone": {
9      "number": "1234567890"
10    },
11    "email_addresses": {
12      "primary": "[email protected]"
13    }
14  },
15  "profile": {
16    "urls": ["https://www.acme-corp.com"],
17    "mccs": ["5814"]
18  },
19  "individual": {
20    "first_name": "Jane",
21    "last_name": "Smith",
22    "trading_name": "Acme Corporation",
23    "national_tax_id": "1234567",
24    "registered_address": {
25      "address_line1": "123 High St.",
26      "city": "London",
27      "zip": "SW1A 1AA",
28      "country": "GB"
29    },
30    "date_of_birth": {
31      "day": 1,
32      "month": 1,
33      "year": 1990
34    }
35  }
36}


1{
2  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
3  "reference": "acmeCorp1234",
4  "status": "pending",
5  "capabilities": {
6    "payments": {
7      "available": true,
8      "enabled": false
9    },
10    "payouts": {
11      "available": false,
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}

Update a sub-entity

Information