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
Webhooks

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
curl https://api.stripe.com/v1/shipping_rates \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d display_name="Ground shipping" \
  -d type=fixed_amount \
  -d "fixed_amount[amount]"=500 \
  -d "fixed_amount[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
curl https://api.stripe.com/v1/shipping_rates/shr_1MrRx2LkdIwHu7ixikgEA6Wd \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d "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
curl https://api.stripe.com/v1/shipping_rates/shr_1MrRx2LkdIwHu7ixikgEA6Wd \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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"
}

List all shipping rates 

Returns a list of your shipping rates.

Parameters

  • activeboolean

    Only return shipping rates that are active or inactive.

  • createdobject

    A filter on the list, based on the object created field. The value can be a string with an integer Unix timestamp, or it can be a dictionary with a number of different query options.

  • currencyenum

    Only return shipping rates for the given currency.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit shipping rates, starting after shipping rate starting_after. Each entry in the array is a separate shipping rate object. If no more shipping rates are available, the resulting array will be empty. This require should never raise an error.

GET /v1/shipping_rates
curl -G https://api.stripe.com/v1/shipping_rates \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/shipping_rates",
  "has_more": false,
  "data": [
    {
      "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"
    }
  ]
}