> ## 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 a contract

> Update or replace a contract by including the `id` of the contract as a path parameter.

This endpoint will either **update** or **replace** a contract. Changes to unused contracts or the contract's state
and description will be done in place and not cause a new contract to be created (`name`, `is_active`, `is_default`, `is_per_carrier_default`).

**However, used contracts are immutable, if you change the contract\_data of a contract that has already been used for shipments,
it will cause a new contract ID to be created. In this case, the old one will no longer be active for use.**

After updating a contract with `contract_data`, we need to validate it again and its state will be `"validating"`.
During the validation the contract is not active and cannot be used for creating shipments. The validation
process is asynchronous and will happen in the background.

Once validation is complete, the contract's state will change to one of the following:

* `"active"` or `"inactive"`: The contract has been successfully processed.
* `"validation_failed"`: An error occurred during validation. Additional information about the failure will be provided.


## OpenAPI

````yaml /.openapi/v3/contracts/openapi.yaml patch /contracts/{id}
openapi: 3.1.0
info:
  title: Contracts API
  version: 3.0.0
  description: >-
    The Contracts API allows you to manage and retrieve information about your
    direct shipping contracts connected to your Sendcloud account.
  contact:
    name: Sendcloud API Support
    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: Contracts
paths:
  /contracts/{id}:
    parameters:
      - schema:
          type: integer
        in: path
        name: id
        description: The id of the contract.
        required: true
    patch:
      tags:
        - Contracts
      summary: Update a contract
      description: >-
        Update or replace a contract by including the `id` of the contract as a
        path parameter.
      operationId: sc-public-v3-scp-patch-contract
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/update-contract-request'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: Update contract
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/contract'
              examples:
                UpdatedContract:
                  summary: Updated contract
                  value:
                    data:
                      id: 60
                      carrier:
                        code: lettresuivie
                        name: Lettre Suivie
                      client_id: sendcloud-1
                      is_default_per_carrier: true
                      state: active
                      type: direct
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
              examples:
                Failed:
                  summary: Failed to update contract
                  value:
                    errors:
                      - detail: This field is required.
                        status: '400'
                        source:
                          pointer: /data/client_id
                        code: required
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors'
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
components:
  schemas:
    update-contract-request:
      title: Update Contract request Object
      description: Update request object model
      type: object
      allOf:
        - $ref: '#/components/schemas/base-contract-request'
        - type: object
          properties:
            is_default_per_carrier:
              type: boolean
              description: >-
                Marks the contract as default for a carrier. You can have only
                one default direct contract per carrier.


                **Note: You cannot mark a contract as not default, to switch the
                default contract of a carrier 

                use is_default_per_carrier: true on the contract you like to set
                as active, 

                other contracts for this carrier will automatically be marked as
                not default.**
            name:
              type: string
              description: The name of the contract
              maxLength: 50
              example: main
    contract:
      title: Contract
      description: User contract
      type: object
      properties:
        id:
          type: integer
          format: int64
          minimum: 1
          description: Unique identifier of the contract.
        client_id:
          description: >-
            Value of the carrier specific key for contact (e.g. the value of
            DelisID in DPD Benelux, username for DHL Express).
          type:
            - string
            - 'null'
        carrier:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
              minLength: 1
              description: Carrier name.
        name:
          type: string
          description: >-
            A custom name set by the user used to identify this contract
            throughout the platform.
          maxLength: 50
        country_code:
          type: string
          description: The country of the contract, as an ISO 3166-1 alpha-2.
          example: NL
        is_default_per_carrier:
          type: boolean
          description: >-
            Indicates if the contract is marked as 

            default. When you have multiple active direct contracts for the same
            carrier, default indicates that the contract will be prioritized
            over the other direct contracts for the same carrier, when no
            contract is explicitly 
             mentioned while creating a parcel. You can have only one default direct contract per carrier and it will always be False for the broker and subbroker. The default can be configured in the "My contracts" page in the Sendcloud platform.
        state:
          type: string
          description: State of the contract
          enum:
            - active
            - inactive
            - validating
            - validation_failed
          example: active
        type:
          type: string
          description: Contract type
          enum:
            - direct
            - broker
            - subbroker
          example: direct
        error:
          type:
            - string
            - 'null'
          description: An error message when validating contract
          example: Missing or invalid shipper number
    errors:
      title: Errors
      type: object
      description: A standardized format for errors in JSON:API responses.
      properties:
        errors:
          type:
            - array
            - object
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/ErrorObject'
            required:
              - status
              - code
              - detail
    base-contract-request:
      title: Base Contract request Object
      type: object
      properties:
        is_active:
          type: boolean
          description: >-
            New contracts are inactive by default, if you want to activate it
            immediately set this flag.
          example: false
        is_default_per_carrier:
          type: boolean
          description: >-
            Marks the contract as default for a carrier. You can have only one
            default direct contract per carrier.
          default: false
          example: false
        contract_data:
          type: object
          description: >-
            Fields for creating a contract. It supports dynamic key-value pairs,
            where keys represent field names and values are string-based data.
          additionalProperties:
            type: string
          example:
            country: NL
            client_id: sendcloud-1
    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.
  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.

````