Stripe Shipping Rates API
Shipping rates describe the price of shipping presented to your customers and applied to a purchase.
OpenAPI Specification
openapi: 3.0.0
info:
title: Stripe Shipping Rates API
description: Needs description.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/shipping_rates:
get:
description: <p>Returns a list of your shipping rates.</p>
operationId: GetShippingRates
parameters:
- description: Only return shipping rates that are active or inactive.
in: query
name: active
required: false
schema:
type: boolean
style: form
- description: >-
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.
explode: true
in: query
name: created
required: false
schema:
anyOf:
- properties:
gt:
type: integer
gte:
type: integer
lt:
type: integer
lte:
type: integer
title: range_query_specs
type: object
- type: integer
style: deepObject
- description: Only return shipping rates for the given currency.
in: query
name: currency
required: false
schema:
type: string
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
properties: {}
type: object
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
properties:
data:
items:
$ref: '#/components/schemas/shipping_rate'
type: array
has_more:
description: >-
True if this list has another page of items after this one
that can be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same
type share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/shipping_rates
type: string
required:
- data
- has_more
- object
- url
title: ShippingResourcesShippingRateList
type: object
x-expandableFields:
- data
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Shipping Rates
post:
description: <p>Creates a new shipping rate object.</p>
operationId: PostShippingRates
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
delivery_estimate:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
fixed_amount:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
properties:
delivery_estimate:
description: >-
The estimated range for how long shipping will take, meant
to be displayable to the customer. This will appear on
CheckoutSessions.
properties:
maximum:
properties:
unit:
enum:
- business_day
- day
- hour
- month
- week
type: string
value:
type: integer
required:
- unit
- value
title: delivery_estimate_bound
type: object
minimum:
properties:
unit:
enum:
- business_day
- day
- hour
- month
- week
type: string
value:
type: integer
required:
- unit
- value
title: delivery_estimate_bound
type: object
title: delivery_estimate
type: object
display_name:
description: >-
The name of the shipping rate, meant to be displayable to
the customer. This will appear on CheckoutSessions.
maxLength: 100
type: string
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
fixed_amount:
description: >-
Describes a fixed amount to charge for shipping. Must be
present if type is `fixed_amount`.
properties:
amount:
type: integer
currency:
type: string
currency_options:
additionalProperties:
properties:
amount:
type: integer
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
required:
- amount
title: currency_option
type: object
type: object
required:
- amount
- currency
title: fixed_amount
type: object
metadata:
additionalProperties:
type: string
description: >-
Set of [key-value
pairs](https://stripe.com/docs/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`.
type: object
tax_behavior:
description: >-
Specifies whether the rate is considered inclusive of taxes
or exclusive of taxes. One of `inclusive`, `exclusive`, or
`unspecified`.
enum:
- exclusive
- inclusive
- unspecified
type: string
tax_code:
description: >-
A [tax code](https://stripe.com/docs/tax/tax-categories) ID.
The Shipping tax code is `txcd_92010001`.
type: string
type:
description: >-
The type of calculation to use on the shipping rate. Can
only be `fixed_amount` for now.
enum:
- fixed_amount
type: string
required:
- display_name
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipping_rate'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Shipping Rates
/v1/shipping_rates/{shipping_rate_token}:
get:
description: <p>Returns the shipping rate object with the given ID.</p>
operationId: GetShippingRatesShippingRateToken
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: shipping_rate_token
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
properties: {}
type: object
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipping_rate'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Shipping Rates
post:
description: <p>Updates an existing shipping rate object.</p>
operationId: PostShippingRatesShippingRateToken
parameters:
- in: path
name: shipping_rate_token
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
expand:
explode: true
style: deepObject
fixed_amount:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
schema:
additionalProperties: false
properties:
active:
description: >-
Whether the shipping rate can be used for new purchases.
Defaults to `true`.
type: boolean
expand:
description: Specifies which fields in the response should be expanded.
items:
maxLength: 5000
type: string
type: array
fixed_amount:
description: >-
Describes a fixed amount to charge for shipping. Must be
present if type is `fixed_amount`.
properties:
currency_options:
additionalProperties:
properties:
amount:
type: integer
tax_behavior:
enum:
- exclusive
- inclusive
- unspecified
type: string
title: currency_option_update
type: object
type: object
title: fixed_amount_update
type: object
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- enum:
- ''
type: string
description: >-
Set of [key-value
pairs](https://stripe.com/docs/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_behavior:
description: >-
Specifies whether the rate is considered inclusive of taxes
or exclusive of taxes. One of `inclusive`, `exclusive`, or
`unspecified`.
enum:
- exclusive
- inclusive
- unspecified
type: string
type: object
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/shipping_rate'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
tags:
- Shipping Rates
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
shipping_rate:
description: >-
Shipping rates describe the price of shipping presented to your
customers and
applied to a purchase. For more information, see [Charge for
shipping](https://stripe.com/docs/payments/during-payment/charge-shipping).
properties:
active:
description: >-
Whether the shipping rate can be used for new purchases. Defaults to
`true`.
type: boolean
created:
description: >-
Time at which the object was created. Measured in seconds since the
Unix epoch.
format: unix-time
type: integer
delivery_estimate:
anyOf:
- $ref: '#/components/schemas/shipping_rate_delivery_estimate'
description: >-
The estimated range for how long shipping will take, meant to be
displayable to the customer. This will appear on CheckoutSessions.
nullable: true
display_name:
description: >-
The name of the shipping rate, meant to be displayable to the
customer. This will appear on CheckoutSessions.
maxLength: 5000
nullable: true
type: string
fixed_amount:
$ref: '#/components/schemas/shipping_rate_fixed_amount'
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
you can attach to an object. This can be useful for storing
additional information about the object in a structured format.
type: object
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- shipping_rate
type: string
tax_behavior:
description: >-
Specifies whether the rate is considered inclusive of taxes or
exclusive of taxes. One of `inclusive`, `exclusive`, or
`unspecified`.
enum:
- exclusive
- inclusive
- unspecified
nullable: true
type: string
tax_code:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/tax_code'
description: >-
A [tax code](https://stripe.com/docs/tax/tax-categories) ID. The
Shipping tax code is `txcd_92010001`.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/tax_code'
type:
description: >-
The type of calculation to use on the shipping rate. Can only be
`fixed_amount` for now.
enum:
- fixed_amount
type: string
required:
- active
- created
- id
- livemode
- metadata
- object
- type
title: ShippingRate
type: object
x-expandableFields:
- delivery_estimate
- fixed_amount
- tax_code
x-resourceId: shipping_rate
securitySchemes:
basicAuth:
description: >-
Basic HTTP authentication. Allowed headers-- Authorization: Basic
<api_key> | Authorization: Basic <base64 hash of `api_key:`>
scheme: basic
type: http
bearerAuth:
bearerFormat: auth-scheme
description: >-
Bearer HTTP authentication. Allowed headers-- Authorization: Bearer
<api_key>
scheme: bearer
type: http
tags:
- name: Shipping Rates