> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update your shipping defaults

> Update the shipping defaults configured for your account.

Only the fields you send are changed; anything you omit keeps its current value. Send `null` for `ship_with` or `insurance` to remove that default.



## OpenAPI

````yaml /.openapi/v3/shipping-defaults/openapi.yaml patch /shipping-defaults
openapi: 3.1.0
info:
  title: Shipping Defaults [BETA]
  version: 3.0.0
  description: >-
    The Sendcloud Shipping Defaults API lets you manage the fallback values that
    are applied to your shipments. A shipping default is used whenever a
    shipment does not specify a value itself, so you can set a default weight,
    shipping method, insurance, customs options, and label options once instead
    of repeating them on every shipment.
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://panel.sendcloud.sc/api/v3
    description: Sendcloud Production
security: []
tags:
  - name: Shipping defaults
    description: Retrieve and update the default values that are applied to your shipments.
paths:
  /shipping-defaults:
    patch:
      tags:
        - Shipping defaults
      summary: Update your shipping defaults
      description: >-
        Update the shipping defaults configured for your account.


        Only the fields you send are changed; anything you omit keeps its
        current value. Send `null` for `ship_with` or `insurance` to remove that
        default.
      operationId: sc-public-v3-shipping-defaults-update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShippingDefaultsUpdate'
            examples:
              UpdateTheDefaultWeight:
                summary: Update the default weight
                value:
                  weight:
                    value: '1.500'
                    unit: kg
              InsureEveryShipmentInFull:
                summary: Insure every shipment in full
                value:
                  insurance:
                    type: percentage
                    properties:
                      percentage: 100
              RemoveTheDefaultShippingMethod:
                summary: Remove the default shipping method
                value:
                  ship_with: null
              ShowTheOrderReferenceOnLabels:
                summary: Show the order reference on labels
                value:
                  label_options:
                    label_notes:
                      - order_reference
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShippingDefaultsResponse'
              examples:
                UpdatedShippingDefaults:
                  summary: The updated shipping defaults
                  value:
                    data:
                      weight:
                        value: '1.500'
                        unit: kg
                      ship_with:
                        type: shipping_method_id
                        properties:
                          shipping_method_id: 8
                      insurance:
                        type: percentage
                        properties:
                          percentage: 100
                      customs_options:
                        export_reason: commercial_goods
                        use_order_number_as_invoice_number: false
                      label_options:
                        label_notes:
                          - order_reference
                        show_qr_code_letter: true
                        show_port_letter: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                IncompatibleShippingMethod:
                  summary: Shipping method is not compatible with the default weight
                  value:
                    errors:
                      - status: '400'
                        code: invalid
                        detail: >-
                          This shipping method is not compatible with your
                          default weight.
                        source:
                          pointer: /ship_with/properties/shipping_method_id
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  schemas:
    ShippingDefaultsUpdate:
      title: ShippingDefaultsUpdate
      type: object
      description: >-
        The shipping defaults to change. Every field is optional; anything you
        omit keeps its current value.
      additionalProperties: false
      properties:
        weight:
          $ref: '#/components/schemas/str-weight'
          description: >-
            The default weight of a parcel. Only `kg` is supported, with up to
            three decimal places.
        ship_with:
          description: >-
            The shipping method to apply by default. Send `null` to remove the
            default.
          oneOf:
            - $ref: '#/components/schemas/ShipWithShippingMethodId'
            - type: 'null'
        insurance:
          description: >-
            The insurance to apply by default. Send `null` to remove the
            default.
          oneOf:
            - $ref: '#/components/schemas/PercentageInsurance'
            - $ref: '#/components/schemas/FixedAmountInsurance'
            - type: 'null'
          discriminator:
            propertyName: type
            mapping:
              percentage:
                $ref: '#/components/schemas/PercentageInsurance'
              fixed_amount:
                $ref: '#/components/schemas/FixedAmountInsurance'
        customs_options:
          $ref: '#/components/schemas/CustomsOptionsUpdate'
        label_options:
          $ref: '#/components/schemas/LabelOptionsUpdate'
    ShippingDefaultsResponse:
      title: ShippingDefaultsResponse
      type: object
      description: The shipping defaults configured for your account.
      properties:
        data:
          $ref: '#/components/schemas/ShippingDefaults'
      required:
        - data
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
      required:
        - errors
    str-weight:
      title: Weight
      type: object
      description: Weight in the specified unit
      properties:
        value:
          type: string
          description: Weight value
          example: '14.5'
        unit:
          $ref: '#/components/schemas/weight-units'
      required:
        - value
        - unit
    ShipWithShippingMethodId:
      title: ShipWithShippingMethodId
      type: object
      description: A default shipping method, selected by its unique id.
      additionalProperties: false
      properties:
        type:
          type: string
          description: The way the default shipping method is selected.
          const: shipping_method_id
          example: shipping_method_id
        properties:
          type: object
          additionalProperties: false
          properties:
            shipping_method_id:
              type: integer
              format: int64
              description: >-
                The unique id of the shipping method. The carrier must be
                enabled for your account.
              exclusiveMinimum: 0
              example: 8
          required:
            - shipping_method_id
      required:
        - type
        - properties
    PercentageInsurance:
      title: PercentageInsurance
      type: object
      description: Insures a percentage of the parcel value.
      additionalProperties: false
      properties:
        type:
          type: string
          description: The way the default insurance is calculated.
          const: percentage
          example: percentage
        properties:
          type: object
          additionalProperties: false
          properties:
            percentage:
              type: integer
              description: The percentage of the parcel value to insure.
              minimum: 1
              maximum: 100
              example: 100
          required:
            - percentage
      required:
        - type
        - properties
    FixedAmountInsurance:
      title: FixedAmountInsurance
      type: object
      description: >-
        Insures a fixed amount, regardless of the parcel value. Deprecated: use
        `percentage` instead. Existing fixed amounts are still returned, but you
        can no longer set a new one.
      deprecated: true
      additionalProperties: false
      properties:
        type:
          type: string
          description: The way the default insurance is calculated.
          const: fixed_amount
          example: fixed_amount
        properties:
          type: object
          additionalProperties: false
          properties:
            value:
              type: integer
              description: >-
                The fixed insured value. Deprecated: use `type: percentage`
                instead.
              deprecated: true
              minimum: 1
              example: 500
          required:
            - value
      required:
        - type
        - properties
    CustomsOptionsUpdate:
      title: CustomsOptionsUpdate
      type: object
      description: The customs defaults to change. Every field is optional.
      additionalProperties: false
      properties:
        export_reason:
          description: >-
            The reason for exporting the goods. Send `null` to remove the
            default.
          oneOf:
            - $ref: '#/components/schemas/ExportReason'
            - type: 'null'
        use_order_number_as_invoice_number:
          type:
            - boolean
            - 'null'
          description: Whether the order number is used as the customs invoice number.
          example: false
    LabelOptionsUpdate:
      title: LabelOptionsUpdate
      type: object
      description: The label defaults to change. Every field is optional.
      additionalProperties: false
      properties:
        label_notes:
          type: array
          description: >-
            The extra information printed on the label. Send an empty array to
            print none.
          maxItems: 1
          items:
            $ref: '#/components/schemas/LabelNote'
        show_qr_code_letter:
          type: boolean
          description: Whether a QR code letter is included with the label.
          example: true
        show_port_letter:
          type: boolean
          description: Whether a post office letter is included with the label.
          example: false
    ShippingDefaults:
      title: ShippingDefaults
      type: object
      description: The default values that are applied to your shipments.
      properties:
        weight:
          $ref: '#/components/schemas/str-weight'
          description: The default weight of a parcel. Only `kg` is supported.
        ship_with:
          description: >-
            The shipping method applied by default, or `null` when no default is
            set.
          oneOf:
            - $ref: '#/components/schemas/ShipWithShippingMethodId'
            - type: 'null'
        insurance:
          description: The insurance applied by default, or `null` when no default is set.
          oneOf:
            - $ref: '#/components/schemas/PercentageInsurance'
            - $ref: '#/components/schemas/FixedAmountInsurance'
            - type: 'null'
          discriminator:
            propertyName: type
            mapping:
              percentage:
                $ref: '#/components/schemas/PercentageInsurance'
              fixed_amount:
                $ref: '#/components/schemas/FixedAmountInsurance'
        customs_options:
          $ref: '#/components/schemas/CustomsOptions'
        label_options:
          $ref: '#/components/schemas/LabelOptions'
      required:
        - weight
        - ship_with
        - insurance
        - customs_options
        - label_options
    ErrorObject:
      title: Error
      type: object
      description: Error in a JSON:API error format
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        links:
          type: object
          description: >-
            A set of hyperlinks that provide additional information about the
            error.
          properties:
            about:
              type: string
              description: A URL that provides additional information about the error.
        status:
          type: string
          format: int32
          description: The HTTP status code of the error.
          minLength: 1
        code:
          type: string
          description: A unique error code for the error, in snake case format.
          minLength: 1
          enum:
            - unknown_field
            - invalid
            - forbidden
            - invalid_choice
            - min_value
            - 'null'
            - not_found
            - required
            - not_a_list
            - non_field_errors
            - authentication_failed
            - validation_error
            - parcel_announcement_error
        title:
          type: string
          description: A short, human-readable summary of the error.
          minLength: 1
        detail:
          type: string
          description: A human-readable explanation of the error.
          minLength: 1
        source:
          type: object
          description: >-
            An object that identifies the source of the error within the request
            payload.
          properties:
            pointer:
              type: string
              description: >-
                A `JSON` pointer to the location of the error within the request
                payload.
            parameter:
              type: string
              description: The name of the `query` parameter that caused the error.
            header:
              type: string
              description: The name of the `header` parameter that caused the error.
        meta:
          type: object
          description: Additional metadata about the error.
    weight-units:
      type: string
      title: Mass Units Object
      enum:
        - kg
        - g
        - lbs
        - oz
      example: g
    ExportReason:
      title: ExportReason
      type: string
      description: The reason for exporting the goods.
      enum:
        - gift
        - documents
        - commercial_goods
        - commercial_sample
        - returned_goods
        - personal_use
      example: commercial_goods
    LabelNote:
      title: LabelNote
      type: string
      description: Extra information that can be printed on a label.
      enum:
        - order_reference
        - shop_note
        - skus
      example: order_reference
    CustomsOptions:
      title: CustomsOptions
      type: object
      description: The customs defaults applied to your international shipments.
      properties:
        export_reason:
          description: >-
            The reason for exporting the goods, or `null` when no default is
            set.
          oneOf:
            - $ref: '#/components/schemas/ExportReason'
            - type: 'null'
        use_order_number_as_invoice_number:
          type: boolean
          description: Whether the order number is used as the customs invoice number.
          example: false
      required:
        - export_reason
        - use_order_number_as_invoice_number
    LabelOptions:
      title: LabelOptions
      type: object
      description: The defaults applied to the labels you create.
      properties:
        label_notes:
          type: array
          description: The extra information printed on the label.
          items:
            $ref: '#/components/schemas/LabelNote'
        show_qr_code_letter:
          type: boolean
          description: Whether a QR code letter is included with the label.
          example: true
        show_port_letter:
          type: boolean
          description: Whether a post office letter is included with the label.
          example: false
      required:
        - label_notes
        - show_qr_code_letter
        - show_port_letter
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: >-
        Basic Authentication using API key and secrets is currently the main
        authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: >-
        OAuth2 is a standardized protocol for authorization that allows users to
        share their private resources stored on one site with another site
        without having to provide their credentials. OAuth2 Client Credentials
        Grant workflow. This workflow is typically used for server-to-server
        interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.

````