Fallback shipping methods

Fallback shipping methods are shipping options you define in Violet for a merchant, rather than rates the merchant's platform returns. They are stored per merchant and passed through to your channel according to the shipping settings:

• By default, fallback methods are offered alongside whatever rates the merchant's platform returns.

• With exclude_external_methods turned on, the applicable fallback methods replace the platform's rates. If no fallback method applies to the cart, the platform's rates pass through instead.

• With use_fallback_methods_on_empty turned on, fallback methods are held in reserve and passed through only when no platform rates remain after exclusions.

Anatomy of a fallback method

Field	Behavior
label	Required. The name shoppers see at checkout, such as Standard Shipping.
description	Optional. Stored with the method for reference; it is not currently passed through to your channel with the rate.
price	Required. What the shopper pays for this method, in cents. Use 0 for free shipping.
currency	Required. The ISO 4217 currency this price is charged in.
handle	A short unique identifier per merchant. Generated from the label if omitted.
calculation_type	PER_ORDER charges the price once for the whole order. PER_ITEM charges it for each item. Defaults to PER_ORDER.
conditions	Optional limits on when the method is offered: destination countries, specific offers, order amount, or order weight.

Full field tables, including every condition field, are in Merchant Configuration Resources.

Handles identify methods

Each method is addressed by its handle in these configuration endpoints. Creating a method without one generates a handle from the label, lowercased with hyphens, so "Standard Shipping" becomes "standard-shipping". If that handle is already taken, a numeric suffix is added ("standard-shipping-2"). Handles may contain letters, digits, hyphens, and underscores, up to 64 characters. Supplying a handle that already exists for the merchant returns 409 Conflict, and renaming a handle means deleting the old method and creating a new one.

The handle is not the shipping method ID your channel sees at checkout. That ID is derived from the method's label and price, so changing either one gives the method a new ID.

Example

Create a flat-rate method offered only for US and Canadian addresses on orders of at least $10:

POST /merchants/{merchant_id}/shipping-methods

{
  "label": "Standard Shipping",
  "description": "Arrives in 3 to 5 business days",
  "price": 500,
  "currency": "USD",
  "calculation_type": "PER_ORDER",
  "conditions": {
    "applicable_countries": ["US", "CA"],
    "min_order_amount": 1000
  }
}

Related

• When fallback methods are used covers holding these methods in reserve.

• Choosing which shipping rates are passed through covers excluding the platform's own rates.