openapi: 3.1.0
info:
  title: Contracts
  version: 2.0.0
  description: |
    The Contracts API allows you to manage and retrieve information about your direct shipping contracts
    connected to your Sendcloud account. With this API, you can list your contracts or fetch details about a specific
    contract.
  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/v2
    description: Sendcloud Production
tags:
  - name: Contracts
paths:
  /contracts:
    get:
      summary: Retrieve a list of contracts
      tags:
        - Contracts
      x-sendcloud-paginated: true
      x-sendcloud-paginated-discriminator: contracts
      x-mint:
        href: /api/v2/contracts/retrieve-a-list-of-contracts
        content: |-
          <Info>
            OAuth2 scopes required: `write:carrier`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  next:
                    type: string
                    nullable: true
                    description: Url to retrieve the next page of contracts.
                  previous:
                    type: string
                    nullable: true
                    description: Url to retrieve the previous page of contracts.
                  contracts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
                required:
                  - contracts
              examples:
                RetrieveContracts:
                  summary: Retrieve a list of contracts
                  value:
                    next: null
                    previous: null
                    contracts:
                      - id: 60
                        carrier:
                          code: lettresuivie
                          name: Lettre Suivie
                        client_id: sendcloud-1
                        is_active: true
                        country: FR
                        is_default: true
                      - id: 61
                        carrier:
                          code: poste_italiane
                          name: Poste Italiane
                        client_id: sendcloud-1
                        is_active: true
                        country: IT
                        is_default: true
      operationId: sc-public-v2-scp-get-all_contracts
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds:
            - write:carrier
      description: |-
        Retrieves information about all of the available contracts you have in your Sendcloud
        account. It will also return the `contract_id` of your contracts, which you can use to retrieve information
        about a specific contract.
      parameters:
        - schema:
            type: string
          in: query
          name: carrier
          description: 'The carrier you want to filter for, for instance: postnl. You can find available carriers in your Sendcloud account settings.'
          required: false
        - schema:
            type: boolean
          in: query
          name: is_active
          description: Filter contracts based on the status.
        - schema:
            type: string
          in: query
          name: client_id
          description: Filter direct contracts based on the client id.
        - schema:
            type: string
          in: query
          name: name
          description: Filter direct contracts based on the contract's name.
        - schema:
            type: string
          in: query
          name: country
          description: Filter contracts based on the country of the contract, it should be in the ISO 3166-1 alpha-2 format.
          example: NL
  /contracts/{id}:
    get:
      summary: Retrieve a contract
      tags:
        - Contracts
      x-mint:
        href: /api/v2/contracts/retrieve-a-contract
        content: |-
          <Info>
            OAuth2 scopes required: `write:carrier`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
              examples:
                RetrieveContract:
                  summary: Retrieve a contract
                  value:
                    id: 60
                    carrier:
                      code: lettresuivie
                      name: Lettre Suivie
                    client_id: sendcloud-1
                    is_active: true
                    is_default: true
        '404':
          description: Contract not found
      operationId: sc-public-v2-scp-get-specific_contract
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds:
            - write:carrier
      description: Retrieve information about a specific direct contract by passing its `id` as a path parameter.
      parameters:
        - schema:
            type: integer
          in: path
          name: id
          description: The id of the contract you want to retrieve.
          required: true
        - schema:
            type: string
          in: query
          name: carrier
          description: 'The carrier you want to filter for, for instance: postnl. You can find available carriers in your Sendcloud account settings.'
          required: false
        - schema:
            type: boolean
          in: query
          name: is_active
          description: Filter contracts based on the status.
        - schema:
            type: string
          in: query
          name: client_id
          description: Filter direct contracts based on the client id.
        - schema:
            type: string
          in: query
          name: name
          description: Filter direct contracts based on the contract's name.
components:
  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:
            read:analytics: View your shipping analytics
            read:audit-log: View your account's audit log
            read:brand: View your brands
            write:brand: Manage your brands
            write:carrier: Configure carriers and contracts
            read:checkout: View your dynamic checkout configurations and templates
            read:event-subscription: View your event subscriptions
            write:event-subscription: Create and manage your event subscriptions
            read:integration: View your integrations
            write:integration: Connect and manage integrations
            read:invoice: View your invoices
            read:notification: View your notifications
            write:notification: Manage your notifications
            read:operational-settings: View your warehouses, shipping lanes, and other operational settings
            write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
            read:order: View your orders
            write:order: Import and process your orders
            read:organization: View organization settings
            write:organization: Change organization settings
            read:parcel: View your shipments and their tracking status
            write:parcel: Create, announce, and cancel shipments
            read:pickup: View carrier pickups and the options available for scheduling them
            write:pickup: Schedule and manage carrier pickups
            read:price: View shipping prices
            write:product: Manage your product catalog
            read:return: View your returns
            write:return: Create and manage returns
            read:return-settings: View your return settings
            write:return-settings: Configure your return settings
            read:service-point: View carrier service points
            read:shipping-method: View shipping methods, products and prices
            read:shipping-rule: View your shipping rules
            write:shipping-rule: Create and manage shipping rules
            read:support-ticket: View your support tickets
            write:support-ticket: Manage your support tickets
            read:tracking-message: View your tracking notifications
            write:tracking-message: Manage your tracking notifications
            read:tracking-page: View your tracking page
            write:tracking-page: Customize your tracking page
            read:user: Read your basic account information
  schemas:
    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: Client ID of a contract
          type: string
          nullable: true
        is_active:
          type: boolean
          description: Contract's status
        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:
          type: string
          description: The country of the contract, as an ISO 3166-1 alpha-2.
          example: NL
        is_default:
          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.