The Custom shipping provider lets you connect StoreConnect to your own rate calculation endpoint. At checkout, StoreConnect sends cart and address details to your endpoint as a JSON POST request. Your endpoint returns the available shipping rates, which are displayed to the customer alongside any other configured shipping options.

Custom providers support rate fetching only — shipment lodging and tracking are not supported.

## How it works

1. StoreConnect sends a POST request to your endpoint with cart details (items, weights, dimensions, addresses).
2. Your endpoint calculates available rates and returns them in the expected JSON format.
3. StoreConnect displays the returned rates at checkout.
4. Each unique rate `code` in your response automatically creates a **Shipping Carrier Product** record, which you can customise in Salesforce.

## Configure the shipping provider

Create a **Shipping Provider** record on your Store with these values:

| Field | Value |
|---|---|
| **Provider** | Custom |
| **API URL** | Full HTTPS URL of your rate endpoint, e.g. `https://rates.example.com/shipping` |
| **API Key** | Your primary credential (used as bearer token, basic auth username, or API key) |
| **API Secret** | Your secondary credential (used only for Basic Auth) |
| **API Options** | JSON object specifying authentication method (see below) |
| **Zone** | The geographic zone this provider serves |
| **Active** | Checked |

:::note
The API URL must include the full URL with `https://` protocol for custom providers.
:::

## Authentication methods

Set the **API Options** field to a JSON object that specifies how StoreConnect authenticates with your endpoint.

### Bearer token (default)

```json
{"auth_type": "bearer"}
```

Sends: `Authorization: Bearer {api_key}`

### HTTP basic auth

```json
{"auth_type": "basic_auth"}
```

Sends: `Authorization: Basic {base64(api_key:api_secret)}`

### API key header

```json
{"auth_type": "api_key"}
```

Sends: `X-API-Key: {api_key}`

To use a custom header name:

```json
{"auth_type": "api_key", "auth_header_name": "X-My-Auth-Header"}
```

### Custom headers

Send multiple custom headers with static or credential-derived values:

```json
{
  "auth_type": "custom_headers",
  "custom_headers": {
    "X-API-Username": "field:s_c__api_key__c",
    "X-API-Password": "field:s_c__api_secret__c",
    "X-Location-Id": "warehouse-sydney"
  }
}
```

Values prefixed with `field:` are resolved from the Shipping Provider record. Allowed field references: `field:s_c__api_key__c`, `field:s_c__api_secret__c`. Values without a prefix are sent as literal strings.

All header names must contain only letters, numbers, and hyphens.

## Request payload

StoreConnect sends a POST request with `Content-Type: application/json`. The body contains:

```json
{
  "currency": "AUD",
  "shipping_address": {
    "name": "Customer name",
    "street": "123 Example St",
    "city": "Sydney",
    "state": "NSW",
    "postal_code": "2000",
    "country": "AU"
  },
  "origin_address": {
    "street": "1 Warehouse Rd",
    "city": "Melbourne",
    "state": "VIC",
    "postal_code": "3000",
    "country": "AU"
  },
  "items": [
    {
      "sku": "PROD-001",
      "name": "Example Product",
      "quantity": 2,
      "unit_price": 29.95,
      "weight": 0.5,
      "length": 10.0,
      "width": 10.0,
      "height": 5.0
    }
  ],
  "totals": {
    "item_total": 59.90,
    "total_weight": 1.0
  }
}
```

Weights are in kilograms. Dimensions are in centimetres.

## Response format

Your endpoint must return HTTP 200 with a JSON body:

```json
{
  "rates": [
    {
      "code": "standard",
      "name": "Standard Shipping",
      "price_ex_tax": 9.95,
      "tax": 1.00,
      "instructions": "Delivered in 3–5 business days"
    },
    {
      "code": "express",
      "name": "Express Shipping",
      "price_ex_tax": 19.95,
      "tax": 2.00
    }
  ]
}
```

The `instructions` field is optional and is displayed to the customer on the checkout shipping step. If an error occurs, return HTTP 200 with an `error` key:

```json
{"error": "Unable to calculate rates for this address"}
```

:::tip
Each unique `code` value creates a Shipping Carrier Product record in Salesforce. You can rename, reorder, or hide these records to control how rates appear at checkout.
:::

## Allow products to use the custom provider

For custom provider rates to appear at checkout, each product must be configured to allow it. On each product record, find the **Shipping Methods** multi-select picklist field and add **Custom**.

If Custom does not appear in the picklist, ask your Salesforce System Admin to add a new picklist value with the API Name **Custom**.

## Limitations

- Rate fetching only — shipment lodging and carrier tracking are not supported.
- Your endpoint must respond within 30 seconds.
- The request payload structure is fixed and cannot be customised.
- If your endpoint returns an error or times out, other configured shipping rates still display at checkout.