> 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 Plan Change

POST https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/{store_id}/change-plan
Content-Type: application/json

Create Store Plan Change

Reference: https://docs.bigcommerce.com/developer/docs/beta/powered-by/api-reference/plans/create-store-plan-change

## 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

- `store_id` (string, required) — The ID of the store.

### 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.

- `plan_sku` (string, required) — The new BigCommerce plan type. The allow list for SKUs is configured on your franchise.
- `effective` (enum, optional) — Effective date for the plan change. Acceptable values: * IMMEDIATELY - the change is effective immediately * BILLCYCLEDAY - the change becomes effective at the start of the merchant’s next billing cycle, with the exception of trial accounts which are effective immediately. If the field is not specified, the change will become effective immediately. If the field is specified and the value does not match the values above, the change will become effective immediately.
  - Allowed values: `IMMEDIATELY`, `BILLCYCLEDAY`

## Response

### 200

Success

- `data` (StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaData, optional)
- `meta` (StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaMeta, 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)

### 404 Not Found Error

Not Found If a store with the given `store_id` does not exist, you will get a 404 Not Found.

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

### 422 Unprocessable Entity Error

Unprocessable Entity There are several circumstances that result in a 422 error response. If the plan\_sku 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 the plan\_sku passed in the response body is already on the store, 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": "Failed to change plan. The store is already on the requested plan." } } ``` If required fields are missing, a 422 response is returned with the following error: ```json { "status": 422, "title": "Bad Request", "type": "/developer/api-reference/rest/overview#rest-http-status-codes", "errors": { "sku": "SKU is required." } } ```

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

### 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)
- `errors` (StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaErrors, required)

### 503 Service Unavailable Error

Service Unavailable If this occurs, you should retry the request. 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.

- `status` (integer, optional)
- `title` (string, optional)
- `type` (string, 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](https://status.bigcommerce.com/). A service is likely down and the request will need to be made again when it is back up.

- `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

### StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaData

- `status` (string, optional)
- `id` (string, optional)
- `plan_sku` (string, optional)
- `name` (string, optional)
- `country` (string, optional)
- `allocated_at` (string, optional)
- `cancels_on` (string, optional)
- `expires_at` (string, optional)
- `primary_hostname` (string, optional)
- `canonical_hostname` (string, optional)
- `store_hash` (string, optional)

### StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaMeta

### StoresStoreIdChangePlanPostResponsesContentApplicationJsonSchemaErrors

## Examples

**Request**

```json
{
  "plan_sku": "TRIAL-30DAY",
  "effective": "IMMEDIATELY"
}
```

**Response**

```json
{
  "data": {
    "status": "active",
    "id": "S-0001934",
    "plan_sku": "TRIAL-30DAY",
    "name": "Husky",
    "country": "US",
    "allocated_at": "2018-05-23 14:04:34.0",
    "cancels_on": "nil",
    "expires_at": "2018-06-23",
    "primary_hostname": "www.husky.com",
    "canonical_hostname": "store-da234.mybigcommerce.com",
    "store_hash": "da234"
  },
  "meta": {}
}
```

**SDK Code**

```python Example
import requests

url = "https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/store_id/change-plan"

payload = {
    "plan_sku": "TRIAL-30DAY",
    "effective": "IMMEDIATELY"
}
headers = {
    "Accept": "application/json",
    "X-Auth-Client": "<apiKey>",
    "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/stores/store_id/change-plan';
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'X-Auth-Client': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{"plan_sku":"TRIAL-30DAY","effective":"IMMEDIATELY"}'
};

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/stores/store_id/change-plan"

	payload := strings.NewReader("{\n  \"plan_sku\": \"TRIAL-30DAY\",\n  \"effective\": \"IMMEDIATELY\"\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 Example
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/store_id/change-plan")

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  \"plan_sku\": \"TRIAL-30DAY\",\n  \"effective\": \"IMMEDIATELY\"\n}"

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

```java Example
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/stores/store_id/change-plan")
  .header("Accept", "application/json")
  .header("X-Auth-Client", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"plan_sku\": \"TRIAL-30DAY\",\n  \"effective\": \"IMMEDIATELY\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/store_id/change-plan', [
  'body' => '{
  "plan_sku": "TRIAL-30DAY",
  "effective": "IMMEDIATELY"
}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Client' => '<apiKey>',
  ],
]);

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

```csharp Example
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/store_id/change-plan");
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  \"plan_sku\": \"TRIAL-30DAY\",\n  \"effective\": \"IMMEDIATELY\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Client": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "plan_sku": "TRIAL-30DAY",
  "effective": "IMMEDIATELY"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/franchises/franchise_uuid/v1/stores/store_id/change-plan")! 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()
```