checkout_rates

Add a delivery option

Changed on Oct 22, 2026

Add a delivery option to an existing checkout rates configuration. Option names must be unique within a configuration; adding an option whose name already exists returns a 409 Conflict.

post/v1/checkout_rates/{config_id}/options

Request

Base URL: https://api.shipengine.com
URL: https://api.shipengine.com/v1/checkout_rates/{config_id}/options
Auth: API key in header API-Key

Request body

namestring required

The display name of the delivery option. Must be unique within the configuration.

type'live_rate' | 'flat_rate' | 'free' | 'local_delivery' required

The kind of delivery option.

fee_mode'add' | 'subtract'

Whether the fee defined by fee_percentage is added to or subtracted from the carrier rate. Omit for a pass-through rate.

fee_percentagenumber

The percentage of the carrier rate to add or subtract, according to fee_mode.

sort_indexinteger

The position of this option relative to the others in the configuration, ascending.

fallback_mode'dont_show' | 'flat_rate' | 'cart_percentage'

What to show when live rates cannot be retrieved. dont_show hides the option; flat_rate shows fallback_rate_amount/fallback_rate_currency; cart_percentage shows fallback_percentage of the cart total.

fallback_rate_amountnumber

The fixed fallback price, when fallback_mode is flat_rate.

fallback_rate_currencystring

The currency of fallback_rate_amount.

fallback_percentagenumber

The percentage of the cart total to charge, when fallback_mode is cart_percentage.

amountnumber

The fixed price for a flat_rate option.

currencystring

The currency of amount.

Example request

{
  "name": "Standard Shipping",
  "type": "live_rate",
  "services": [
    {
      "carrier_id": "se-1234567",
      "service_code": "usps_priority_mail"
    }
  ],
  "fee_mode": "add",
  "fee_percentage": 10,
  "fallback_mode": "flat_rate",
  "fallback_rate_amount": 5,
  "fallback_rate_currency": "USD",
  "fallback_percentage": 5,
  "amount": 4.99,
  "currency": "USD"
}

Response

The delivery option was added.

option_idinteger

The unique identifier of the delivery option.

config_idstring

The identifier of the configuration this option belongs to.

namestring

The display name of the delivery option.

type'live_rate' | 'flat_rate' | 'free' | 'local_delivery'

The kind of delivery option.

fee_mode'add' | 'subtract'

Whether fee_percentage is added to or subtracted from the carrier rate.

fee_percentagenumber

The percentage of the carrier rate added or subtracted, according to fee_mode.

sort_indexinteger

The position of this option relative to the others in the configuration, ascending.

fallback_mode'dont_show' | 'flat_rate' | 'cart_percentage'

What is shown when live rates cannot be retrieved.

fallback_rate_amountnumber

The fixed fallback price, when fallback_mode is flat_rate.

fallback_rate_currencystring

The currency of fallback_rate_amount.

fallback_percentagenumber

The percentage of the cart total charged, when fallback_mode is cart_percentage.

amountnumber

The fixed price for a flat_rate option.

currencystring

The currency of amount.

is_activeboolean

Whether the option is active and shown at checkout.

created_atstring date-time

When the option was created.

Example response

{
  "option_id": 100001,
  "config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Standard Shipping",
  "type": "live_rate",
  "services": [
    {
      "carrier_id": "se-1234567",
      "service_code": "usps_priority_mail"
    }
  ],
  "fee_mode": "add",
  "fee_percentage": 10,
  "fallback_mode": "flat_rate",
  "fallback_rate_amount": 5,
  "fallback_rate_currency": "USD",
  "fallback_percentage": 5,
  "currency": "USD",
  "is_active": true,
  "created_at": "2026-05-15T18:30:00Z"
}

Changes

Oct 22, 2026e998dffc42be Revision changes
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new bring_your_own_label_not_supported enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new multiple_sales_orders enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
- warning
  added the new sales_order_link_required enum value to the // response property for the response status
Oct 9, 2026020f57d6f5b8 Revision changes
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- breaking
  the / response's property type changed from no type to object for status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  added the optional property // to the response with the status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  removed from the / response property allOf list for the response status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status
- info
  added the required property // to the response with the status

Operation history (4 revisions)