> 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 Store POST https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/{account_id}/stores Content-Type: application/json This endpoint allows you to create a new store for a merchant on a specific account under your franchise. Reference: https://docs.bigcommerce.com/developer/docs/beta/powered-by/api-reference/stores/create-store ## 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 ### Path parameters - `account_id` (string, required) — The account ID set when the account was created. Can be retrieved through a `GET` request to `/accounts`. ### 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 a post_store. - `id` (string, required) — Associated store id within partner’s system. Must be unique within your franchise. - `plan_sku` (string, required) — Determines the BigCommerce plan (delegated billing) or trial length (non-delegated billing). The allow list for SKUs is configured on your franchise - `store_name` (string, required) — Initial store name used across the BigCommerce control panel and the merchant’s theme. When a merchant has multiple stores on their account, this name is used to identify each store in the merchant’s store switcher. The name can be updated by the merchant after store creation. The name has a 255 character limit and must be unique to the account. - `country` (string, required) — ISO 3166-1 alpha-2 code (i.e., ‘US’). `country` controls the ‘Default Country’ option for the store. For more information, see [Locale](https://support.bigcommerce.com/s/article/Store-Profile-Settings?language=en_US#locale). `country` also influences the ‘Default Language’ for a store. If the country has an associated language that the theme supports, the default language will align with the `country` value. For example, a store created with `country` value of `FR` will have French as the default language. For more information, visit the [Store Profile FAQ](https://support.bigcommerce.com/s/article/Store-Profile-Settings?language=en_US#faq). - `region` (enum, optional) — If no region is provided, the server location where the store is provisioned will default to what BigCommerce has set as the default for your franchise. - Allowed values: `us-central1`, `europe-west3`, `australia-southeast1` - `settings` (PostStoreSettings, optional) — Object used to send any partner specific settings needed for configuring apps or other dashboard specific settings, such as shipping. These settings must be added to the allow list on your franchise or the request will be rejected. ## Response ### 200 Accepted - `data` (ResponseStorePostData, optional) ## Errors ### 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 a store already exists on the specified account with the same store name. Retry the request with a unique value for the store_name. - `status` (double, required) - `title` (string, required) - `type` (string, required) - `errors` (AccountsAccountIdStoresPostResponsesContentApplicationJsonSchemaErrors, required) ### 422 Unprocessable Entity Error Unprocessable Entity Several issues can result in a 422 return result. If the plan\_sku that is passed in the response body is not a allowed for your franchise, a 422 response is returned with the following error: ```json { "status": 422, "title": "Unprocessable entity", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "plan_type": "Unallowable plan type" } } ``` If required fields are missing, the given account in the request URL cannot be found, non-allowed list settings are passed, required allowed list settings are not provided, or the requested plan\_sku is not in the partner’s allowed plans, a 422 is returned. ```json { "status": 422, "title": "Bad Request", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "sku": "SKU is required." } } ``` Ex: If the account cannot be found: ```json { "status": 422, "title": "Bad Request", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "account_id": "not found" } } ``` Ex: If non-allow list settings are passed: ```json { "status": 422, "title": "Bad Request", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "settings": "Unaccepted settings values provided." } } ``` Ex: If required allow list settings are not passed: ```json { "status": 422, "title": "Bad Request", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "settings": "Required settings values not provided." } } ``` - `status` (double, optional) - `title` (string, optional) - `type` (string, optional) - `errors` (AccountsAccountIdStoresPostResponsesContentApplicationJsonSchemaErrors, 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 store 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` (AccountsAccountIdStoresPostResponsesContentApplicationJsonSchemaErrors, optional) ### 504 Gateway Timeout Error 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](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up (in several hours usually) - `status` (integer, optional) — The HTTP status code. - `title` (string, optional) — The error title describing the particular error. - `type` (string, optional) - `errors` (map from string to string, optional) ## Types ### PostStoreSettings Object used to send any partner specific settings needed for configuring apps or other dashboard specific settings, such as shipping. These settings must be added to the allow list on your franchise or the request will be rejected. - ` unique_setting_1 ` (string, optional) — Unique key value setting (must be defined in allowed settings on your franchise) - submitted with the Settings object above. - ` unique_setting_2 ` (string, optional) — Unique key value setting (must be defined in allowed settings on your franchise) - submitted with the Settings object above. - ` unique_setting_3 ` (string, optional) — Unique key value setting (must be defined in allowed settings on your franchise) - submitted with the Settings object above. ### ResponseStorePostData - `id` (string, optional) ### AccountsAccountIdStoresPostResponsesContentApplicationJsonSchemaErrors ## Examples **Request** ```json { "id": "S-0001934", "plan_sku": "TRIAL-30DAY", "store_name": "Husky", "country": "US", "settings": { "more_settings": "etc..." } } ``` **Response** ```json { "data": { "id": "string" } } ``` **SDK Code** ```python Example import requests url = "https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores" payload = { "id": "S-0001934", "plan_sku": "TRIAL-30DAY", "store_name": "Husky", "country": "US", "settings": { "more_settings": "etc..." } } headers = { "Accept": "application/json", "X-Auth-Client": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Example const url = 'https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores'; const options = { method: 'POST', headers: { Accept: 'application/json', 'X-Auth-Client': '', 'Content-Type': 'application/json' }, body: '{"id":"S-0001934","plan_sku":"TRIAL-30DAY","store_name":"Husky","country":"US","settings":{"more_settings":"etc..."}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores" payload := strings.NewReader("{\n \"id\": \"S-0001934\",\n \"plan_sku\": \"TRIAL-30DAY\",\n \"store_name\": \"Husky\",\n \"country\": \"US\",\n \"settings\": {\n \"more_settings\": \"etc...\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Client", "") 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 Example require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores") 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"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"id\": \"S-0001934\",\n \"plan_sku\": \"TRIAL-30DAY\",\n \"store_name\": \"Husky\",\n \"country\": \"US\",\n \"settings\": {\n \"more_settings\": \"etc...\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java Example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores") .header("Accept", "application/json") .header("X-Auth-Client", "") .header("Content-Type", "application/json") .body("{\n \"id\": \"S-0001934\",\n \"plan_sku\": \"TRIAL-30DAY\",\n \"store_name\": \"Husky\",\n \"country\": \"US\",\n \"settings\": {\n \"more_settings\": \"etc...\"\n }\n}") .asString(); ``` ```php Example request('POST', 'https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores', [ 'body' => '{ "id": "S-0001934", "plan_sku": "TRIAL-30DAY", "store_name": "Husky", "country": "US", "settings": { "more_settings": "etc..." } }', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Client' => '', ], ]); echo $response->getBody(); ``` ```csharp Example using RestSharp; var client = new RestClient("https://api.bigcommerce.com/franchises/franchise_uuid/v1/accounts/account_id/stores"); var request = new RestRequest(Method.POST); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Client", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"id\": \"S-0001934\",\n \"plan_sku\": \"TRIAL-30DAY\",\n \"store_name\": \"Husky\",\n \"country\": \"US\",\n \"settings\": {\n \"more_settings\": \"etc...\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Example import Foundation let headers = [ "Accept": "application/json", "X-Auth-Client": "", "Content-Type": "application/json" ] let parameters = [ "id": "S-0001934", "plan_sku": "TRIAL-30DAY", "store_name": "Husky", "country": "US", "settings": ["more_settings": "etc..."] ] 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/account_id/stores")! 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() ```