> 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 Carrier Connection

POST https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/carrier/connection
Content-Type: application/json

Creates a *Carrier Connection*.

Carrier connections refer to specific settings required to connect to a specific shipping carrier. Each carrier requires your app to supply a unique set of properties/fields to establish a connection with that carrier.

*Notes:*

* There is no `GET` with this resource. It has `PUT`, `POST` and `DELETE`.
  * `PUT` is used to update. The connection can be updated by API.

* Connections created here do not enable the shipping method. To enable the carrier for a shipping zone, use the Shipping Methods API.

* The Carrier Connection resource returns a 204 for both successful and unsuccessful attempts to connect. If a field is missing, it will return a 400.

### Australia Post

PUT or POST example request:

```json
{
  "carrier_id" : "auspost",
  "connection" : {
    "auth_key" : "yourAusPostAuthKey",
    "test_mode" : false
  }
}
```

DELETE example request:

```json
{
  "carrier_id" : "auspost"
}
```

#### Australia Post Connection Object – Properties

Australia Post `PUT` or `POST` requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) `DELETE` requests require only a `carrier_id`.

| Property   | Type    | Description                                                                                       |
| ---------- | ------- | ------------------------------------------------------------------------------------------------- |
| auth\_key  | string  | Australia Post authorization key.                                                                 |
| test\_mode | boolean | Whether or not to use Australia Post test-mode settings. Acceptable values are `true` or `false`. |

### Endicia

USPS is connected through Endicia.

PUT or POST example request:

```json
{  "carrier_id" : "endicia",
  "connection": {
    "account_id" : "yourEndiciaAccountId",
    "pass_phrase" : "yourEndiciaPassphrase"
  }
}
```

DELETE example request:

```json
{
  "carrier_id" : "endicia"
}
```

#### Endicia Connection Object – Properties

Endicia `PUT` or `POST` requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) `DELETE` requests require only a `carrier_id`.

| Property    | Type   | Description         |
| ----------- | ------ | ------------------- |
| account\_id | string | Endicia account ID. |
| passphrase  | string | Endicia passphrase. |

### FedEx

PUT or POST example request:

```json
{
  "carrier_id" : "fedex",
  "connection" : {
    "key" : "yourFedexKey",
    "password" : "yourFedexPassword",
    "account_number" : "yourFedexAccountNumber",
    "meter_number" : "yourFedexMeterNumber"
  }
}
```

DELETE example request:

```json
{
  "carrier_id" : "fedex"
}
```

#### FedEx Connection Object – Properties

FedEx `PUT` or `POST` requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) `DELETE` requests require only a `carrier_id`.

| Property        | Type   | Description           |
| --------------- | ------ | --------------------- |
| key             | string | FedEx account ID.     |
| password        | string | FedEx passphrase.     |
| account\_number | string | FedEx account number. |
| meter\_number   | string | FedEx meter number.   |

### Royal Mail

PUT or POST example request:

```json
{
    "carrier_id" : "royalmail",
    "connection" : {

    }
}
```

DELETE example request:

```json
{
    "carrier_id" : "royalmail"
}
```

#### Royal Mail Connection Object - Properties

Royal Mail has no connection object properties.

### Shipping Provider API

Please note that this endpoint is not intended for adding connection settings.

Its purpose is solely to establish a connection between your BigCommerce store and the carrier. If the carrier has no connection settings configured, please leave the connection property empty. However, if the carrier already has connection settings configured, you can utilize this endpoint to establish the connection using the existing connection properties.

PUT or POST example request when your carrier is not configured with any connection settings:

```json filename="No connection settings configured" showLineNumbers copy
{
  "carrier_id" : "carrier_{your_carrier_id}",
  "connection" : {}
}
```

PUT or POST example request when your carrier is configured with connection settings:

```json filename="Connection settings configured" showLineNumbers copy
{
  "carrier_id" : "carrier_{your_carrier_id}",
  "connection" : {
    "your_configured_key_1": "value_1",
    "your_configured_key_2": "value_2
  }
}
```

### Zoom2U

PUT or POST example request:

```json
{
  "carrier_id" : "zoom2u",
  "connection" : {
    "auth_key" : "yourZoom2uAuthKey",
    "test_mode" : false
  }
}
```

DELETE example request:

```json
{
  "carrier_id" : "zoom2u"
}
```

#### Zoom2U Connection Object – Properties

Zoom2U `PUT` or `POST` requests require all of the following properties. (These requests won’t be fulfilled unless these properties are valid.) `DELETE` requests require only a `carrier_id`.

| Property   | Type    | Description                                                                               |
| ---------- | ------- | ----------------------------------------------------------------------------------------- |
| auth\_key  | string  | Zoom2U authorization key.                                                                 |
| test\_mode | boolean | Whether or not to use Zoom2U test-mode settings. Acceptable values are `true` or `false`. |

Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/shipping/v2/shipping-carrier/create-carrier-connection

## Authentication

- `X-Auth-Token` header (required) — ### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Information & Settings | modify | `store_v2_information` | | Information & Settings | read-only | `store_v2_information_read_only` | ### Authentication header | Header | Argument | Description | | - | - | - | | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

## Request

### Path parameters

- `store_hash` (string, required) — Permanent ID of the BigCommerce 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 a carrierConnection.

- `carrier_id` (string, optional)
- `connection` (CarrierConnectionConnection, optional) — The `connection` object varies by carrier.

## Response

### 204

Returns if request was successful.

## Errors

### 400 Bad Request Error

Invalid requests will return a 400 response. \[ \{ "status": 400, "message": "The field 'id' cannot be written to. Please remove it from your request before trying again." } ] If a required field is not provided, the request will return a 400 response. \[ \{ "status": 400, "message": "Required fields missing \[key]" } ]

- `any`

## Types

### CarrierConnectionConnection

The `connection` object varies by carrier.

## Examples

**Request**

```json
{
  "carrier_id": "auspost",
  "connection": {
    "auth_key": "yourAusPostAuthKey",
    "test_mode": false
  }
}
```

**SDK Code**

```python Shipping Carrier_createCarrierConnection_example
import requests

url = "https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection"

payload = {
    "carrier_id": "auspost",
    "connection": {
        "auth_key": "yourAusPostAuthKey",
        "test_mode": False
    }
}
headers = {
    "Accept": "application/json",
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript Shipping Carrier_createCarrierConnection_example
const url = 'https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection';
const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'X-Auth-Token': '<apiKey>',
    'Content-Type': 'application/json'
  },
  body: '{"carrier_id":"auspost","connection":{"auth_key":"yourAusPostAuthKey","test_mode":false}}'
};

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

```go Shipping Carrier_createCarrierConnection_example
package main

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

func main() {

	url := "https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection"

	payload := strings.NewReader("{\n  \"carrier_id\": \"auspost\",\n  \"connection\": {\n    \"auth_key\": \"yourAusPostAuthKey\",\n    \"test_mode\": false\n  }\n}")

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

	req.Header.Add("Accept", "application/json")
	req.Header.Add("X-Auth-Token", "<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 Shipping Carrier_createCarrierConnection_example
require 'uri'
require 'net/http'

url = URI("https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection")

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-Token"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"carrier_id\": \"auspost\",\n  \"connection\": {\n    \"auth_key\": \"yourAusPostAuthKey\",\n    \"test_mode\": false\n  }\n}"

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

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

HttpResponse<String> response = Unirest.post("https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection")
  .header("Accept", "application/json")
  .header("X-Auth-Token", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"carrier_id\": \"auspost\",\n  \"connection\": {\n    \"auth_key\": \"yourAusPostAuthKey\",\n    \"test_mode\": false\n  }\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection', [
  'body' => '{
  "carrier_id": "auspost",
  "connection": {
    "auth_key": "yourAusPostAuthKey",
    "test_mode": false
  }
}',
  'headers' => [
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
    'X-Auth-Token' => '<apiKey>',
  ],
]);

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

```csharp Shipping Carrier_createCarrierConnection_example
using RestSharp;

var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("X-Auth-Token", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"carrier_id\": \"auspost\",\n  \"connection\": {\n    \"auth_key\": \"yourAusPostAuthKey\",\n    \"test_mode\": false\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Shipping Carrier_createCarrierConnection_example
import Foundation

let headers = [
  "Accept": "application/json",
  "X-Auth-Token": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "carrier_id": "auspost",
  "connection": [
    "auth_key": "yourAusPostAuthKey",
    "test_mode": false
  ]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v2/shipping/carrier/connection")! 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()
```