> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/merchants/configuration/fallback-shipping-methods.md).

# 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`](/prism/merchants/configuration/choosing-shipping-rates.md) 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`](/prism/merchants/configuration/when-fallback-methods-apply.md) 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](/prism/merchants/merchant-configuration-resources.md#shipping-methods).

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

{% hint style="info" %}
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.
{% endhint %}

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

```json
{
  "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](/prism/merchants/configuration/when-fallback-methods-apply.md) covers holding these methods in reserve.
* [Choosing which shipping rates are passed through](/prism/merchants/configuration/choosing-shipping-rates.md) covers excluding the platform's own rates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.violet.io/prism/merchants/configuration/fallback-shipping-methods.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.