openapi: 3.0.0
info:
  title: Stripe Shipping Rates API
  description: Needs description.
  contact:
    email: dev-platform@stripe.com
    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