Sample - Stripe API
POST/v1/shipping_rates

Create a shipping rate

Creates a new shipping rate for display to customers and application to purchases. Supply display_name and configure the calculation type, fixed amount, tax behavior, and delivery estimate as needed. The created rate can appear in Checkout Sessions.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

8 body fields

Shipping-rate configuration for the customer-facing name, delivery estimate, fixed charge, metadata, and tax treatment.

delivery_estimateobjectoptional
The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.
display_namestringrequired
The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.
expandarray<string>optional
Specifies which fields in the response should be expanded.
fixed_amountobjectoptional
Describes a fixed amount to charge for shipping. Must be present if type is `fixed_amount`.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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_behaviorstringoptional
Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`.
Allowed:exclusiveinclusiveunspecified
tax_codestringoptional
A [tax code](https://docs.stripe.com/tax/tax-categories) ID. The Shipping tax code is `txcd_92010001`.
typestringoptional
The type of calculation to use on the shipping rate.
Allowed:fixed_amount

2 status codes
200Returns the created shipping-rate object with its identifier, active state, display name, fixed amount, tax settings, metadata, and creation time.
activebooleanrequired
Whether the shipping rate can be used for new purchases. Defaults to `true`.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
delivery_estimateobjectoptional
The estimated range for how long shipping will take, meant to be displayable to the customer. This will appear on CheckoutSessions.
display_namestringoptional
The name of the shipping rate, meant to be displayable to the customer. This will appear on CheckoutSessions.
fixed_amountobjectoptional
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectrequired
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:shipping_rate
tax_behaviorstringoptional
Specifies whether the rate is considered inclusive of taxes or exclusive of taxes. One of `inclusive`, `exclusive`, or `unspecified`.
Allowed:exclusiveinclusiveunspecified
tax_codestringoptional
A [tax code](https://docs.stripe.com/tax/tax-categories) ID. The Shipping tax code is `txcd_92010001`.
typestringrequired
The type of calculation to use on the shipping rate.
Allowed:fixed_amount
defaultError response.
errorobjectrequired

Error handling

display_name is required and must not exceed 100 characters. type must be fixed_amount, tax_behavior must be inclusive, exclusive, or unspecified, and fixed_amount must include amount and currency when used.