Sign in
checkout_rates

Add a delivery option

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

Changed in 1 of the 6 revisions of this API.18

  • f3a66d20456518See the full diff
    • ●

      added the new freight_connection_inactive enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_connection_inactive enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_connection_inactive enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    • ●

      added the new freight_provider_id_required enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_provider_id_required enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_provider_id_required enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_batchable enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_batchable enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_batchable enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_shipment_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_available enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_available enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_available enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 400

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 409

      response-property-enum-value-added

    • ●

      added the new freight_tracking_not_found enum value to the errors/items/allOf[subschema #1: error]/error_code/allOf[subschema #1: error_code]/ response property for the response status 500

      response-property-enum-value-added

    This revision also has 14 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog