Medusa Shipping Options API

openapi: 3.2.0
info:
  title: Medusa Shipping Options API
  version: 2.19.0
  description: 'Operations tagged Shipping Options across 2 of this provider''s published API definitions: medusa-admin-openapi.yaml, medusa-store-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Shipping Options
  description: 'A shipping option is a way of shipping an item to or from the customer.


    Shipping options are associated with the fulfillment provider used to handle their fulfillment.


    Shipping options can be restricted geographically by service zones, and by custom rules, such as an item''s weight or the customer''s group.


    These API routes allow admins to manage shipping options.

    '
  externalDocs:
    description: Learn more about shipping options.
    url: https://docs.medusajs.com/resources/commerce-modules/fulfillment/shipping-option
  x-associatedSchema:
    $ref: '#/components/schemas/AdminShippingOption'
paths:
  /admin/shipping-options:
    get:
      operationId: GetShippingOptions
      summary: List Shipping Options
      description: Retrieve a list of shipping options. The shipping options can be filtered by fields such as `id`. The shipping options can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by a shipping option ID.
          - type: array
            description: Filter by shipping option IDs.
            items:
              type: string
              title: id
              description: A shipping option's ID.
      - name: q
        in: query
        description: Search term to filter the shipping option's searchable properties.
        required: false
        schema:
          type: string
          title: q
          description: Search term to filter the shipping option's searchable properties.
      - name: service_zone_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: service_zone_id
            description: Filter by a service zone's ID to retrieve its associated shipping options.
          - type: array
            description: Filter by service zone IDs to retrieve their associated shipping options.
            items:
              type: string
              title: service_zone_id
              description: A service zone ID.
      - name: shipping_profile_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: shipping_profile_id
            description: Filter by a shipping profile's ID to retrieve its associated shipping options.
          - type: array
            description: Filter by shipping profile IDs to retrieve their associated shipping options.
            items:
              type: string
              title: shipping_profile_id
              description: A shipping profile ID.
      - name: provider_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: provider_id
            description: Filter by a fulfillment provider's ID to retrieve its associated shipping options.
          - type: array
            description: Filter by fulfillment provider IDs to retrieve their associated shipping options.
            items:
              type: string
              title: provider_id
              description: A fulfillment provider ID.
      - name: shipping_option_type_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: shipping_option_type_id
            description: Filter by a shipping option type's ID to retrieve its associated shipping options.
          - type: array
            description: Filter by shipping option type IDs to retrieve its associated shipping options.
            items:
              type: string
              title: shipping_option_type_id
              description: A shipping option type ID.
      - name: created_at
        in: query
        description: Filter by a shipping option's creation date.
        required: false
        schema:
          type: object
          description: Filter by a shipping option's creation date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by an exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: created_at
      - name: updated_at
        in: query
        description: Filter by a shipping option's update date.
        required: false
        schema:
          type: object
          description: Filter by a shipping option's update date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by an exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: updated_at
      - name: deleted_at
        in: query
        description: Filter by a shipping option's deletion date.
        required: false
        schema:
          type: object
          description: Filter by a shipping option's deletion date.
          properties:
            $and:
              type: array
              description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $and
            $or:
              type: array
              description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
              items:
                type: object
              title: $or
            $eq:
              oneOf:
              - type: string
                title: $eq
                description: Filter by an exact match.
              - type: array
                description: Filter by an exact match.
                items:
                  type: string
                  title: $eq
                  description: Filter by an exact match.
            $ne:
              type: string
              title: $ne
              description: Filter by values not equal to this parameter.
            $in:
              type: array
              description: Filter by values in this array.
              items:
                type: string
                title: $in
                description: Filter by values in this array.
            $nin:
              type: array
              description: Filter by values not in this array.
              items:
                type: string
                title: $nin
                description: Filter by values not in this array.
            $not:
              oneOf:
              - type: string
                title: $not
                description: Filter by values not matching the conditions in this parameter.
              - type: object
                description: Filter by values not matching the conditions in this parameter.
              - type: array
                description: Filter by values not matching the conditions in this parameter.
                items:
                  type: string
                  title: $not
                  description: Filter by values not matching the conditions in this parameter.
            $gt:
              type: string
              title: $gt
              description: Filter by values greater than this parameter. Useful for numbers and dates only.
            $gte:
              type: string
              title: $gte
              description: Filter by values greater than or equal to this parameter. Useful for numbers and dates only.
            $lt:
              type: string
              title: $lt
              description: Filter by values less than this parameter. Useful for numbers and dates only.
            $lte:
              type: string
              title: $lte
              description: Filter by values less than or equal to this parameter. Useful for numbers and dates only.
            $like:
              type: string
              title: $like
              description: Apply a `like` filter. Useful for strings only.
            $re:
              type: string
              title: $re
              description: Apply a regex filter. Useful for strings only.
            $ilike:
              type: string
              title: $ilike
              description: Apply a case-insensitive `like` filter. Useful for strings only.
            $fulltext:
              type: string
              title: $fulltext
              description: Filter to apply on full-text properties.
            $overlap:
              type: array
              description: Filter arrays that have overlapping values with this parameter.
              items:
                type: string
                title: $overlap
                description: Filter arrays that have overlapping values with this parameter.
            $contains:
              type: array
              description: Filter arrays that contain some of the values of this parameter.
              items:
                type: string
                title: $contains
                description: Filter arrays that contain some of the values of this parameter.
            $contained:
              type: array
              description: Filter arrays that contain all values of this parameter.
              items:
                type: string
                title: $contained
                description: Filter arrays that contain all values of this parameter.
            $exists:
              type: boolean
              title: $exists
              description: Filter by whether a value for this parameter exists (not `null`).
          title: deleted_at
      - name: stock_location_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: stock_location_id
            description: Filter by a location ID to retrieve its associated shipping option.
          - type: array
            description: Filter by location IDs to retrieve their associated shipping option.
            items:
              type: string
              title: stock_location_id
              description: A stock location's ID.
      - name: is_return
        in: query
        description: Filter by whether the shipping option is used for returns.
        required: false
        schema:
          type: boolean
          title: is_return
          description: Filter by whether the shipping option is used for returns.
      - name: admin_only
        in: query
        description: Filter by whether the shipping option is used by admin users only.
        required: false
        schema:
          type: boolean
          title: admin_only
          description: Filter by whether the shipping option is used by admin users only.
      - name: with_deleted
        in: query
        description: Whether to include deleted records in the result.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: Whether to include deleted records in the result.
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.shippingOption.list()\n.then(({ shipping_options, count, limit, offset }) => {\n  console.log(shipping_options)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/shipping-options'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Shipping Options
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The paginated list of shipping options.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items returned.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before retrieving the returned items.
                    count:
                      type: number
                      title: count
                      description: The total number of items.
                - type: object
                  description: The paginated list of shipping options.
                  required:
                  - shipping_options
                  properties:
                    shipping_options:
                      type: array
                      description: The list of shipping options.
                      items:
                        type: object
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
    post:
      operationId: PostShippingOptions
      summary: Create Shipping Option
      description: Create a shipping option.
      x-authenticated: true
      parameters:
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/AdminCreateFlatRateShippingOption'
              - $ref: '#/components/schemas/AdminCreateCalculatedShippingOption'
              description: The shipping option's details.
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.shippingOption.create({\n  name: \"Standard Shipping\",\n  profile_id: \"shp_123\",\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option)\n})"
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/shipping-options' \\\n-H 'Authorization: Bearer {jwt_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"name\": \"Julie\",\n  \"service_zone_id\": \"{value}\",\n  \"shipping_profile_id\": \"{value}\",\n  \"price_type\": \"{value}\",\n  \"provider_id\": \"{value}\",\n  \"type\": {\n    \"label\": \"{value}\",\n    \"description\": \"{value}\",\n    \"code\": \"{value}\"\n  },\n  \"prices\": []\n}'"
      tags:
      - Shipping Options
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminShippingOptionResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-workflow: createShippingOptionsWorkflow
      x-events:
      - name: shipping-option.created
        payload: "```ts\n{\n  id, // The ID of the shipping option\n}\n```"
        description: Emitted when shipping options are created.
        deprecated: false
        since: 2.12.4
    servers:
    - url: http://localhost:9000
    - url: https://api.medusajs.com
  /admin/shipping-options/{id}:
    get:
      operationId: GetShippingOptionsId
      summary: Get a Shipping Option
      description: Retrieve a shipping option by its ID. You can expand the shipping option's relations or select the fields that should be returned.
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The shipping option's ID.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: 'Comma-separated fields that should be included in the returned data.

          if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields.

          without prefix it will replace the entire default fields.'
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. if a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.shippingOption.retrieve(\"so_123\")\n.then(({ shipping_option }) => {\n  console.log(shipping_option)\n})"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/shipping-options/{id}'' \

          -H ''Authorization: Bearer {jwt_token}'''
      tags:
      - Shipping Options
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminShippingOptionResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
    post:
      operationId: PostShippingOptionsId
      summary: Update a Shipping Option
      description: 'Update a shipping option''s details.


        When you provide the `prices` array, it replaces the shipping option''s existing flat-rate prices:


        - A price with a matching `id` is updated.

        - A price without an `id` is created

        - Any existing price whose `id` isn''t included in the array is deleted.


        The `rules` you provide for a price similarly replace that price''s existing rules, so omit a rule to remove it.


        Omitting the `prices` property entirely leaves the existing prices unchanged, whereas setting `price_type` to `calculated` removes all flat-rate prices.

        '
      x-authenticated: true
      parameters:
      - name: id
        in: path
        description: The shipping option's ID.
        required: true
        schema:
          type: string
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. Without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. Without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateShippingOption'
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nsdk.admin.shippingOption.update(\"so_123\", {\n  name: \"Standard Shipping\",\n})\n.then(({ shipping_option }) => {\n  console.log(shipping_option)\n})"
 

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/medusa/refs/heads/main/openapi/medusa-shipping-options-api-openapi.yml