Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
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.

Endpoints

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.

  • metadataobject

    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": "shr_1MrRx2LkdIwHu7ixikgEA6Wd",
  "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 

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.

  • fixed_amountobject

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

  • metadataobject

    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.

POST /v1/shipping_rates
const stripe = require('stripe')('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
const shippingRate = await stripe.shippingRates.create({
  display_name: 'Ground shipping',
  type: 'fixed_amount',
  fixed_amount: {
    amount: 500,
    currency: 'usd',
  },
});
Response
{
  "id": "shr_1MrRx2LkdIwHu7ixikgEA6Wd",
  "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"
}

Update a shipping rate 

Updates an existing shipping rate object.

Parameters

  • activeboolean

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

  • fixed_amountobject

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

  • metadataobject

    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

Returns

Returns the modified shipping rate object if the call succeeded.

POST /v1/shipping_rates/:id
const stripe = require('stripe')('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
const shippingRate = await stripe.shippingRates.update(
  'shr_1MrRx2LkdIwHu7ixikgEA6Wd',
  {
    metadata: {
      order_id: '6735',
    },
  }
);
Response
{
  "id": "shr_1MrRx2LkdIwHu7ixikgEA6Wd",
  "object": "shipping_rate",
  "active": true,
  "created": 1680207604,
  "delivery_estimate": null,
  "display_name": "Ground shipping",
  "fixed_amount": {
    "amount": 500,
    "currency": "usd"
  },
  "livemode": false,
  "metadata": {
    "order_id": "6735"
  },
  "tax_behavior": "unspecified",
  "tax_code": null,
  "type": "fixed_amount"
}

Retrieve a shipping rate 

Returns the shipping rate object with the given ID.

Parameters

No parameters.

Returns

Returns a shipping rate object if a valid identifier was provided.

GET /v1/shipping_rates/:id
const stripe = require('stripe')('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
const shippingRate = await stripe.shippingRates.retrieve(
  'shr_1MrRx2LkdIwHu7ixikgEA6Wd'
);
Response
{
  "id": "shr_1MrRx2LkdIwHu7ixikgEA6Wd",
  "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"
}