Etsy Shop ShippingProfile API

openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy Shop ShippingProfile API
  description: <div class="wt-text-body-01"><p class="wt-pt-xs-2 wt-pb-xs-2">Etsy's Open API provides a simple RESTful interface for various Etsy.com features.</p><p class="wt-pb-xs-2">If you'd like to report an issue or provide feedback on the API design, <a target="_blank" class="wt-text-link wt-p-xs-0" href="https://github.com/etsy/open-api/discussions">please add an issue in Github</a>.</p></div>&copy; 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's <a class='wt-text-link wt-p-xs-0' target='_blank' href='https://www.etsy.com/legal/api'>API Developer Terms of Use</a>.
  termsOfService: https://www.etsy.com/legal/api
  contact:
    email: developers@etsy.com
  version: 3.0.0
  x-generated-from: https://www.etsy.com/openapi/generated/oas/3.0.0.json
  x-last-validated: '2026-05-30'
servers:
- url: https://openapi.etsy.com
  description: Etsy Open API v3 base URL (per Etsy developer documentation; live calls also resolve at https://api.etsy.com/v3/application).
security:
- api_key: []
tags:
- name: Shop ShippingProfile
paths:
  /v3/application/shipping-carriers:
    get:
      operationId: getShippingCarriers
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a list of available shipping carriers and the mail classes associated with them for a given country'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: origin_country_iso
        in: query
        description: The ISO code of the country from which the listing ships.
        required: true
        schema:
          type: string
          description: The ISO code of the country from which the listing ships.
          format: ISO 3166-1 alpha-2
        example: US
      responses:
        '200':
          description: A set of ShippingCarriers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingCarriers'
              examples:
                GetShippingCarriers200Example:
                  summary: Default getShippingCarriers 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - shipping_carrier_id: 1
                      name: Handmade Ceramic Mug
                      domestic_classes:
                      - {}
                      international_classes:
                      - {}
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShippingCarriers400Example:
                  summary: Default getShippingCarriers 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShippingCarriers500Example:
                  summary: Default getShippingCarriers 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shipping Carriers
  /v3/application/shops/{shop_id}/shipping-profiles:
    post:
      operationId: createShopShippingProfile
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Creates a new ShippingProfile. You can pass a country iso code or a region when creating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - title
              - origin_country_iso
              - primary_cost
              - secondary_cost
              properties:
                title:
                  type: string
                  description: The name string of this shipping profile.
                origin_country_iso:
                  type: string
                  description: The ISO code of the country from which the listing ships.
                  format: ISO 3166-1 alpha-2
                primary_cost:
                  type: number
                  description: The cost of shipping to this country/region alone, measured in the store's default currency.
                  format: float
                  minimum: 0
                secondary_cost:
                  type: number
                  description: The cost of shipping to this country/region with another item, measured in the store's default currency.
                  format: float
                  minimum: 0
                min_processing_time:
                  type: integer
                  description: The minimum time required to process to ship listings with this shipping profile.
                  minimum: 1
                  maximum: 10
                max_processing_time:
                  type: integer
                  description: The maximum processing time the listing needs to ship.
                  minimum: 1
                  maximum: 10
                processing_time_unit:
                  type: string
                  description: The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to "business_days".
                  enum:
                  - business_days
                  - weeks
                  default: business_days
                destination_country_iso:
                  type: string
                  description: The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.
                  format: ISO 3166-1 alpha-2
                  default: null
                destination_region:
                  type: string
                  description: The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If `none`, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.
                  enum:
                  - eu
                  - non_eu
                  - none
                  default: none
                origin_postal_code:
                  type: string
                  description: The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info
                  default: ''
                shipping_carrier_id:
                  type: integer
                  description: The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with `mail_class`** if `min_delivery_days` and `max_delivery_days` are null.
                  minimum: 0
                  default: 0
                mail_class:
                  type: string
                  description: The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with `shipping_carrier_id`** if `min_delivery_days` and `max_delivery_days` are null.
                  default: null
                min_delivery_days:
                  type: integer
                  description: The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `max_delivery_days`** if `mail_class` is null.
                  minimum: 1
                  maximum: 45
                  default: null
                max_delivery_days:
                  type: integer
                  description: The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with `min_delivery_days`** if `mail_class` is null.
                  minimum: 1
                  maximum: 45
                  default: null
            examples:
              CreateShopShippingProfileRequestExample:
                summary: Default createShopShippingProfile request
                x-microcks-default: true
                value:
                  title: example string
                  origin_country_iso: example string
                  primary_cost: 1.0
                  secondary_cost: 1.0
                  min_processing_time: 1
                  max_processing_time: 1
                  processing_time_unit: business_days
                  destination_country_iso: example string
                  destination_region: eu
                  origin_postal_code: example string
                  shipping_carrier_id: 1
                  mail_class: example string
                  min_delivery_days: 1
                  max_delivery_days: 1
      responses:
        '200':
          description: A single ShippingProfile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopShippingProfile'
              examples:
                CreateShopShippingProfile200Example:
                  summary: Default createShopShippingProfile 200 response
                  x-microcks-default: true
                  value:
                    shipping_profile_id: 1
                    title: Handmade Ceramic Mug — Stoneware
                    user_id: 456789
                    origin_country_iso: US
                    is_deleted: true
                    shipping_profile_destinations:
                    - null
                    shipping_profile_upgrades:
                    - null
                    origin_postal_code: '11201'
                    profile_type: manual
                    domestic_handling_fee: 1.0
                    international_handling_fee: 1.0
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                CreateShopShippingProfile403Example:
                  summary: Default createShopShippingProfile 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                CreateShopShippingProfile400Example:
                  summary: Default createShopShippingProfile 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                CreateShopShippingProfile401Example:
                  summary: Default createShopShippingProfile 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                CreateShopShippingProfile500Example:
                  summary: Default createShopShippingProfile 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Create Shop Shipping Profile
    get:
      operationId: getShopShippingProfiles
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      responses:
        '200':
          description: A list of shipping profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopShippingProfiles'
              examples:
                GetShopShippingProfiles200Example:
                  summary: Default getShopShippingProfiles 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - shipping_profile_id: 1
                      title: Handmade Ceramic Mug — Stoneware
                      user_id: 456789
                      origin_country_iso: US
                      is_deleted: true
                      shipping_profile_destinations:
                      - {}
                      shipping_profile_upgrades:
                      - {}
                      origin_postal_code: '11201'
                      profile_type: manual
                      domestic_handling_fee: 1.0
                      international_handling_fee: 1.0
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfiles403Example:
                  summary: Default getShopShippingProfiles 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfiles400Example:
                  summary: Default getShopShippingProfiles 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfiles500Example:
                  summary: Default getShopShippingProfiles 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shop Shipping Profiles
  /v3/application/shops/{shop_id}/shipping-profiles/{shipping_profile_id}:
    delete:
      operationId: deleteShopShippingProfile
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Deletes a ShippingProfile by given id.'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: shipping_profile_id
        in: path
        description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
        required: true
        schema:
          type: integer
          description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
          format: int64
          minimum: 1
        example: 1
      responses:
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteShopShippingProfile403Example:
                  summary: Default deleteShopShippingProfile 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteShopShippingProfile404Example:
                  summary: Default deleteShopShippingProfile 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '204':
          description: The ShopShippingProfile resource was correctly deleted
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteShopShippingProfile400Example:
                  summary: Default deleteShopShippingProfile 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteShopShippingProfile401Example:
                  summary: Default deleteShopShippingProfile 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteShopShippingProfile500Example:
                  summary: Default deleteShopShippingProfile 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Delete Shop Shipping Profile
    get:
      operationId: getShopShippingProfile
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a Shipping Profile referenced by shipping profile ID.'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: shipping_profile_id
        in: path
        description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
        required: true
        schema:
          type: integer
          description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
          format: int64
          minimum: 1
        example: 1
      responses:
        '200':
          description: A single ShippingProfile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopShippingProfile'
              examples:
                GetShopShippingProfile200Example:
                  summary: Default getShopShippingProfile 200 response
                  x-microcks-default: true
                  value:
                    shipping_profile_id: 1
                    title: Handmade Ceramic Mug — Stoneware
                    user_id: 456789
                    origin_country_iso: US
                    is_deleted: true
                    shipping_profile_destinations:
                    - null
                    shipping_profile_upgrades:
                    - null
                    origin_postal_code: '11201'
                    profile_type: manual
                    domestic_handling_fee: 1.0
                    international_handling_fee: 1.0
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfile403Example:
                  summary: Default getShopShippingProfile 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfile404Example:
                  summary: Default getShopShippingProfile 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfile400Example:
                  summary: Default getShopShippingProfile 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfile401Example:
                  summary: Default getShopShippingProfile 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopShippingProfile500Example:
                  summary: Default getShopShippingProfile 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shop Shipping Profile
    put:
      operationId: updateShopShippingProfile
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Changes the settings in a shipping profile. You can pass a country iso code or a region when updating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.'
      tags:
      - Shop ShippingProfile
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: shipping_profile_id
        in: path
        description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
        required: true
        schema:
          type: integer
          description: The numeric ID of the [shipping profile](/documentation/reference#operation/getShopShippingProfile) associated with the listing. Required when listing type is `physical`.
          format: int64
          minimum: 1
        example: 1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: The name string of this shipping profile.
                origin_country_iso:
                  type: string
                  description: The ISO code of the country from which the listing ships.
                  format: ISO 3166-1 alpha-2
                min_processing_time:
                  type: integer
                  description: The minimum time required to process to ship listings with this shipping profile.
                  minimum: 1
                  maximum: 10
                max_processing_time:
                  type: integer
                  description: The maximum processing time the listing needs to ship.
                  minimum: 1
                  maximum: 10
                processing_time_unit:
                  type: string
                  description: The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to "business_days".
                  enum:
                  - business_days
                  - weeks
                  default: business_days
                origin_postal_code:
                  type: string
                  description: The postal code string (not necessarily a number) for the location from which the listing ships. Required if the `origin_country_iso` supports postal codes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#countries-requiring-postal-codes) for more info
                  default: null
            examples:
              UpdateShopShippingProfileRequestExample:
                summary: Default updateShopShippingProfile request
                x-microcks-default: true
                value:
                  title: example string
                  origin_country_iso: example string
                  min_processing_time: 1
                  max_processing_time: 1
                  processing_time_unit: business_days
                  origin_postal_code: example string
      responses:
        '200':
          description: The updated shipping profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopShippingProfile'
              examples:
                UpdateShopShippingProfile200Example:
                  summary: Default updateShopShippingProfile 200 response
                  x-microcks-default: true
                  value:
                    shipping_profile_id: 1
                    title: Handmade Ceramic Mug — Stoneware
                    user_id: 456789
                    origin_country_iso: US
                    is_deleted: true
                    shipping_profile_destinations:
                    - null
                    shipping_profile_upgrades:
                    - null
                    origin_postal_code: '11201'
                    profile_type: manual
                    domestic_handling_fee: 1.0
      

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shop-shippingprofile-api-openapi.yml