close
Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Shipping Rates

Shipping rates describe the price of shipping presented to your customers and applied to a purchase. For more information, see Charge for shipping.

Was this section helpful?YesNo
Create a shipping rate
POST/v1/shipping_rates
Update a shipping rate
POST/v1/shipping_rates/:id
Retrieve a shipping rate
GET/v1/shipping_rates/:id
List all shipping rates
GET/v1/shipping_rates

The Shipping Rate object

Attributes

  • idstring

    Unique identifier for the object.

  • activeboolean

    Whether the shipping rate can be used for new purchases. Defaults to true.

  • display_namenullable string

    The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.

  • fixed_amountnullable object

    Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

  • metadatamap

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • tax_behaviornullable enum

    Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

    Possible enum values
    exclusive
    inclusive
    unspecified

  • tax_codenullable stringExpandable

    A tax code ID. The Shipping tax code is txcd_92010001.

  • typeenum

    The type of calculation to use on the shipping rate.

    Possible enum values
    fixed_amount

    The shipping rate is a fixed amount.

More attributes

  • objectstring

  • createdtimestamp

  • delivery_estimatenullable object

  • livemodeboolean

The Shipping Rate object
{
  "id": "",
  "object": "shipping_rate",
  "active": true,
  "created": 1680207604,
  "delivery_estimate": null,
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "livemode": false,
  "metadata": {},
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}

Create a shipping rate

POST /v1/shipping_rates

Creates a new shipping rate object.

Parameters

  • display_namestringRequired

    The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.

    The maximum length is 100 characters.

  • fixed_amountobject

    Describes a fixed amount to charge for shipping. Must be present if type is fixed_amount.

  • metadatamap

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • tax_behaviorenumRecommended if calculating taxes

    Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified.

    Possible enum values
    exclusive
    inclusive
    unspecified

  • tax_codestringRecommended if calculating taxes

    A tax code ID. The Shipping tax code is txcd_92010001.

  • typeenumRequired

    The type of calculation to use on the shipping rate.

    Possible enum values
    fixed_amount

    The shipping rate is a fixed amount.

More parameters

  • delivery_estimateobject

Returns

Returns a shipping rate object if the call succeeded.

curl https://api.stripe.com/v1/shipping_rates \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "display_name=Ground shipping" \
  -d type=fixed_amount \
  -d "fixed_amount[amount]=500" \
  -d "fixed_amount[currency]=usd"
Response
{
  "id": "",
  "object": "shipping_rate",
  "active": true,
  "created": 1680207604,
  "delivery_estimate": null,
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "livemode": false,
  "metadata": {},
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}