Create a customer

Article
03/26/2024

Applies to: Partner Center | Partner Center operated by 21Vianet | Partner Center for Microsoft Cloud for US Government

As a Cloud Solution Provider (CSP) partner, when you create a customer you can place orders on behalf of the customer. When you create a customer, you also create:

An Microsoft Entra tenant object for the customer
A relationship between the reseller and customer (used for delegated admin privileges)
A user name and password to sign in as an admin for the customer

After the customer is created, save the customer ID and Microsoft Entra ID details.

Important

If you are an indirect provider and you want to create a customer for an indirect reseller, see Create a customer for an indirect reseller.

Prerequisites

Credentials as described in Partner Center authentication. This scenario supports authentication with both standalone App and App+User credentials.

Important

To create a customer tenant you must provide a valid physical address during the creation process. An address can be validated by following the steps outlined in the Validate an address scenario. If you create a customer using an invalid address in the sandbox environment, you won't be able to delete that customer tenant.

Important

If passing userCredentials password isn't accepted.

C#

To add a customer:

Instantiate a new Customer object. Be sure to fill in the BillingProfile and CompanyProfile.
Add the new customer to your IAggregatePartner.Customers collection by calling Create or CreateAsync.

C# example

// IAggregatePartner partnerOperations;

var partnerOperations = this.Context.UserPartnerOperations;

var customerToCreate = new Customer()
{
    CompanyProfile = new CustomerCompanyProfile()
    {
        Domain = string.Format(CultureInfo.InvariantCulture,
            "SampleApplication{0}.{1}",
            new Random().Next(),
            this.Context.Configuration.Scenario.CustomerDomainSuffix),
        //// OrganizationRegistrationNumber = "123456" // Please add if in specific country/region that requires
    },
    BillingProfile = new CustomerBillingProfile()
    {
        Culture = "EN-US",
        Email = "gena@wingtiptoys.com",
        Language = "En",
        CompanyName = "Wingtip Toys"
        DefaultAddress = new Address()
        {
            FirstName = "Gena",
            MiddleName = "Coralie",
            LastName = "Soto",
            AddressLine1 = "One Microsoft Way",
            City = "Redmond",
            State = "WA",
            Country = "US",
            PostalCode = "98052",
            PhoneNumber = ""
        }
    }
};

var newCustomer = partnerOperations.Customers.Create(customerToCreate);

C# sample app

Console test app. Project: Partner Center SDK Samples Class: CreateCustomer.cs

REST

Request syntax

Method	Request URI
POST	{baseURL}/v1/customers HTTP/1.1

Request headers

This API is idempotent (it will not yield a different result if you call it multiple times).
A request ID and correlation ID are required.
For more information, see Partner Center REST headers.

Request body

This table describes the required properties in the request body.

Name	Type	Description
BillingProfile	object	The customer's billing profile information.
CompanyProfile	object	The customer's company profile information.

Billing profile

This table describes the minimum required fields from the CustomerBillingProfile resource needed to create a new customer.

Name	Type	Description
email	string	The customer's email address.
culture	string	Their preferred culture for communication and currency, such as `en-US`. See Partner Center supported languages and locales for the supported cultures.
language	string	The default language. Two character language codes (for example `en` or `fr`) are supported.
companyName	string	The registered company/organization name.
defaultAddress	Address	The registered address of the customer's company/organization. See the Address resource for information on any length limitations.

Company profile

This table describes the minimum required fields from the CustomerCompanyProfile resource needed to create a new customer.

Name	Type	Description
domain	string	The customer's domain name, such as contoso.onmicrosoft.com.
organizationRegistrationNumber	String	The customer's organization registration number (also referred to as INN number in certain countries/regions). Only required for customer's company/organization located in the following countries/regions: Armenia(AM), Azerbaijan(AZ), Belarus(BY), Hungary(HU), Kazakhstan(KZ), Kyrgyzstan(KG), Moldova(MD), Russia(RU), Tajikistan(TJ), Uzbekistan(UZ), Ukraine(UA), Brazil(BR), India, South Africa, Poland, United Arab Emirates, Saudi Arabia, Türkiye, Thailand, Vietnam, Myanmar, Iraq, South Sudan, Venezuela and China. For customer's company/organization located in other countries/regions, this is an optional field.

GDAP by Default

Name	Type	Description
enableGDAPByDefault	bool	Boolean to indicate if we want to enable GDAP by default or not. If true we will create GDAP by default. If false, we will not create GDAP. Note, this is only honored in clouds that support GDAP. If no supported, DAP will be created by default.

Request example

POST https://api.partnercenter.microsoft.com/v1/customers HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 94e4e214-6b06-4fb7-96d1-94d559f9b47f
MS-CorrelationId: ab993325-1605-4cf4-bac4-fb584142a31b
X-Locale: en-US
Content-Type: application/json
Host: api.partnercenter.microsoft.com
Content-Length: 789
Expect: 100-continue
Connection: Keep-Alive

{
    "enableGDAPByDefault": false,
    "CompanyProfile": {
        "Domain": "xyz.onmicrosoft.com"
    },
    "BillingProfile": {
        "Culture": "EN-US",
        "Email": "gena@wingtiptoys.com",
        "Language": "en",
        "CompanyName": "Wingtip Toys",
        "DefaultAddress": {
            "FirstName": "Gena",
            "LastName": "Soto",
            "AddressLine1": "One Microsoft Way",
            "City": "Redmond",
            "State": "WA",
            "PostalCode": "98052",
            "Country": "US"
        }
    }
}

REST response

If successful, this API returns a Customer resource for the new customer. Save the customer ID and Microsoft Entra ID details for future use with the Partner Center SDK. You will need them for use with account management, for example.

Response success and error codes

Responses come with an HTTP status code that indicates success or failure and additional debugging information. Use a network trace tool to read this code, error type, and additional parameters. For the full list, see Partner Center REST error codes.

Response example

HTTP/1.1 201 Created
Content-Length: 834
Content-Type: application/json; charset=utf-8
MS-CorrelationId: ab993325-1605-4cf4-bac4-fb584142a31b
MS-RequestId: 94e4e214-6b06-4fb7-96d1-94d559f9b47f
MS-CV: ObwhuhD2tUKJoM+Z.0
MS-ServerId: 202010223
Date: Tue, 14 Feb 2017 20:06:02 GMT

{
    "id": "dfd8cc0a-c592-468c-8461-869a38d24738",
    "commerceId": "0a4ce58a-6f96-4273-8035-d9c7d31b9ba4",
    "companyProfile": {
        "tenantId": "dfd8cc0a-c592-468c-8461-869a38d24738",
        "domain": "xyz.onmicrosoft.com",
        "attributes": {
            "objectType": "CustomerCompanyProfile"
        }
    },
    "billingProfile": {
        "id": "d17c0275-da92-5c33-9032-782ef1d0b69b",
        "email": "gena@wingtiptoys.com",
        "culture": "en-US",
        "language": "en",
        "companyName": "Wingtip Toys",
        "defaultAddress": {
            "country": "US",
            "city": "Redmond",
            "state": "WA",
            "addressLine1": "One Microsoft Way",
            "postalCode": "98052",
            "firstName": "Gena",
            "lastName": "Soto",
            "phoneNumber": ""
        },
        "attributes": {
            "etag": "5920358838484612121",
            "objectType": "CustomerBillingProfile"
        }
    },
    "enableGDAPByDefault": false,
    "relationshipToPartner": "none",
    "userCredentials": {
        "userName": "admin",
        "password": "=;;n.=s9Z"
    },
    "attributes": {
        "objectType": "Customer"
    }
}

Java

Note

The Partner Center SDK for Java is an open source project maintained by the partner community.

Use the following steps to create a new customer.

Create a new instance of the CustomerBillingProfile and the CustomerCompanyProfile objects. Be sure to populate the required fields.
Create the customer by calling the IAggregatePartner.getCustomers().create function.

Java example

// IAggregatePartner partnerOperations;

Address address = new Address();

address.setFirstName( "Gena" );
address.setLastName( "Soto" );
address.setAddressLine1( "One Microsoft Way" );
address.setCity( "Redmond" );
address.setState( "WA" );
address.setCountry( "US" );
address.setPostalCode( "98052" );
address.setPhoneNumber( "4255550101" );

CustomerBillingProfile billingProfile = new CustomerBillingProfile();

billingProfile.setCulture( "en-US" );
billingProfile.setEmail( "gena@wingtiptoys.com" );
billingProfile.setLanguage( "en" );
billingProfile.setCompanyName( "Wingtip Toys" );
billingProfile.setDefaultAddress( address );

CustomerCompanyProfile companyProfile = new CustomerCompanyProfile();

companyProfile.setDomain( "WingtipToys" + Math.abs( new Random().nextInt() ) + ".onmicrosoft.com" );

Customer customerToCreate = new Customer();

customerToCreate.setBillingProfile( billingProfile );
customerToCreate.setCompanyProfile( companyProfile );

Customer newCustomer = partnerOperations.getCustomers().create( customerToCreate );

PowerShell

Note

The Partner Center SDK for PowerShell is an open source project maintained by the partner community.

To create a customer, execute the New-PartnerCustomer command as in the following example.

New-PartnerCustomer -BillingAddressLine1 '1 Microsoft Way' -BillingAddressCity 'Redmond' -BillingAddressCountry 'US' -BillingAddressPostalCode '98052' -BillingAddressState 'WA' -ContactEmail 'gena@wingtiptoys.com' -ContactFirstName 'Gena' -ContactLastName 'Soto' -Culture 'en-US' -Domain 'newcustomer.onmicrosoft.com' -Language 'en' -Name 'New Customer'

Create a customer

Prerequisites

C#

C# example

C# sample app

REST

Request syntax

Request headers

Request body

Billing profile

Company profile

GDAP by Default

Request example

REST response

Response success and error codes

Response example

Java

Java example

PowerShell

Feedback

Feedback

Additional resources