> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Create Account

POST https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts
Content-Type: application/json

This endpoint allows you to create a new account for a merchant under your franchise. In order to create a store for a merchant, an account must exist.

Reference: https://docs.bigcommerce.com/developer/docs/beta/powered-by/api-reference/accounts/create-account

## Authentication

- `X-Auth-Client` header (required) — The client ID of the franchise API account.
- `X-Auth-Token` header (required) — An OAuth token generated from the franchise API account. To authenticate, generate an **OAuth Token** (if you donʼt have one or itʼs expired): ```http POST https://api.bigcommerce.com/franchises/{franchise_uuid}/v1/oauth/token Accept: application/json X-Auth-Client: {client_id} X-Auth-Secret: {client_secret} { "duration": 900 } ``` Response: ```json { "access_token": "dlkJcn34...Lkd012", "expires_at": "2018-04-24T16:15:26.509045122Z” } ``` After you generate an **OAuth token**, use the `client_id` and `oauth_token` to authenticate all other API requests: ```http GET https://api.bigcommerce.com/franchises/{franchise_uuid}/v1/accounts/123 Accept: application/json X-Auth-Client: {client_id} X-Auth-Token: {oauth_token} ``` Response: ```json { "data": { "id": "12345678910", "name": "Test Company", ... }, "meta": {} } ```

## Request

### Headers

- `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

### Body (application/json)

This endpoint expects an object.

- `id` (string, required) — Associated account ID within partner’s system. Must be unique within your franchise.
- `name` (string, required) — Company name for the account and the name displayed at login when a merchant has multiple stores. 40 character limit.
- `user_email` (string, required) — Email address of the user who will be the store owner for the account.
- `primary_contact` (AccountsPostRequestBodyContentApplicationJsonSchemaPrimaryContact, required)
- `billing_contact` (billing_contact, optional) — Billing contact information for the Account
- `locale` (string, optional, default: en) — `locale` is used when sending email communications (such as account activation emails) to the accountʼs `user_email`.

## Response

### 200

Success

- `data` (AccountsPostResponsesContentApplicationJsonSchemaData, optional)
- `meta` (AccountsPostResponsesContentApplicationJsonSchemaMeta, optional)

## Errors

### 400 Bad Request Error

Malformed request syntax. Typically you need to fix the JSON body and resend.

- `status` (double, required)
- `title` (string, required)
- `type` (string, required)

### 401 Unauthorized Error

Unauthorized If a franchise makes a request with a `client_id` and access token that do not belong together or are expired, a 401 Unauthorized Credentials response is returned.

- `status` (double, required)
- `title` (string, required)
- `type` (string, required)

### 409 Conflict Error

Conflict This occurs if there is an account in the BigCommerce system with the given `ID` or `user_email`. Please provide a new value for one of these fields.

- `status` (double, required)
- `title` (string, required)
- `type` (string, required)
- `errors` (AccountsPostResponsesContentApplicationJsonSchemaErrors, required)

### 422 Unprocessable Entity Error

Unprocessable Entity This occurs when missing or unacceptable data is passed for one or more fields. Please correct the values for the fields listed in the error object.

- `status` (double, optional)
- `title` (string, optional)
- `type` (string, optional)
- `errors` (AccountsPostResponsesContentApplicationJsonSchemaErrors, optional)

### 502 Bad Gateway Error

Bad Gateway If something happens during the request that causes it to fail, a 502 response is returned. Submit a new get request. If it continues to fail, check the BigCommerce system status [here](http://status.bigcommerce.com/). A service is likely down and the request needs to be made again when the service is back up.

- `status` (double, required)
- `title` (string, required)
- `type` (string, required)

### 503 Service Unavailable Error

If this occurs, you should retry the request. If you are unable to successfully make a request, please check [the BigCommerce system status](http://status.bigcommerce.com/). A service is likely down and you will need to send the request again when the system is back up.

- `status` (double, optional)
- `title` (string, optional)
- `type` (string, optional)
- `errors` (AccountsPostResponsesContentApplicationJsonSchemaErrors, optional)

### 504 Gateway Timeout Error

Gateway Timeout If this occurs, you should retry the request. Typically retrying the request several times will result in a successful request. However, if you are unable to successfully make a request, please check the BigCommerce system status [here](http://status.bigcommerce.com/). A service is likely down and the request needs to be made again when the system is back up.

- `status` (double, optional)
- `title` (string, optional)
- `type` (string, optional)
- `errors` (AccountsPostResponsesContentApplicationJsonSchemaErrors, optional)

## Types

### AccountsPostRequestBodyContentApplicationJsonSchemaPrimaryContact

- `first_name` (string, required)
- `last_name` (string, required)
- `email` (string, required)
- `district` (string, required) — State, province, etc.
- `country` (string, required) — ISO 3166-1 alpha-2 code
- `address_line_1` (string, optional) — First line of address of primary contact. 255 character limit.
- `address_line_2` (string, optional) — Second line of address of primary contact. 255 character limit.
- `city` (string, optional) — City for primary contact. 255 character limit.
- `postal_code` (string, optional) — Postal code for primary contact. If this merchant is located in a country that does not have postal codes, this field is not required.
- `phone_number` (string, optional) — Phone number for the primary contact.

### billing_contact

Billing contact information for the Account

- `first_name` (string, optional) — First name of the billing contact
- `last_name` (string, optional) — Last name of the billing contact
- `address_line_1` (string, optional) — First line of address of billing contact
- `address_line_2` (string, optional) — Second line of address of billing contact (if necessary)
- `email` (string, optional) — Email address of billing contact
- `district` (string, optional) — District (State in US) of billing contact
- `country` (string, optional) — Country of billing contact
- `phone` (string, optional) — Phone number of billing contact
- `city` (string, optional) — City for billing contact
- `postal_code` (string, optional) — Postal / zip code of billing contact

### AccountsPostResponsesContentApplicationJsonSchemaData

- `id` (string, required)

### AccountsPostResponsesContentApplicationJsonSchemaMeta

### AccountsPostResponsesContentApplicationJsonSchemaErrors

## Examples

**Request**

```json
{
  "id": "string",
  "name": "string",
  "user_email": "string",
  "primary_contact": {
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "district": "string",
    "country": "US"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "string"
  },
  "meta": {}
}
```

**SDK Code**

```python
import requests

url = "https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts"

payload = {
    "id": "string",
    "name": "string",
    "user_email": "string",
    "primary_contact": {
        "first_name": "string",
        "last_name": "string",
        "email": "string",
        "district": "string",
        "country": "US"
    }
}
headers = {
    "Accept": "application/json",
    "X-Auth-Client": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts';
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'X-Auth-Client': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{"id":"string","name":"string","user_email":"string","primary_contact":{"first_name":"string","last_name":"string","email":"string","district":"string","country":"US"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts"

	payload := strings.NewReader("{\n  \"id\": \"string\",\n  \"name\": \"string\",\n  \"user_email\": \"string\",\n  \"primary_contact\": {\n    \"first_name\": \"string\",\n    \"last_name\": \"string\",\n    \"email\": \"string\",\n    \"district\": \"string\",\n    \"country\": \"US\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Client", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["X-Auth-Client"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"id\": \"string\",\n  \"name\": \"string\",\n  \"user_email\": \"string\",\n  \"primary_contact\": {\n    \"first_name\": \"string\",\n    \"last_name\": \"string\",\n    \"email\": \"string\",\n    \"district\": \"string\",\n    \"country\": \"US\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts")
  .header("Accept", "application/json")
  .header("X-Auth-Client", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"id\": \"string\",\n  \"name\": \"string\",\n  \"user_email\": \"string\",\n  \"primary_contact\": {\n    \"first_name\": \"string\",\n    \"last_name\": \"string\",\n    \"email\": \"string\",\n    \"district\": \"string\",\n    \"country\": \"US\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts', [
  'body' => '{
  "id": "string",
  "name": "string",
  "user_email": "string",
  "primary_contact": {
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "district": "string",
    "country": "US"
  }
}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Client' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Client", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"id\": \"string\",\n  \"name\": \"string\",\n  \"user_email\": \"string\",\n  \"primary_contact\": {\n    \"first_name\": \"string\",\n    \"last_name\": \"string\",\n    \"email\": \"string\",\n    \"district\": \"string\",\n    \"country\": \"US\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Client": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "id": "string",
  "name": "string",
  "user_email": "string",
  "primary_contact": [
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "district": "string",
    "country": "US"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```