Commerce Layer shipping_methods API

openapi: 3.1.0
info:
  title: Commerce Layer addresses shipping_methods API
  version: 7.10.1
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
  description: API
- url: https://core.commercelayer.io/users/sign_in
  description: Sign in
- url: https://docs.commercelayer.io/api
  description: API reference
security:
- bearerAuth: []
tags:
- name: shipping_methods
  description: resource type
paths:
  /delivery_lead_times/{deliveryLeadTimeId}/shipping_method:
    get:
      operationId: GET/deliveryLeadTimeId/shipping_method
      summary: Retrieve the shipping method associated to the delivery lead time
      description: Retrieve the shipping method associated to the delivery lead time
      tags:
      - shipping_methods
      parameters:
      - name: deliveryLeadTimeId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The shipping_method associated to the delivery lead time
  /markets/{marketId}/default_shipping_method:
    get:
      operationId: GET/marketId/default_shipping_method
      summary: Retrieve the default shipping method associated to the market
      description: Retrieve the default shipping method associated to the market
      tags:
      - shipping_methods
      parameters:
      - name: marketId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The default_shipping_method associated to the market
  /orders/{orderId}/default_shipping_method:
    get:
      operationId: GET/orderId/default_shipping_method
      summary: Retrieve the default shipping method associated to the order
      description: Retrieve the default shipping method associated to the order
      tags:
      - shipping_methods
      parameters:
      - name: orderId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The default_shipping_method associated to the order
  /shipments/{shipmentId}/shipping_method:
    get:
      operationId: GET/shipmentId/shipping_method
      summary: Retrieve the shipping method associated to the shipment
      description: Retrieve the shipping method associated to the shipment
      tags:
      - shipping_methods
      parameters:
      - name: shipmentId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The shipping_method associated to the shipment
  /shipments/{shipmentId}/available_shipping_methods:
    get:
      operationId: GET/shipmentId/available_shipping_methods
      summary: Retrieve the available shipping methods associated to the shipment
      description: Retrieve the available shipping methods associated to the shipment
      tags:
      - shipping_methods
      parameters:
      - name: shipmentId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The available_shipping_methods associated to the shipment
  /shipping_method_tiers/{shippingMethodTierId}/shipping_method:
    get:
      operationId: GET/shippingMethodTierId/shipping_method
      summary: Retrieve the shipping method associated to the shipping method tier
      description: Retrieve the shipping method associated to the shipping method tier
      tags:
      - shipping_methods
      parameters:
      - name: shippingMethodTierId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The shipping_method associated to the shipping method tier
  /shipping_methods:
    get:
      operationId: GET/shipping_methods
      summary: List all shipping methods
      description: List all shipping methods
      tags:
      - shipping_methods
      responses:
        '200':
          description: A list of shipping method objects
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/shippingMethodResponseList'
    post:
      operationId: POST/shipping_methods
      summary: Create a shipping method
      description: Create a shipping method
      tags:
      - shipping_methods
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/shippingMethodCreate'
      responses:
        '201':
          description: The created shipping method object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/shippingMethodResponse'
  /shipping_methods/{shippingMethodId}:
    get:
      operationId: GET/shipping_methods/shippingMethodId
      summary: Retrieve a shipping method
      description: Retrieve a shipping method
      tags:
      - shipping_methods
      parameters:
      - name: shippingMethodId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The shipping method object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/shippingMethodResponse'
    patch:
      operationId: PATCH/shipping_methods/shippingMethodId
      summary: Update a shipping method
      description: Update a shipping method
      tags:
      - shipping_methods
      parameters:
      - name: shippingMethodId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/shippingMethodUpdate'
      responses:
        '200':
          description: The updated shipping method object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/shippingMethodResponse'
    delete:
      operationId: DELETE/shipping_methods/shippingMethodId
      summary: Delete a shipping method
      description: Delete a shipping method
      tags:
      - shipping_methods
      parameters:
      - name: shippingMethodId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '204':
          description: No content
  /shipping_weight_tiers/{shippingWeightTierId}/shipping_method:
    get:
      operationId: GET/shippingWeightTierId/shipping_method
      summary: Retrieve the shipping method associated to the shipping weight tier
      description: Retrieve the shipping method associated to the shipping weight tier
      tags:
      - shipping_methods
      parameters:
      - name: shippingWeightTierId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The shipping_method associated to the shipping weight tier
components:
  schemas:
    shippingMethodResponseList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/shippingMethodResponse/properties/data'
    shippingMethodResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            type:
              type: string
              description: The resource's type
              enum:
              - shipping_methods
            links:
              type: object
              properties:
                self:
                  type: string
                  description: URL
            attributes:
              $ref: '#/components/schemas/shippingMethod/properties/data/properties/attributes'
            relationships:
              type: object
              properties:
                market:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - market
                        id:
                          type: string
                          description: The resource ID
                shipping_zone:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_zone
                        id:
                          type: string
                          description: The resource ID
                shipping_category:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_category
                        id:
                          type: string
                          description: The resource ID
                stock_location:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - stock_location
                        id:
                          type: string
                          description: The resource ID
                delivery_lead_time_for_shipment:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - delivery_lead_time_for_shipment
                        id:
                          type: string
                          description: The resource ID
                shipping_method_tiers:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_method_tiers
                        id:
                          type: string
                          description: The resource ID
                shipping_weight_tiers:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_weight_tiers
                        id:
                          type: string
                          description: The resource ID
                attachments:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - attachments
                        id:
                          type: string
                          description: The resource ID
                notifications:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - notifications
                        id:
                          type: string
                          description: The resource ID
                events:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - events
                        id:
                          type: string
                          description: The resource ID
                tags:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tags
                        id:
                          type: string
                          description: The resource ID
                event_stores:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: The resource ID
    shippingMethodCreate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - shipping_methods
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The shipping method's name.
                  example: Standard shipping
                scheme:
                  type: string
                  description: The shipping method's scheme. One of 'flat', 'weight_tiered', or 'external'.
                  example: flat
                  enum:
                  - flat
                  - weight_tiered
                  - external
                currency_code:
                  type: string
                  description: The international 3-letter currency code as defined by the ISO 4217 standard.
                  example: EUR
                external_prices_url:
                  type: string
                  description: The URL used to overwrite prices by an external source.
                  example: https://external_prices.yourbrand.com
                price_amount_cents:
                  type: integer
                  description: The price of this shipping method, in cents.
                  example: 1000
                free_over_amount_cents:
                  type: integer
                  description: Apply free shipping if the order amount is over this value, in cents.
                  example: 9900
                use_subtotal:
                  type: boolean
                  description: Send this attribute if you want to compare the free over amount with order's subtotal (excluding discounts, if any).
                  example: true
                min_weight:
                  type: number
                  description: The minimum weight for which this shipping method is available.
                  example: 3.0
                max_weight:
                  type: number
                  description: The maximum weight for which this shipping method is available.
                  example: 300.0
                unit_of_weight:
                  type: string
                  description: The unit of weight. One of 'gr', 'oz', or 'lb'.
                  example: gr
                  enum:
                  - gr
                  - oz
                  - lb
                tax_code:
                  type: string
                  description: The freight tax identifier code, specific for a particular tax calculator.
                  example: FR010000
                _disable:
                  type: boolean
                  description: Send this attribute if you want to mark this resource as disabled.
                  example: true
                _enable:
                  type: boolean
                  description: Send this attribute if you want to mark this resource as enabled.
                  example: true
                external_includes:
                  type: array
                  description: List of related resources that will be included in the request to the external callback. Please do consult the documentation to check on which resource the includes are related (i.e. the order) and the defaults in case no list is provided.
                  example:
                  - order.line_item_options
                  items:
                    type: string
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
              required:
              - name
              - price_amount_cents
            relationships:
              type: object
              properties:
                market:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - markets
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                shipping_zone:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_zones
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                shipping_category:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_categories
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                stock_location:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - stock_locations
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                shipping_method_tiers:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - shipping_method_tiers
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                tags:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tags
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    shippingMethodUpdate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - shipping_methods
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The shipping method's name.
                  example: Standard shipping
                  nullable: false
                scheme:
                  type: string
                  description: The shipping method's scheme. One of 'flat', 'weight_tiered', or 'external'.
                  example: flat
                  nullable: true
                  enum:
                  - flat
                  - weight_tiered
                  - external
                currency_code:
                  type: string
                  description: The international 3-letter currency code as defined by the ISO 4217 standard.
                  example: EUR
                  nullable: true
                external_prices_url:
                  type: string
                  description: The URL used to overwrite prices by an external source.
                  example: https://external_prices.yourbrand.com
                  nullable: true
                price_amount_cents:
                  type: integer
                  description: The price of this shipping method, in cents.
                  example: 1000
                  nullable: false
                free_over_amount_cents:
                  type: integer
                  description: Apply free shipping if the order amount is over this value, in cents.
                  example: 9900
                  nullable: true
                use_subtotal:
                  type: boolean
                  description: Send this attribute if you want to compare the free over amount with order's subtotal (excluding discounts, if any).
                  example: true
                  nullable: false
                min_weight:
                  type: number
                  description: The minimum weight for which this shipping method is available.
                  example: 3.0
                  nullable: true
                max_weight:
                  type: number
                  description: The maximum weight for which this shipping method is available.
                  example: 300.0
                  nullable: true
                unit_of_weight:
                  type: string
                  description: The unit of weight. One of 'gr', 'oz', or 'lb'.
                  example: gr
                  nullable: true
                  enum:
                  - gr
                  - oz
                  - lb
                tax_code:
                  type: string
                  description: The freight tax identifier code, specific for a particular tax calculator.
                  example: FR010000
                  nullable: true
                _disable:
                  type: boolean
                  description: Send this attribute if you want to mark this resource as disabled.
                  example: true
                  nullable: false
                _enable:
                  type: boolean
                  description: Send this attribute if you want to mark this resource as enabled.
                  example: true
                  nullable: false
                _reset_circuit:
                  type: boolean
                  description: Send this attribute if you want to reset the circuit breaker associated to this resource to 'closed' state and zero failures count. Cannot be passed by sales channels.
                  example: true
                  nullable: false
                external_includes:
                  type: array
                  description: List of related resources that will be included in the request to the external callback. Please do consult the documentation to check on which resource the includes are related (i.e. the order) and the defaults in case no list is provided.
                  example:
                  - order.line_item_options
                  nullable: true
                  items:
                    type: string
                _add_tags:
                  type: string
                  description: Comma separated list of tags to be added. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.
                _remove_tags:
                  type: string
                  description: Comma separated list of tags to be removed. Duplicates, invalid and non existing ones are discarded. Cannot be passed by sales channels.
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
      

# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-shipping-methods-api-openapi.yml