checkout_rates

Update a delivery option

Changed on Oct 22, 2026

<aside class="access" aria-label="Endpoint access"> <table class="access__table"> <thead> <tr> <th class="access__table-header">Products</th> <th class="access__table-header">Plans</th> </tr> </thead> <tbody> <tr> <td class="access__table-cell access__product"> <img class="access__logo" src="/static/logos/shipstation-api-logo.svg" alt="ShipStation API Logo" loading="lazy" decoding="async"/> <div class="access__sub">Formerly ShipEngine</div> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-free.md" class="access__plan">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Advanced</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-api-advanced-enterprise.md" class="access__plan">Enterprise</a> </td> </tr> <tr> <td class="access__table-cell"> <img class="access__logo" src="/static/logos/shipstation-logo.svg" alt="ShipStation Logo" loading="lazy" decoding="async"/> </td> <td class="access__table-cell access__plans"> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Free</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-free-starter.md" class="access__plan access__plan--off">Starter</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Standard</a> <a href="/apis/@shipstation-v2/docs/getting-started/plans/shipstation-standard-premium.md" class="access__plan">Premium</a> </td> </tr> </tbody> </table> <footer class="access__footer"> <a class="access__help" href="/apis/@shipstation-v2/docs/getting-started/products-and-plans.md"> Learn about products and plans <img src="/static/icons/external-link.svg" alt="External Link Icon" style="width: 16px;" loading="lazy" decoding="async"/> </a> </footer> </aside>

Replace the configuration of an existing delivery option. Option names must remain unique within a configuration; renaming an option to a name already in use returns a 409 Conflict.

put/v2/checkout_rates/{config_id}/options/{option_id}

Request

Base URL
https://api.shipstation.com
URL
https://api.shipstation.com/v2/checkout_rates/{config_id}/options/{option_id}
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 updated.

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, 20264e29670aa28d 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, 2026934f5935dbea 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
  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)