openapi: 3.0.1
info:
  title: Carriyo Shipping Setup API
  version: '1.0'
  description: |-
    The Carriyo Shipping Setup API manages the configuration the shipping engine reads on every booking: carrier accounts, shipping rules, service levels, carrier networks, and costing profiles. These resources are set up once per merchant and updated infrequently.
  contact:
    name: Carriyo Support
    url: https://help.carriyo.com
    email: support@carriyo.com
servers:
  - url: https://api.carriyo.com
    description: Production Server
  - url: https://demo-api.carriyo.com
    description: Demo Server
security:
  - OAuth2-Production: []
    ApiKey: []
    TenantId: []
  - OAuth2-Demo: []
    ApiKey: []
    TenantId: []
tags:
  - name: carrier-accounts
    description: |-
      A carrier account in Carriyo holds the settings for a given account with your chosen carrier. The information in the carrier account varies by carrier and usually includes details such as the account number, the API credentials (API key, username, password), and the chosen service type.

      If you're a business that uses multiple carriers for shipping, you'll have multiple carrier accounts. For instance, if you have an account with DHL and UPS, you'll create two carrier accounts in Carriyo (one for each carrier) with the mandatory settings needed to book and track your shipments. You can also configure multiple carrier accounts in Carriyo for the same carrier when you hold multiple accounts with them across service types or countries.
  - name: shipping-rules
    description: |-
      Carriyo lets merchants automate carrier selection using shipping rules. Rules are grouped into rule sets, which can be assigned to merchant / country combinations. For example, a merchant can define one set of rules for the United States and a different set for Canada.

      Each rule has a set of conditions that assign an inbound shipment to a chosen carrier when the conditions match. Rules have a sequence (priority), and the first rule to match the shipment determines the carrier. Conditions are flexible: you can match on the pickup or dropoff location, the delivery type, parcel weight, dimensions, or any other attribute of the shipment, and you can also cap the number of shipments routed to a carrier.
  - name: service-levels
    description: |-
      A service level in Carriyo lets merchants define the expected timeline for a shipment. Service levels can be applied to each stage of the shipment journey: processing (preparing the shipment in the warehouse or store), collection (the carrier collecting the shipment), and delivery (the carrier delivering it once collected). You can also set up the customer promise: the end-to-end timeline from the moment the customer places the order.

      Service levels work like shipping rules: they have a priority sequence and conditions, so you can define different expected timelines for different types of shipments.
  - name: carrier-networks
    description: |-
      Carrier networks group carriers for routing decisions across geographic regions.
    x-internal: true
  - name: carrier-costing
    description: |-
      Costing profiles and rules define cost structures for carriers based on shipment characteristics.
    x-internal: true
  - name: carrier-capacity
    description: |-
      Capacity profiles define shipment-volume thresholds and constraints per carrier across regions and time windows.
    x-internal: true
  - name: document-settings
    description: |-
      Document settings configure templates and formats for shipment documents (labels, manifests, proofs of delivery).
    x-internal: true
paths:
  /carrier-accounts:
    parameters: []
    post:
      tags:
        - carrier-accounts
      summary: Create carrier account
      operationId: create-carrier-account
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/carrier-account-request'
        required: false
      responses:
        '200':
          description: 'Carrier account created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-account-object'
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a new carrier account for the merchant. The account holds the credentials and
        configuration Carriyo uses to book shipments with that carrier.
    get:
      tags:
        - carrier-accounts
      summary: List carrier accounts
      operationId: list-carrier-accounts
      parameters:
        - name: status
          in: query
          description: >-
            Filter by account status. Repeat the parameter or pass multiple values to match
            more than one status (e.g. `status=ACTIVE&status=INACTIVE`).
          schema:
            type: array
            items:
              $ref: '#/components/schemas/status-field'
          style: form
          explode: true
        - name: page
          in: query
          description: Page number (1-based). Default `1`.
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: page_size
          in: query
          description: Number of accounts per page. Default `10`.
          schema:
            type: integer
            minimum: 1
            default: 10
        - name: pagination
          in: query
          description: >-
            When `false`, all matching accounts are returned in `items` and `pagination.page`
            / `pagination.page_size` are `0`.
          schema:
            type: boolean
            default: true
        - name: search_string
          in: query
          description: Free-text search across account name and related fields.
          schema:
            type: string
        - name: carrier
          in: query
          description: Filter by carrier code (e.g. `DHL`, `QUIQUP`).
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: carrier_id
          in: query
          description: Filter by carrier account ID.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: account_name
          in: query
          description: Filter by carrier account display name.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: account_country
          in: query
          description: Filter by ISO 3166-1 alpha-2 account country.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: is_live
          in: query
          description: Filter by live vs test credentials in account properties.
          schema:
            type: boolean
        - name: sort_by
          in: query
          schema:
            type: string
        - name: sort_direction
          in: query
          schema:
            type: string
            enum:
              - ASC
              - DESC
      responses:
        '200':
          description: >-
            Paginated carrier accounts. The response is an object with `items` and
            `pagination`, not a bare array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-account-page'
              examples:
                page:
                  summary: First page of active accounts
                  value:
                    items:
                      - carrier_account_id: da335c3b-0f99-4558-b54a-851zx3b86975
                        carrier_account_name: QUIQUP SAME DAY
                        carrier: QUIQUP
                        account_country: AE
                        account_currency: AED
                        merchants:
                          - MERCH1
                        daily_capacity_id: 9a4bc256-7884-46c3-aa7f-bded930cca74
                        in_flight_capacity_id: 1b2c3d4e-5678-90ab-cdef-111122223333
                        costing_profile_id: 69f19360-12b0-4f4b-9b44-79653e2155c1
                        network_id: cd7b4dda-7250-4183-90dc-59344a095b14
                        property:
                          CLIENT_ID: client_id_value
                          CLIENT_SECRET: client_secret_value
                          BILLING_IDENTIFIER: billing_identifier_value
                          URL: https://api.staging.quiqup.com/
                        label:
                          default_label: carrier_pdf
                        status: ACTIVE
                        creation_date: '2022-12-30T07:04:06.298Z'
                        update_date: '2022-07-12T05:32:19.757Z'
                        auto_ready_to_ship: true
                        auto_return_confirmed: false
                        auto_translate_to_english: true
                        use_carrier_costing_api: false
                        generic_carrier: false
                        deleted: false
                    pagination:
                      total: 1
                      page: 1
                      page_size: 10
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List carrier accounts configured for your tenant. The response is a **paginated wrapper**
        (`items` plus `pagination`), not a JSON array at the root.

        By default, active and inactive accounts are included. Pass `status` (e.g. `ACTIVE`) to
        narrow the list. Only `ACTIVE` accounts can be used to book shipments.

        Use `page` and `page_size` to page through results. Set `pagination=false` to return all
        matches in a single response (pagination metadata will show `page` and `page_size` as `0`).
  /carrier-accounts/{carrier-account-id}:
    parameters:
      - schema:
          type: string
        name: carrier-account-id
        in: path
        required: true
    get:
      tags:
        - carrier-accounts
      summary: Get carrier account
      operationId: get-carrier-account
      parameters:
        - name: carrier-account-id
          in: path
          required: true
          schema:
            type: string
        - name: statistics
          in: query
          schema:
            type: boolean
          description: >-
            When `true`, the response includes carrier activity timestamps (last booking,
            last error, real-time and sync update dates).
        - name: integration_status
          in: query
          schema:
            type: boolean
          description: >-
            When `true`, the response includes `integration_statuses` with the result of
            live integration checks for the account.
      responses:
        '200':
          description: 'Returns the requested carrier account.'
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/carrier-account-object'
                  - $ref: '#/components/schemas/carrier-account-statistics-object'
        '404':
          description: Carrier account not found.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single carrier account by its `carrier-account-id`. By default the response
        matches a configured account (`carrier-account-object`). Pass
        `statistics=true` to receive activity timestamps (`carrier-account-statistics-object`).
    put:
      tags:
        - carrier-accounts
      summary: Update carrier account
      operationId: update-carrier-account
      parameters:
        - name: carrier-account-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/carrier-account-request'
        required: false
      responses:
        '200':
          description: 'Carrier account updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-account-object'
      x-codegen-request-body-name: body
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the configuration of a carrier account. The request body fully replaces the
        existing account; fields you omit are reset to defaults.
    delete:
      tags:
        - carrier-accounts
      summary: Delete carrier account
      operationId: delete-carrier-account
      parameters:
        - name: carrier-account-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Carrier account deleted. Response body is empty.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Soft-delete the specified carrier account. The account moves to `deleted` status and is
        no longer returned by `GET /carrier-accounts` unless you pass `status=deleted`. Active
        bookings on the account are not affected.


        The request is rejected with `400` if the account is referenced by any automation rule
        or service-level rule. Remove the references first, then retry.
  /automation-rulesets:
    post:
      tags:
        - shipping-rules
      summary: Create automation ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create an automation ruleset. The ruleset is the container for the routing rules
        Carriyo evaluates at booking time to pick a carrier account for each shipment. You can
        optionally pass an initial set of rules on the request; rules can also be added later.
      operationId: create-automation-ruleset-and-rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/automation-ruleset-with-rules-request'
      responses:
        '200':
          description: 'Automation ruleset and rules created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/automation-ruleset-with-rules-response'
    get:
      tags:
        - shipping-rules
      summary: List automation rulesets
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List automation rulesets. Pass `merchant` to filter to one merchant, or omit it to
        return rulesets across all merchants. Pass `entity-type` (`FORWARD` or `REVERSE`) to
        narrow to forward-shipment or reverse-shipment rulesets.
      operationId: list-automation-rulesets
      parameters:
        - name: merchant
          description: merchant id
          in: query
          schema:
            type: string
        - name: entity-type
          description: Shipment entity type FORWARD or REVERSE
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 'Matching automation rulesets.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ruleset-response'
  /automation-rulesets/{automation-ruleset-id}:
    get:
      tags:
        - shipping-rules
      summary: Get automation ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single automation ruleset by its `automation-ruleset-id`.
      operationId: get-automation-ruleset
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested automation ruleset.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ruleset-response'
    put:
      tags:
        - shipping-rules
      summary: Replace automation ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the ruleset and the rules it contains. The request body overwrites both; any
        rule not in the request is removed. To change just the ruleset's own metadata (name,
        merchants, entity type) without touching its rules, use `PATCH` instead.
      operationId: update-automation-ruleset-and-rules
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/automation-ruleset-with-rules-request'
      responses:
        '200':
          description: 'Automation ruleset and rules updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/automation-ruleset-with-rules-response'
    patch:
      tags:
        - shipping-rules
      summary: Update automation ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Update the ruleset's own metadata (name, merchants, entity type) without touching the
        rules it contains. To replace the rules as well, use `PUT`.
      operationId: patch-automation-ruleset
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ruleset-request'
      responses:
        '200':
          description: 'Automation ruleset updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ruleset-response'
    delete:
      tags:
        - shipping-rules
      summary: Delete automation ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Delete the ruleset and every rule it contains. Active bookings are unaffected, but
        from this point forward new bookings will fall through to any remaining rulesets, or
        return an error if no other ruleset matches.
      operationId: delete-automation-ruleset
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Automation ruleset deleted.'
          content:
            application/json:
              schema:
                type: object
  /automation-rulesets/{automation-ruleset-id}/rules:
    post:
      tags:
        - shipping-rules
      summary: Create automation rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Add a new rule to an existing ruleset. The rule's position in the evaluation order is
        managed separately via **Update automation sequence**.
      operationId: create-automation-rules
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/automation-rule-request'
      responses:
        '200':
          description: 'Automation rules created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/automation-rule-response'
    get:
      tags:
        - shipping-rules
      summary: List automation rules
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List the rules in the specified ruleset, ordered by their configured sequence.
      operationId: list-automation-rules
      parameters:
        - name: automation-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Matching automation rules.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/automation-rule-response'
  /automation-rulesets/{ruleset-id}/rules/sequences:
    patch:
      tags:
        - shipping-rules
      summary: Update automation sequence
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Set the evaluation order of rules within the ruleset. Carriyo evaluates rules in this
        order at booking time and stops at the first matching rule, so sequence drives which
        rule wins when more than one would match the shipment.
      operationId: update-automation-rules-sequence
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sequences-request'
      responses:
        '200':
          description: 'Automation rules sequence updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sequences-request'
  /automation-rulesets/{ruleset-id}/rules/{automation-rule-id}:
    get:
      tags:
        - shipping-rules
      summary: Get automation rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single automation rule by its `automation-rule-id` within the ruleset.
      operationId: get-automation-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: automation-rule-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested automation rule.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/automation-rule-response'
    put:
      tags:
        - shipping-rules
      summary: Update automation rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the rule's configuration. The request body fully replaces the existing rule;
        fields you omit are reset to defaults. The rule's position in the evaluation sequence
        is unchanged and is managed separately via **Update automation sequence**.
      operationId: update-automation-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: automation-rule-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/automation-rule-request'
      responses:
        '200':
          description: 'Automation rule updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/automation-rule-response'
    delete:
      tags:
        - shipping-rules
      summary: Delete automation rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Remove a single rule from its ruleset. The rest of the ruleset is unchanged. New
        bookings that would have matched this rule fall through to the next matching rule in
        the ruleset.
      operationId: delete-automation-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: automation-rule-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Automation rule deleted.'
          content:
            application/json:
              schema:
                type: object
  /service-level-rulesets:
    post:
      tags:
        - service-levels
      summary: Create service level ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a service-level ruleset. Service-level rules drive the delivery promise (estimated
        delivery date and any cut-off windows) Carriyo computes for each shipment. You can
        optionally include an initial set of rules on the request; rules can also be added later.
      operationId: create-service-level-ruleset-and-rules
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service-level-ruleset-with-rules-request'
      responses:
        '200':
          description: 'Service level ruleset and rules created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service-level-ruleset-with-rules-response'
    get:
      tags:
        - service-levels
      summary: List service level rulesets
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List service-level rulesets. Pass `merchant` to filter to one merchant, or omit it to
        return rulesets across all merchants. Pass `entity-type` (`FORWARD` or `REVERSE`) to
        narrow to forward-shipment or reverse-shipment rulesets.
      operationId: list-service-level-rulesets
      parameters:
        - name: merchant
          description: merchant id
          in: query
          schema:
            type: string
        - name: entity-type
          description: Shipment entity type FORWARD or REVERSE
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 'Matching service level rulesets.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ruleset-response'
  /service-level-rulesets/{service-level-ruleset-id}:
    get:
      tags:
        - service-levels
      summary: Get service level ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single service-level ruleset by its `service-level-ruleset-id`.
      operationId: get-service-level-ruleset
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested service level ruleset.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ruleset-response'
    put:
      tags:
        - service-levels
      summary: Replace service level ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the ruleset and the rules it contains. The request body overwrites both; any
        rule not in the request is removed. To change just the ruleset's own metadata without
        touching its rules, use `PATCH` instead.
      operationId: update-service-level-ruleset-and-rules
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service-level-ruleset-with-rules-request'
      responses:
        '200':
          description: 'Service level ruleset and rules updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service-level-ruleset-with-rules-response'
    patch:
      tags:
        - service-levels
      summary: Update service level ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Update the ruleset's own metadata (name, merchants, entity type) without touching the
        rules it contains. To replace the rules as well, use `PUT`.
      operationId: patch-service-level-ruleset
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ruleset-request'
      responses:
        '200':
          description: 'Service level ruleset updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ruleset-response'
    delete:
      tags:
        - service-levels
      summary: Delete service level ruleset
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Delete the ruleset and every rule it contains. Without an applicable service-level
        ruleset, Carriyo falls back to carrier-provided estimates for new shipments.
      operationId: delete-service-level-ruleset
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Service level ruleset deleted.'
          content:
            application/json:
              schema:
                type: object
  /service-level-rulesets/{service-level-ruleset-id}/rules:
    post:
      tags:
        - service-levels
      summary: Create service level rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Add a new rule to an existing service-level ruleset. The rule's position in the
        evaluation order is managed separately via **Update service level sequence**.
      operationId: create-service-level-rules
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service-level-rule-request'
      responses:
        '200':
          description: 'Service level rules created.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service-level-rule-response'
    get:
      tags:
        - service-levels
      summary: List service level rules
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List the rules in the specified service-level ruleset, ordered by their configured sequence.
      operationId: list-service-level-rules
      parameters:
        - name: service-level-ruleset-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Matching service level rules.'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/service-level-rule-response'
  /service-level-rulesets/{ruleset-id}/rules/sequences:
    patch:
      tags:
        - service-levels
      summary: Update service level sequence
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Set the evaluation order of rules within the service-level ruleset. Carriyo evaluates
        rules in this order and stops at the first matching rule, so sequence drives which rule
        wins when more than one would match the shipment.
      operationId: update-service-level-rules-sequence
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sequences-request'
      responses:
        '200':
          description: 'Service level rules sequence updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/sequences-request'
  /service-level-rulesets/{ruleset-id}/rules/{service-level-rule-id}:
    get:
      tags:
        - service-levels
      summary: Get service level rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single service-level rule by its `service-level-rule-id` within the ruleset.
      operationId: get-service-level-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: service-level-rule-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Returns the requested service level rule.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service-level-rule-response'
    put:
      tags:
        - service-levels
      summary: Update service level rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the rule's configuration. The request body fully replaces the existing rule;
        fields you omit are reset to defaults. The rule's position in the evaluation sequence
        is unchanged.
      operationId: update-service-level-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: service-level-rule-id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/service-level-rule-request'
      responses:
        '200':
          description: 'Service level rule updated.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service-level-rule-response'
    delete:
      tags:
        - service-levels
      summary: Delete service level rule
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Remove a single rule from its service-level ruleset. The rest of the ruleset is
        unchanged.
      operationId: delete-service-level-rule
      parameters:
        - name: ruleset-id
          in: path
          required: true
          schema:
            type: string
        - name: service-level-rule-id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 'Service level rule deleted.'
          content:
            application/json:
              schema:
                type: object
  /networks:
    post:
      tags:
        - carrier-networks
      summary: Create carrier network
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a new carrier network. A network groups carriers and their geographic or postcode
        coverage so it can be referenced as a condition in automation rules.
      operationId: create-carrier-network
      x-internal: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/carrier-network-dto'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-network-dto'
    get:
      tags:
        - carrier-networks
      summary: List carrier networks
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return all carrier networks defined for the tenant.
      operationId: list-carrier-networks
      x-internal: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/carrier-network-dto'
  /networks/{id}:
    get:
      tags:
        - carrier-networks
      summary: Get carrier network
      operationId: get-carrier-network
      x-internal: true
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Carrier network identifier.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-network-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single carrier network by its `id`.
  /networks/{id}/assign:
    post:
      tags:
        - carrier-networks
      summary: Assign carriers to network
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the list of carrier accounts associated with the network. The request body is
        the full set; accounts not in the list are removed from the network.
      operationId: assign-carrier-network
      x-internal: true
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Carrier network identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: Carrier account ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/carrier-network-dto'
  /costing-rules:
    post:
      tags:
        - carrier-costing
      x-internal: true
      summary: Create costing profile
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a shipment costing profile and its rules. The body is a `ShipmentCostingDto`
        wrapper with `costing_profile` and `costing_rules`.
      operationId: create-costing-profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-costing-dto'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-costing-dto'
    get:
      tags:
        - carrier-costing
      x-internal: true
      summary: List costing profiles
      operationId: list-costing-profiles
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/shipment-costing-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return all shipment costing profiles configured for the tenant.
  /costing-rules/{id}:
    get:
      tags:
        - carrier-costing
      x-internal: true
      summary: Get costing profile
      operationId: get-costing-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Costing profile ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-costing-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single shipment costing profile by its `id`, including its costing rules.
    put:
      tags:
        - carrier-costing
      x-internal: true
      summary: Update costing profile
      operationId: update-costing-profile-with-rules
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Costing profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-costing-dto'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-costing-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the costing profile and all of its rules. The body is a `ShipmentCostingDto`
        wrapper with `costing_profile` and `costing_rules`; any rule not in `costing_rules` is
        removed.
    delete:
      tags:
        - carrier-costing
      x-internal: true
      summary: Delete costing profile
      operationId: delete-costing-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Costing profile ID.
      responses:
        '204':
          description: Deleted.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently delete the costing profile and its rules. Carrier accounts that were using
        this profile fall back to live rating where available.
  /costing-rules/{profile_id}/rules:
    post:
      tags:
        - carrier-costing
      x-internal: true
      summary: Add costing rule
      operationId: create-costing-rule
      parameters:
        - name: profile_id
          in: path
          required: true
          schema:
            type: string
          description: Costing profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shipment-costing-rule-dto'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shipment-costing-rule-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Add a new costing rule to an existing shipment costing profile.
  /capacities:
    post:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Create capacity profile
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a capacity profile. The profile holds a set of rules that cap the number of
        shipments Carriyo will book against the assigned carrier accounts within a time window,
        so capacity-constrained carriers don't get overwhelmed.
      operationId: create-capacity-profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/capacity-profile-request'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-profile-dto'
    get:
      tags:
        - carrier-capacity
      x-internal: true
      summary: List capacity profiles
      operationId: list-capacity-profiles
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/capacity-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return all capacity profiles configured for the tenant.
  /capacities/{id}:
    get:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Get capacity profile
      operationId: get-capacity-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return a single capacity profile by its `id`, including its capacity rules.
    put:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Update capacity profile
      operationId: update-capacity-profile-with-rules
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/capacity-profile-request'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the capacity profile and its rules. The request body fully replaces the
        existing profile; any rule not in the request is removed. To change only the profile's
        own metadata without touching rules, use `PATCH`.
    patch:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Patch capacity profile
      operationId: patch-capacity-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/capacity-profile-dto'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Update the capacity profile's own metadata without touching the rules it contains.
        Only the supplied fields are changed; omitted fields are left as-is. To replace the
        rules as well, use `PUT`.
    delete:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Delete capacity profile
      operationId: delete-capacity-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      responses:
        '204':
          description: Deleted.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently delete the capacity profile and its rules. Carrier accounts that were
        assigned to this profile no longer have capacity caps enforced through it.
  /capacities/{id}/assign:
    post:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Assign carrier accounts to capacity profile
      operationId: assign-capacity-profile
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-profile-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace the list of carrier accounts assigned to the capacity profile. The request body
        is the full set; accounts not in the list are unassigned.
  /capacities/{profile_id}/rules:
    post:
      tags:
        - carrier-capacity
      x-internal: true
      summary: Add capacity rule
      operationId: create-capacity-rule
      parameters:
        - name: profile_id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/capacity-rule-dto'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/capacity-rule-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Add a new capacity rule to an existing capacity profile.
    get:
      tags:
        - carrier-capacity
      x-internal: true
      summary: List capacity rules
      operationId: list-capacity-rules
      parameters:
        - name: profile_id
          in: path
          required: true
          schema:
            type: string
          description: Capacity profile ID.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/capacity-rule-dto'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        List the capacity rules in the specified capacity profile.
  /document-settings:
    post:
      tags:
        - document-settings
      x-internal: true
      summary: Create document setting
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Create a document setting for the tenant. A document setting registers a document type
        (commercial invoice, packing list, label, manifest, POD) along with its format, template,
        and whether it can be uploaded to the carrier. Document uploads on shipments must match
        an existing setting.
      operationId: create-document-setting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/document-request'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/document-settings'
    get:
      tags:
        - document-settings
      x-internal: true
      summary: List document settings
      operationId: list-document-settings
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/document-settings'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Return all document settings configured for the tenant.
  /document-settings/{documentId}:
    put:
      tags:
        - document-settings
      x-internal: true
      summary: Update document setting
      operationId: update-document-setting
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
          description: Document setting ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/document-request'
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/document-settings'
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Replace a document setting's configuration. The request body fully replaces the
        existing setting; fields you omit are reset to defaults.
    delete:
      tags:
        - document-settings
      x-internal: true
      summary: Delete document setting
      operationId: delete-document-setting
      parameters:
        - name: documentId
          in: path
          required: true
          schema:
            type: string
          description: Document setting ID.
      responses:
        '204':
          description: Deleted.
      description: |-
        > **Setup endpoint.** Manage this in the Carriyo Dashboard, not the API.

        Permanently delete a document setting. Existing shipment documents tied to this setting
        are not removed retroactively, but new uploads referencing it are no longer accepted.
components:
  securitySchemes:
    OAuth2-Production:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.carriyo.com/oauth/token
          scopes: {}
    OAuth2-Demo:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://demo-api.carriyo.com/oauth/token
          scopes: {}
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: "Your tenant's API key, issued in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
    TenantId:
      type: apiKey
      in: header
      name: tenant-id
      description: "Your Carriyo tenant ID, shown in the Carriyo Dashboard. Required on every request except `POST /oauth/token`."
  schemas:
    carrier-account-fields:
      type: object
      description: Shared carrier account configuration fields.
      properties:
        carrier_account_id:
          type: string
          description: Unique identifier of the carrier account.
        parent:
          type: object
          description: Parent account reference for child (e.g. Click-n-Ship) accounts.
          properties:
            parent_id:
              type: string
            parent_tenant_id:
              type: string
        merchants:
          type: array
          description: Merchant IDs allowed to use this account.
          items:
            type: string
        carrier_account_name:
          type: string
        carrier:
          type: string
          description: Carrier code (e.g. `QUIQUP`, `DHL`).
        account_country:
          type: string
          description: ISO 3166-1 alpha-2 country code for the account.
        account_currency:
          type: string
          description: ISO 4217 currency code for the account.
        daily_capacity_id:
          type: string
        in_flight_capacity_id:
          type: string
        costing_profile_id:
          type: string
        network_id:
          type: string
        property:
          type: object
          additionalProperties:
            type: string
          description: Carrier-specific credential and configuration key-value pairs.
        carrier_custom_attributes:
          type: object
          additionalProperties:
            type: string
        document_mappings:
          type: object
          additionalProperties:
            type: string
        label:
          type: object
          properties:
            default_label:
              type: string
        service_schedule:
          type: object
          additionalProperties:
            type: object
          description: Per-service pickup schedule configuration.
        auto_ready_to_ship:
          type: boolean
        auto_return_confirmed:
          type: boolean
        auto_translate_to_english:
          type: boolean
        use_carrier_costing_api:
          type: boolean
        service_name:
          type: string
        service_description:
          type: string
        delivery_promise:
          type: string
        estimated_days:
          type: integer
        shipping_cost_markup_percentage:
          type: number
          format: double
        status:
          $ref: '#/components/schemas/status-field'
        deleted:
          type: boolean
          deprecated: true
          description: Deprecated. Use `status` instead (`DELETED`).
        generic_carrier:
          type: boolean
        packaging:
          type: object
          properties:
            default_parcel_weight:
              type: object
              description: Default parcel weight for this account.
            default_parcel_dimension:
              type: object
              description: Default parcel dimensions for this account.
        unique_identifier:
          type: string
        assets:
          type: object
          properties:
            signature_url:
              type: string
            logo_url:
              type: string
    carrier-account-object:
      title: Carrier Account Object
      allOf:
        - $ref: '#/components/schemas/carrier-account-fields'
        - type: object
          properties:
            creation_date:
              type: string
              format: date-time
              readOnly: true
            update_date:
              type: string
              format: date-time
              readOnly: true
            deletion_date:
              type: string
              format: date-time
              readOnly: true
            integration_statuses:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/carrier-integration-status'
              description: >-
                Present when `integration_status=true` on GET. Maps capability name to
                integration check result.
      description: Carrier account returned by list, create, get, and update endpoints.
      x-examples:
        example-1:
          carrier_account_id: da335c3b-0f99-4558-b54a-851zx3b86975
          carrier_account_name: QUIQUP SAME DAY
          carrier: QUIQUP
          account_country: AE
          account_currency: AED
          merchants:
            - MERCH1
          daily_capacity_id: 9a4bc256-7884-46c3-aa7f-bded930cca74
          in_flight_capacity_id: 1b2c3d4e-5678-90ab-cdef-111122223333
          costing_profile_id: 69f19360-12b0-4f4b-9b44-79653e2155c1
          network_id: cd7b4dda-7250-4183-90dc-59344a095b14
          property:
            CLIENT_ID: client_id_value
            CLIENT_SECRET: client_secret_value
            BILLING_IDENTIFIER: billing_identifier_value
            URL: https://api.staging.quiqup.com/
          label:
            default_label: carrier_pdf
          status: ACTIVE
          creation_date: '2022-12-30T07:04:06.298Z'
          update_date: '2022-07-12T05:32:19.757Z'
          auto_ready_to_ship: true
          auto_return_confirmed: false
          auto_translate_to_english: true
          use_carrier_costing_api: false
          generic_carrier: false
          deleted: false
    carrier-account-statistics-object:
      allOf:
        - $ref: '#/components/schemas/carrier-account-object'
        - type: object
          properties:
            last_booking_date:
              type: string
              format: date-time
              readOnly: true
            last_error_date:
              type: string
              format: date-time
              readOnly: true
            last_real_time_update_received_date:
              type: string
              format: date-time
              readOnly: true
            last_real_time_update_applied_date:
              type: string
              format: date-time
              readOnly: true
            last_sync_update_received_date:
              type: string
              format: date-time
              readOnly: true
            last_sync_update_applied_date:
              type: string
              format: date-time
              readOnly: true
            test_data:
              type: boolean
              readOnly: true
      description: >-
        Carrier account with activity timestamps. Returned when `statistics=true` on
        `GET /carrier-accounts/{carrier-account-id}`.
    carrier-account-request:
      title: Carrier Account Request
      allOf:
        - $ref: '#/components/schemas/carrier-account-fields'
      description: Request body for create and update carrier account endpoints.
      x-examples:
        example-1:
          carrier_account_name: QUIQUP SAME DAY
          carrier: QUIQUP
          account_country: AE
          account_currency: AED
          daily_capacity_id: 9a4bc256-7884-46c3-aa7f-bded930cca74
          costing_profile_id: 69f19360-12b0-4f4b-9b44-79653e2155c1
          network_id: cd7b4dda-7250-4183-90dc-59344a095b14
          property:
            CLIENT_ID: client_id_value
            CLIENT_SECRET: client_secret_value
            BILLING_IDENTIFIER: billing_identifier_value
            URL: https://api.staging.quiqup.com/
          label:
            default_label: carrier_pdf
          status: ACTIVE
          auto_ready_to_ship: true
          auto_return_confirmed: false
          auto_translate_to_english: true
    carrier-integration-status:
      type: object
      properties:
        success:
          type: boolean
        error_message:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    carrier-account-page:
      title: Carrier Account Page
      type: object
      description: >-
        Paginated carrier account list (`PageableItems`). Returned by `GET /carrier-accounts`.
      required:
        - items
        - pagination
      properties:
        items:
          type: array
          description: >-
            `carrier-account-object[]` — carrier accounts for the current page (or all matches
            when `pagination=false`).
          items:
            $ref: '#/components/schemas/carrier-account-object'
        pagination:
          type: object
          required:
            - total
            - page
            - page_size
          properties:
            total:
              type: integer
              format: int64
              description: Total number of accounts matching the filters.
            page:
              type: integer
              description: Current page number (1-based), or `0` when pagination is disabled.
            page_size:
              type: integer
              description: Page size used for this request, or `0` when pagination is disabled.
    automation-ruleset-with-rules-request:
      title: Automation Ruleset with Rules Request
      type: object
      properties:
        automation_ruleset:
          $ref: '#/components/schemas/ruleset-request'
        automation_rules:
          type: array
          items:
            $ref: '#/components/schemas/automation-rule-request'
      required:
        - automation_ruleset
      x-examples:
        example-1:
          automation_ruleset:
            name: Default routing
            entity_type: FORWARD
            merchants:
              - _ANY
            countries:
              - _ANY
            status: ACTIVE
          automation_rules:
            - rule_name: Cheapest carrier
              merchant:
                operator: INCLUSION
                value:
                  - _ANY
              carrier_accounts:
                - carrier: DHL
                  carrier_id: act_example123
                  carrier_account_name: DHL Express
              carrier_choice: CHEAPEST_CARRIER
              round_robin_carriers:
                - carrier_account_id: act_example123
                  quota: 100
              daily_limit:
                threshold: 500
              status: ACTIVE
    automation-ruleset-with-rules-response:
      title: Automation Ruleset with Rules Response
      type: object
      properties:
        automation_ruleset:
          $ref: '#/components/schemas/ruleset-response'
        automation_rules:
          type: array
          items:
            $ref: '#/components/schemas/automation-rule-response'
      required:
        - automation_ruleset
    ruleset-response:
      title: Ruleset Response
      type: object
      properties:
        tenant:
          type: string
        rule_set_id:
          type: string
        name:
          type: string
        entity_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
        merchants:
          type: array
          description: List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
          items:
            type: string
        countries:
          type: array
          description: List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
          items:
            type: string
        status:
          $ref: '#/components/schemas/status-field'
        creation_date:
          type: string
          format: date-time
        update_date:
          type: string
          format: date-time
    ruleset-request:
      title: Ruleset Request
      type: object
      properties:
        name:
          type: string
        entity_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
        merchants:
          type: array
          description: List of Merchant ids used in Ruleset. Use ["_ANY"] for all merchants
          items:
            type: string
        countries:
          type: array
          description: List of country iso2 codes used in Ruleset. Use ["_ANY"] for all countries
          items:
            type: string
        status:
          $ref: '#/components/schemas/status-field'
      required:
        - name
        - entity_type
        - merchants
        - countries
        - status
    automation-rule-request:
      title: Automation rule request
      type: object
      description: Body for creating or updating an automation rule. Automation rules select a carrier account (or rotation) for matching shipments based on geography, payment, weight, custom-attribute and other conditions.
      properties:
        rule_id: &id001
          type: string
          description: Server-assigned rule identifier. Provide on update; omit on create.
          readOnly: true
        rule_set_id: &id002
          type: string
          description: ID of the parent automation ruleset.
          readOnly: true
        rule_name: &id003
          type: string
          description: Human-readable name for the rule.
        description: &id004
          type: string
          description: Optional notes about the rule.
        sequence: &id005
          type: integer
          description: Rule evaluation order within the ruleset. Lower values evaluate first.
        status: &id006
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Rule status.
        merchant: &id007
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.merchant.
        creation_source_type: &id008
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.creation_source.source_type.
        update_source_type: &id009
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.update_source.source_type.
        dropoff_v2: &id010
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment dropoff country / state / city / area.
        dropoff_partner_location_ids: &id011
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff partner location IDs.
        dropoff_postcode: &id012
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff postcode.
        pickup_v2: &id013
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment pickup country / state / city / area.
        pickup_partner_location_ids: &id014
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup partner location IDs.
        pickup_postcode: &id015
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup postcode.
        payment_type: &id016
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.payment.type.
        delivery_type: &id017
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.delivery_type.
        order_type: &id018
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.order_type.
        dangerous_goods: &id019
          type: string
          description: 'Filter on shipment.items[].dangerous_goods. Values: `ANY`, `ONLY`, `NONE`.'
        customer_address_verified: &id020
          type: string
          description: 'Filter on shipment.dropoff.address_verified. Values: `ANY`, `VERIFIED`, `UNVERIFIED`.'
        volumetric_weight: &id021
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels volumetric weight.
        gross_weight: &id022
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels gross weight.
        chargeable_weight: &id023
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels chargeable weight.
        parcel_count: &id024
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcel count.
        order_value: &id025
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment.payment.total_amount.
        item_value: &id026
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment.items[].price aggregated value.
        custom_conditions_v2: &id027
          type: array
          items:
            $ref: '#/components/schemas/custom-attributes-condition-field'
          description: Match against shipment.custom_attributes. Each entry is AND-combined.
        schedule: &id028
          allOf:
            - $ref: '#/components/schemas/schedule-dto'
          description: >-
            When the rule applies: recurring `working_days` / `working_hours`, optional
            `working_period`, `blackout_days`, and `schedule_by` (reference date). Omitted or
            empty `working_days` = always.
        carrier_accounts: &id029
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/carrier-account-bean'
          description: Carrier accounts the rule selects from (`CarrierAccountBean`).
        carrier_choice: &id030
          type: string
          enum:
            - CHEAPEST_CARRIER
            - ROUND_ROBIN
          description: >-
            Flat enum (`CarrierChoice`), not an object. `CHEAPEST_CARRIER` selects the lowest-cost
            account; `ROUND_ROBIN` uses `round_robin_carriers` quotas.
        round_robin_carriers: &id031
          type: array
          items:
            $ref: '#/components/schemas/round-robin-carrier'
          description: Quota entries when `carrier_choice` is `ROUND_ROBIN`.
        daily_limit: &id032
          allOf:
            - $ref: '#/components/schemas/daily-limit'
          description: Optional per-rule daily cap.
    automation-rule-response:
      title: Automation rule response
      type: object
      description: Full automation rule as stored. Includes audit fields populated by the server.
      properties:
        rule_id: *id001
        rule_set_id: *id002
        rule_name: *id003
        description: *id004
        sequence: *id005
        status: *id006
        merchant: *id007
        creation_source_type: *id008
        update_source_type: *id009
        dropoff_v2: *id010
        dropoff_partner_location_ids: *id011
        dropoff_postcode: *id012
        pickup_v2: *id013
        pickup_partner_location_ids: *id014
        pickup_postcode: *id015
        payment_type: *id016
        delivery_type: *id017
        order_type: *id018
        dangerous_goods: *id019
        customer_address_verified: *id020
        volumetric_weight: *id021
        gross_weight: *id022
        chargeable_weight: *id023
        parcel_count: *id024
        order_value: *id025
        item_value: *id026
        custom_conditions_v2: *id027
        schedule: *id028
        carrier_accounts: *id029
        carrier_choice: *id030
        round_robin_carriers: *id031
        daily_limit: *id032
        tenant:
          type: string
          description: Tenant identifier.
          readOnly: true
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
    sequences-request:
      title: Update Rules Sequences
      type: array
      items:
        type: object
        properties:
          rule_id:
            type: string
          sequence:
            type: number
      required:
        - rule_id
        - sequence
    service-level-ruleset-with-rules-request:
      title: Service Level Ruleset with Rules Request
      type: object
      properties:
        service_level_ruleset:
          $ref: '#/components/schemas/ruleset-request'
        service_level_rules:
          type: array
          items:
            $ref: '#/components/schemas/service-level-rule-request'
      required:
        - service_level_ruleset
    service-level-ruleset-with-rules-response:
      title: Service Level Ruleset with Rules Response
      type: object
      properties:
        service_level_ruleset:
          $ref: '#/components/schemas/ruleset-response'
        service_level_rules:
          type: array
          items:
            $ref: '#/components/schemas/service-level-rule-response'
      required:
        - service_level_ruleset
    service-level-rule-request:
      title: Service-level rule request
      type: object
      description: Body for creating or updating a service-level rule. Service-level rules attach lead-time SLAs to shipments matching the supplied conditions.
      properties:
        rule_id: &id033
          type: string
          description: Server-assigned rule identifier. Provide on update; omit on create.
          readOnly: true
        rule_set_id: &id034
          type: string
          description: ID of the parent service-level ruleset.
          readOnly: true
        name: &id035
          type: string
          description: Human-readable name for the rule.
        description: &id036
          type: string
          description: Optional notes about the rule.
        sequence: &id037
          type: integer
          description: Rule evaluation order within the ruleset. Lower values evaluate first.
        config_type: &id038
          type: string
          enum:
            - FULFILLMENT
            - SHIPPING
            - DELIVERY
            - PROMISED
          description: >-
            SLA stage the rule applies to (`ConfigType`): fulfillment processing,
            shipping/collection, delivery attempt, or customer promise.
        status: &id039
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Rule status.
        merchants: &id040
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.merchant (`StringCondition` with `operator` and `value`).
        creation_source_type: &id041
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.creation_source.source_type.
        update_source_type: &id042
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.update_source.source_type.
        delivery_types: &id043
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.delivery_type.
        order_types: &id044
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.order_type.
        carrier_ids: &id045
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match carrier account IDs (`carrier_id` on assigned accounts).
        carrier_accounts: &id046
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match carrier account IDs.
        dropoff_v2: &id047
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment dropoff country / state / city / area.
        dropoff_partner_location_ids: &id048
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff partner location IDs.
        dropoff_postcode: &id049
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff postcode.
        pickup_v2: &id050
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment pickup country / state / city / area.
        pickup_partner_location_ids: &id051
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup partner location IDs.
        pickup_postcode: &id052
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup postcode.
        volumetric_weight: &id053
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels volumetric weight.
        gross_weight: &id054
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels gross weight.
        custom_conditions_v2: &id055
          type: array
          items:
            $ref: '#/components/schemas/custom-attributes-condition-field'
          description: Match against shipment.custom_attributes. Each entry is AND-combined.
        schedule: &id057
          allOf:
            - $ref: '#/components/schemas/schedule-dto'
          description: When the rule applies. Same shape as automation rule `schedule`. Omitted = always.
        lead_sla: &id056
          allOf:
            - $ref: '#/components/schemas/estimation-sla'
          description: Lead-time SLA (`EstimationSLA`) — `TIME_BASED` or `DAY_BASED`.
      required:
        - name
        - config_type
        - sequence
        - lead_sla
        - status
    service-level-rule-response:
      title: Service-level rule response
      type: object
      description: Full service-level rule as stored. Includes audit fields populated by the server.
      properties:
        rule_id: *id033
        rule_set_id: *id034
        name: *id035
        description: *id036
        sequence: *id037
        config_type: *id038
        status: *id039
        merchants: *id040
        creation_source_type: *id041
        update_source_type: *id042
        delivery_types: *id043
        order_types: *id044
        carrier_ids: *id045
        carrier_accounts: *id046
        dropoff_v2: *id047
        dropoff_partner_location_ids: *id048
        dropoff_postcode: *id049
        pickup_v2: *id050
        pickup_partner_location_ids: *id051
        pickup_postcode: *id052
        volumetric_weight: *id053
        gross_weight: *id054
        custom_conditions_v2: *id055
        schedule: *id057
        lead_sla: *id056
    status-field:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
        - DELETED
    string-condition-field:
      title: String condition
      type: object
      description: Inclusion or exclusion match against a list of string values (`StringCondition`).
      required:
        - operator
        - value
      properties:
        operator:
          type: string
          enum:
            - INCLUSION
            - EXCLUSION
        value:
          type: array
          items:
            type: string
          minItems: 1
    geography-condition-field:
      type: object
      properties:
        operator:
          type: string
          enum:
            - INCLUSION
            - EXCLUSION
        value:
          type: array
          items:
            $ref: '#/components/schemas/country-states-v2'
    number-area-condition-field:
      type: object
      properties:
        min_value:
          type: number
        max_value:
          type: number
    custom-attributes-condition-field:
      title: Custom attribute condition
      type: object
      description: Match a shipment custom attribute (`CustomConditionV2`).
      required:
        - operator
        - attribute_name
        - values
      properties:
        operator:
          type: string
          enum:
            - INCLUSION
            - EXCLUSION
        attribute_name:
          type: string
          description: Custom attribute key on the shipment.
        values:
          type: array
          items:
            type: string
          minItems: 1
          description: Attribute values to match.
    days-field:
      type: array
      items:
        type: string
        enum:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
          - SATURDAY
          - SUNDAY
    capacity-profile-dto:
      title: Capacity profile
      type: object
      description: A capacity profile groups capacity rules and applies them to one or more carrier accounts. `DAILY` capacity caps shipments per UTC day; `IN_FLIGHT` capacity caps shipments currently in the carrier network.
      properties:
        profile_id:
          type: string
          description: Carriyo-issued identifier for the capacity profile. Server-assigned on create.
          readOnly: true
        profile_name:
          type: string
          description: Human-readable name for the profile.
        capacity_type:
          type: string
          enum:
            - DAILY
            - IN_FLIGHT
          description: 'Capacity-counting mode: `DAILY` resets at the configured daily start time; `IN_FLIGHT` counts shipments not yet delivered.'
        daily_capacity_start_time:
          type: string
          description: 'For `DAILY` profiles: HH:mm time at which the daily window resets (24-hour, UTC). Ignored for `IN_FLIGHT`.'
        carrier_account_ids:
          type: array
          items:
            type: string
          description: Carrier account IDs that this profile applies to.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Profile status.
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
    capacity-rule-dto:
      title: Capacity rule
      type: object
      description: A capacity rule defines a threshold (a maximum shipment count) and the conditions under which it applies. Capacity rules belong to a `capacity-profile-dto`.
      properties:
        capacity_id:
          type: string
          description: Carriyo-issued identifier for the capacity rule. Server-assigned on create.
          readOnly: true
        capacity_profile_id:
          type: string
          description: ID of the parent capacity profile.
          readOnly: true
        name:
          type: string
          description: Human-readable name for the rule.
        entity_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
            - CONSOLIDATED
          description: Shipment entity type the rule applies to.
        sequence:
          type: integer
          description: Rule evaluation order within the profile. Lower values evaluate first.
        threshold:
          type: integer
          description: Maximum number of shipments allowed under this rule before capacity is considered full.
        daily_capacity_start_time:
          type: string
          description: Overrides the profile-level start time for this rule (HH:mm, UTC). Only meaningful when the parent profile is `DAILY`.
        days:
          allOf:
            - $ref: '#/components/schemas/days-field'
          description: Days of the week when the rule applies.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Rule status.
        dropoff_v2:
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment dropoff country / state / city / area.
        dropoff_partner_location_ids:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff partner location IDs.
        dropoff_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff postcode.
        pickup_v2:
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment pickup country / state / city / area.
        pickup_partner_location_ids:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup partner location IDs.
        pickup_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup postcode.
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment delivery_type.
        order_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment order_type.
        creation_source_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.creation_source.source_type.
        update_source_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.update_source.source_type.
        custom_conditions_v2:
          type: array
          items:
            $ref: '#/components/schemas/custom-attributes-condition-field'
          description: Match against shipment.custom_attributes. Each entry is one custom-attribute condition; all entries are AND-combined.
        special_start_date:
          type: string
          format: date-time
          description: Optional special capacity window start (ISO 8601).
        special_end_date:
          type: string
          format: date-time
          description: Optional special capacity window end (ISO 8601).
        creation_date:
          type: string
          format: date-time
          readOnly: true
        update_date:
          type: string
          format: date-time
          readOnly: true
    capacity-profile-request:
      title: Capacity profile request
      type: object
      description: Body for creating or fully updating a capacity profile together with its rules.
      properties:
        capacity_profile:
          $ref: '#/components/schemas/capacity-profile-dto'
        capacity_rules:
          type: array
          items:
            $ref: '#/components/schemas/capacity-rule-dto'
    country-states-v2:
      title: Country states (v2)
      type: object
      description: >-
        Geographic scope entry (`CountryStatesV2`). Used in carrier `network_v2` and inside
        geography rule conditions.
      required:
        - country
        - state_cities
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code.
        state_cities:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/state-cities-v2'
    state-cities-v2:
      title: State and cities (v2)
      type: object
      required:
        - state
        - city_areas
      properties:
        state:
          type: string
          description: State or region name.
        city_areas:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/city-areas-v2'
    city-areas-v2:
      title: City and areas (v2)
      type: object
      required:
        - city
        - areas
      properties:
        city:
          type: string
        areas:
          type: array
          minItems: 1
          items:
            type: string
    carrier-network-dto:
      title: Carrier network
      type: object
      description: A carrier network groups carrier accounts that serve a common geography. Networks can be assigned to specific carrier accounts via the `/networks/{id}/assign` endpoint.
      properties:
        network_id:
          type: string
          description: Carriyo-issued identifier for the network. Server-assigned on create.
          readOnly: true
        tenant:
          type: string
          description: Tenant identifier (set from the request `tenant-id` header).
          readOnly: true
        name:
          type: string
          description: Human-readable name for the network.
        network_v2:
          type: array
          items:
            $ref: '#/components/schemas/country-states-v2'
          description: Country / state / city / area entries that define the geographic scope of the network.
        pickup_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup postcode.
        dropoff_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff postcode.
        carrier_account_ids:
          type: array
          items:
            type: string
          description: Carrier account IDs assigned to this network.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Network status.
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
    breakdown-item:
      title: Costing breakdown item
      type: object
      description: A line item in a profile or rule cost breakdown (`BreakdownItem`).
      properties:
        amount:
          type: number
          description: Line amount.
        currency:
          type: string
          description: ISO 4217 currency code for the line.
        description:
          type: string
          description: Human-readable label (e.g. base fee, fuel surcharge).
    shipment-costing-dto:
      title: Shipment costing profile with rules
      type: object
      description: >-
        Wrapper (`ShipmentCostingDto`) for creating or replacing a costing profile together
        with its rules. Used by `POST /costing-rules` and `PUT /costing-rules/{id}`.
      required:
        - costing_profile
        - costing_rules
      properties:
        costing_profile:
          $ref: '#/components/schemas/shipment-costing-profile-dto'
        costing_rules:
          type: array
          items:
            $ref: '#/components/schemas/shipment-costing-rule-dto'
          description: Full rule set for the profile (replaces existing rules on PUT).
    shipment-costing-profile-dto:
      title: Shipment costing profile
      type: object
      description: A shipment costing profile defines how carrier charges are computed for shipments routed through specific carrier accounts. The profile holds the default cost and breakdown; per-shipment rules can override the cost based on conditions.
      properties:
        profile_id:
          type: string
          description: Carriyo-issued identifier for the costing profile. Server-assigned on create.
          readOnly: true
        profile_name:
          type: string
          description: Human-readable name for the profile.
        carrier_billing_currency:
          type: string
          description: ISO 4217 currency code in which the carrier bills (e.g. `USD`, `AED`, `EUR`).
        default_shipment_cost:
          type: number
          description: Default per-shipment cost in `carrier_billing_currency`. Used when no rule matches.
        tax_rate:
          type: number
          description: Tax rate (percentage, e.g. 5.0 for 5%) applied on top of the computed cost.
        breakdown:
          type: array
          items:
            $ref: '#/components/schemas/breakdown-item'
          description: Default cost breakdown lines (base fee, fuel surcharge, etc.).
        carrier_account_ids:
          type: array
          items:
            type: string
          description: Carrier account IDs to which this profile applies.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Profile status.
    shipment-cost-structure:
      title: Shipment cost structure
      type: object
      description: Per-rule cost model (`ShipmentCostStructure`) when the profile default does not apply.
      properties:
        fixed_cost:
          type: number
          description: Fixed per-shipment cost.
        variable_cost:
          $ref: '#/components/schemas/variable-weight-cost'
        cod_surcharge:
          $ref: '#/components/schemas/cod-surcharge'
    variable-weight-cost:
      title: Variable weight cost
      type: object
      properties:
        base_cost:
          type: number
        base_weight_value:
          type: number
        weight_unit:
          type: string
          description: Weight unit for incremental calculation (e.g. `kg`).
        incremental_weight_value:
          type: number
        incremental_cost:
          type: number
    cod-surcharge:
      title: COD surcharge
      type: object
      properties:
        fixed_cost:
          type: number
        percentage_cost:
          type: number
          description: Percentage surcharge for cash-on-delivery (0–100).
    shipment-costing-rule-dto:
      title: Shipment costing rule
      type: object
      description: A costing rule overrides the profile default cost when its conditions match a shipment. Rules belong to a shipment costing profile.
      properties:
        rule_id:
          type: string
          description: Carriyo-issued rule identifier.
          readOnly: true
        costing_profile_id:
          type: string
          description: ID of the parent costing profile.
          readOnly: true
        name:
          type: string
          description: Human-readable name for the rule.
        entity_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
            - CONSOLIDATED
          description: Shipment entity type the rule applies to.
        sequence:
          type: integer
          description: Rule evaluation order within the profile. Lower values evaluate first.
        cost_structure:
          $ref: '#/components/schemas/shipment-cost-structure'
        cost_per_shipment:
          type: number
          description: Convenience override of just the per-shipment cost (in profile currency). When set together with `cost_structure`, the structure wins.
        effective_date:
          type: string
          format: date-time
          description: Date from which the rule is effective.
        expiry_date:
          type: string
          format: date-time
          description: Date after which the rule no longer applies.
        schedule:
          $ref: '#/components/schemas/schedule-dto'
        dropoff_v2:
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment dropoff country / state / city / area.
        dropoff_partner_location_ids:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff partner location IDs.
        dropoff_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment dropoff postcode.
        pickup_v2:
          allOf:
            - $ref: '#/components/schemas/geography-condition-field'
          description: Match shipment pickup country / state / city / area.
        pickup_partner_location_ids:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup partner location IDs.
        pickup_postcode:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment pickup postcode.
        delivery_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment delivery_type.
        order_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment order_type.
        payment_type:
          allOf:
            - $ref: '#/components/schemas/string-condition-field'
          description: Match shipment.payment.type.
        dangerous_goods:
          type: string
          description: 'Filter on shipment.items[].dangerous_goods. Values: `ANY`, `ONLY`, `NONE`.'
        volumetric_weight:
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels volumetric weight.
        gross_weight:
          allOf:
            - $ref: '#/components/schemas/number-area-condition-field'
          description: Match shipment parcels gross weight.
        custom_conditions_v2:
          type: array
          items:
            $ref: '#/components/schemas/custom-attributes-condition-field'
          description: Match against shipment.custom_attributes. Each entry is AND-combined.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Rule status.
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
    document-request:
      title: Document setting request
      type: object
      description: Body for creating or updating a document setting. A document setting defines a print template (label, packing list, commercial invoice, etc.) that can be generated for a shipment or order.
      properties:
        name:
          type: string
          description: Human-readable name for the document setting.
        format:
          type: string
          enum:
            - PDF
            - ZPL
            - JSON
            - HTML
          description: Output format of the rendered document.
        type:
          type: string
          description: Sub-type of the document (e.g. `4x6`, `A4`, `THERMAL`).
        shipment_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
            - CONSOLIDATED
          description: Shipment entity type the document applies to.
        document_type:
          type: string
          enum:
            - LABEL
            - PACKING_LIST
            - COMMERCIAL_INVOICE
            - MANIFEST
            - RETURN_AUTHORIZATION
            - CUSTOM
          description: High-level document category.
        entity_type:
          $ref: '#/components/schemas/document-entity-type'
        template_name:
          type: string
          description: Name of the rendering template stored in the document service.
        assigned_documents:
          type: array
          items:
            type: string
          description: Identifiers of related document settings that should be rendered alongside this one.
        quick_print_enabled:
          type: boolean
          description: True to expose this document on the dashboard's quick-print menu.
        uploaded_document:
          type: boolean
          description: True when the template was uploaded by the user rather than supplied by Carriyo.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Document setting status.
    document-entity-type:
      type: string
      enum:
        - SHIPMENT
        - RETURN_REQUEST
      description: >-
        Entity the document applies to (`DocumentEntityType`). Only `SHIPMENT` and
        `RETURN_REQUEST` are supported.
    document-settings:
      title: Document setting
      type: object
      description: A document setting stored in Carriyo. Returned by document-setting endpoints.
      properties:
        tenant_id:
          type: string
          description: Tenant identifier.
          readOnly: true
        document_id:
          type: string
          description: Carriyo-issued identifier for the document setting.
          readOnly: true
        name:
          type: string
          description: Human-readable name.
        format:
          type: string
          enum:
            - PDF
            - ZPL
            - JSON
            - HTML
          description: Output format.
        type:
          type: string
          description: Sub-type (e.g. `4x6`, `A4`).
        shipment_type:
          type: string
          enum:
            - FORWARD
            - REVERSE
            - CONSOLIDATED
          description: Shipment entity type.
        document_type:
          type: string
          enum:
            - LABEL
            - PACKING_LIST
            - COMMERCIAL_INVOICE
            - MANIFEST
            - RETURN_AUTHORIZATION
            - CUSTOM
          description: Document category.
        entity_type:
          $ref: '#/components/schemas/document-entity-type'
        template_name:
          type: string
          description: Rendering template name.
        assigned_documents:
          type: array
          items:
            type: string
          description: Identifiers of related document settings.
        quick_print_enabled:
          type: boolean
          description: True if exposed on the dashboard quick-print menu.
        uploaded_document:
          type: boolean
          description: True if user-uploaded.
        status:
          allOf:
            - $ref: '#/components/schemas/status-field'
          description: Document setting status.
        creation_date:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601).
          readOnly: true
        update_date:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601).
          readOnly: true
        updated_by_user:
          type: string
          description: User identifier (typically email) of the last updater.
          readOnly: true
    schedule-dto:
      title: Schedule
      type: object
      description: >-
        Rule schedule (`ScheduleDto`). Used on automation rules, service-level rules, and
        costing rules. Empty or omitted `working_days` means the rule applies at any time.
      properties:
        working_days:
          type: array
          description: Recurring weekly windows. Each day lists one or more `working_hours` ranges.
          items:
            $ref: '#/components/schemas/schedule-working-day'
        working_period:
          $ref: '#/components/schemas/schedule-from-and-to-date'
          description: Optional calendar date range when the schedule is active.
        blackout_days:
          type: array
          description: Specific dates when the rule does not apply.
          items:
            $ref: '#/components/schemas/schedule-blocked-day'
        schedule_by:
          type: string
          enum:
            - BOOKED_DATE
            - ORDER_DATE
          description: >-
            Reference date used to evaluate `working_days` and `blackout_days`. Defaults to
            booked date when omitted.
    schedule-working-day:
      title: Schedule working day
      type: object
      required:
        - day_of_week
        - working_hours
      properties:
        day_of_week:
          type: string
          enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        working_hours:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/schedule-working-hours'
    schedule-working-hours:
      title: Schedule working hours
      type: object
      required:
        - start_time
        - end_time
      properties:
        start_time:
          type: string
          description: Start of the window in HH:mm (24-hour).
        end_time:
          type: string
          description: End of the window in HH:mm (24-hour). May be earlier than `start_time` for cross-midnight windows.
    schedule-from-and-to-date:
      title: Schedule date period
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          description: Start date (inclusive). ISO 8601 date or date-time string.
        to:
          type: string
          description: End date (inclusive). ISO 8601 date or date-time string.
    schedule-blocked-day:
      title: Schedule blackout day
      type: object
      required:
        - date
      properties:
        name:
          type: string
          description: Optional label for the blackout (e.g. public holiday).
        date:
          type: string
          description: Blackout date. ISO 8601 date or date-time string.
    carrier-account-bean:
      title: Carrier account bean
      type: object
      description: >-
        Carrier account reference on automation rules (`CarrierAccountBean`). Not the full
        carrier account configuration object.
      properties:
        carrier:
          type: string
          description: Carrier code (e.g. `DHL`, `QUIQUP`).
        carrier_id:
          type: string
          description: Carrier account ID.
        carrier_account_name:
          type: string
          description: Carrier account display name.
    round-robin-carrier:
      title: Round-robin carrier entry
      type: object
      description: Quota entry for `ROUND_ROBIN` carrier selection (`RoundRobinCarrier`).
      properties:
        carrier_account_id:
          type: string
          description: Carrier account ID in the rotation.
        quota:
          type: integer
          minimum: 1
          maximum: 100
          description: Relative quota share (1–100).
    daily-limit:
      title: Daily limit
      type: object
      description: Optional per-rule daily shipment cap (`DailyLimit`).
      properties:
        threshold:
          type: integer
          description: Maximum shipments matched by this rule per day.
    estimation-sla:
      title: Estimation SLA
      description: Lead-time SLA (`EstimationSLA`). Discriminated by `type`.
      oneOf:
        - $ref: '#/components/schemas/time-based-sla'
        - $ref: '#/components/schemas/day-based-sla'
      discriminator:
        propertyName: type
        mapping:
          TIME_BASED: '#/components/schemas/time-based-sla'
          DAY_BASED: '#/components/schemas/day-based-sla'
    sla-blackout-day:
      title: SLA blackout date range
      type: object
      properties:
        name:
          type: string
        start_date:
          type: string
          description: Start date (yyyy-MM-dd).
        end_date:
          type: string
          description: End date (yyyy-MM-dd).
    time-based-sla:
      title: Time-based SLA
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - TIME_BASED
        duration:
          $ref: '#/components/schemas/time-based-duration'
        delivery_window:
          $ref: '#/components/schemas/time-based-duration'
        working_schedule:
          type: array
          items:
            $ref: '#/components/schemas/schedule-working-day'
        blackout_dates:
          type: array
          items:
            $ref: '#/components/schemas/sla-blackout-day'
    day-based-sla:
      title: Day-based SLA
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - DAY_BASED
        duration:
          $ref: '#/components/schemas/day-based-duration'
        delivery_window:
          $ref: '#/components/schemas/day-based-duration'
        cutoff_schedule:
          type: object
          additionalProperties:
            type: string
          description: Map of `MONDAY`…`SUNDAY` to cutoff time (HH:mm).
        eta_time:
          type: string
          description: ETA time of day (HH:mm) applied on the estimated date.
        blackout_dates:
          type: array
          items:
            $ref: '#/components/schemas/sla-blackout-day'
    time-based-duration:
      title: Time-based duration
      type: object
      properties:
        hour:
          type: integer
        minute:
          type: integer
    day-based-duration:
      title: Day-based duration
      type: object
      properties:
        day:
          type: integer
