Kibo Commerce Reservation Rules API

openapi: 3.2.0
info:
  title: Kibo Commerce Reservation Rules API
  version: '1.0'
  description: 'Operations tagged ReservationRules across 4 of this provider''s published API definitions: openapi_openapi_catalog_admin.json, openapi_openapi_commerce.json, kibo-commerce-catalog-admin-openapi.yml, kibo-commerce-commerce-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: Kibo Base URL
  url: '{baseUrl}/api'
  variables:
    baseUrl:
      default: https://t1000000.sb.usc1.gcp.kibocommerce.com
      description: Base URL
security:
- bearerAuth: []
tags:
- name: ReservationRules
paths:
  /commerce/rules/reservation/{code}:
    delete:
      description: Permanently deletes a reservation rule (FR-013 hard delete).
      parameters:
      - in: path
        name: code
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Delete reservation rule
      tags:
      - ReservationRules
      operationId: deleteCommerceRulesReservationByCode
      x-operation-id-source: derived
    get:
      description: Gets a reservation rule by its unique code.
      parameters:
      - in: path
        name: code
        required: true
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRule'
          description: OK
      summary: Get reservation rule by code
      tags:
      - ReservationRules
      operationId: getCommerceRulesReservationByCode
      x-operation-id-source: derived
    put:
      description: Updates an existing reservation rule with full replacement semantics (FR-009).
      parameters:
      - in: path
        name: code
        required: true
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationRule'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRule'
          description: OK
      summary: Update reservation rule
      tags:
      - ReservationRules
      operationId: putCommerceRulesReservationByCode
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/rules/reservation:
    get:
      description: Gets a collection of reservation rules according to any specified filter criteria and sort options.
      parameters:
      - in: query
        name: startIndex
        schema:
          default: 0
          format: int32
          type: integer
      - in: query
        name: pageSize
        schema:
          default: 0
          format: int32
          type: integer
      - in: query
        name: sortBy
        schema:
          type: string
      - in: query
        name: filter
        schema:
          type: string
      - in: query
        name: responseGroups
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRuleCollection'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRuleCollection'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRuleCollection'
          description: OK
      summary: Get reservation rules
      tags:
      - ReservationRules
      operationId: getCommerceRulesReservation
      x-operation-id-source: derived
    post:
      description: Creates a new reservation rule.
      parameters:
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReservationRule'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRule'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRule'
          description: OK
      summary: Create reservation rule
      tags:
      - ReservationRules
      operationId: postCommerceRulesReservation
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/rules/reservation/{code}/rank:
    put:
      description: Updates the rank for a reservation rule and atomically reorders all other rules in the current master catalog.
      parameters:
      - in: path
        name: code
        required: true
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRankRequest'
      responses:
        '200':
          description: OK
      summary: Update reservation rule rank
      tags:
      - ReservationRules
      operationId: putCommerceRulesReservationByCodeRank
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/jobs/reservation-rules/call-offs/{callOffOrderId}/runs:
    get:
      description: 'a given CallOffOrder, most recent first. Drives the order-detail

        "reservation history" panel.'
      parameters:
      - in: path
        name: callOffOrderId
        required: true
        schema:
          type: string
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      - in: query
        name: pageToken
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
          description: OK
      summary: GET /call-offs/{callOffOrderId}/runs — every audit record that touched
      tags:
      - ReservationRules
      operationId: getCommerceJobsReservationRulesCallOffsByCallOffOrderIdRuns
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/jobs/reservation-rules/rules/{ruleId}/recent:
    get:
      description: date range, most recent first. Powers the rule-detail "recent runs" panel.
      parameters:
      - in: path
        name: ruleId
        required: true
        schema:
          type: string
      - in: query
        name: fromUtc
        schema:
          format: date-time
          type: string
      - in: query
        name: toUtc
        schema:
          format: date-time
          type: string
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      - in: query
        name: pageToken
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
          description: OK
      summary: GET /rules/{ruleId}/recent — records for one rule within an optional
      tags:
      - ReservationRules
      operationId: getCommerceJobsReservationRulesRulesByRuleIdRecent
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/jobs/reservation-rules/runs:
    get:
      description: optional date range; most-recent run first.
      parameters:
      - in: query
        name: fromUtc
        schema:
          format: date-time
          type: string
      - in: query
        name: toUtc
        schema:
          format: date-time
          type: string
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      - in: query
        name: pageToken
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRunSummaryCollection'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRunSummaryCollection'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRunSummaryCollection'
          description: OK
      summary: GET /runs — per-run summaries (aggregated counts by outcome) within an
      tags:
      - ReservationRules
      operationId: getCommerceJobsReservationRulesRuns
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/jobs/reservation-rules/runs/{runId}:
    get:
      description: chronological order. Drill-down from the runs list.
      parameters:
      - in: path
        name: runId
        required: true
        schema:
          type: string
      - in: query
        name: pageSize
        schema:
          format: int32
          type: integer
      - in: query
        name: pageToken
        schema:
          type: string
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/json:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
            text/plain:
              schema:
                $ref: '#/components/schemas/ReservationRunHistoryRecordCollection'
          description: OK
      summary: GET /runs/{runId} — every audit record produced by a single run, in
      tags:
      - ReservationRules
      operationId: getCommerceJobsReservationRulesRunsByRunId
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
  /commerce/jobs/reservation-rules/run:
    post:
      description: '{tenantId, siteId}.


        Default behavior (`sync=false`): publishes the same

        `ReservationRuleEngineStart` event the cron scheduler does, returns

        HTTP 202 + JobKey within ~200ms p95 (publish-and-return; no batch work

        in the request thread).

        Debug bypass (`?sync=true`): SKIPS kibo.jobs + RabbitMQ +

        MassTransit consumer entirely. Executes the orchestrator inline on the

        request thread and returns HTTP 200 with the run''s final state +

        elapsed milliseconds. Intended for local repro and integration smoke

        only — the request can hold the thread for the full duration of the

        run. Still subject to the per-{tenantId, siteId} single-writer lease,

        so a concurrent async run will SKIP this one.'
      parameters:
      - in: query
        name: sync
        schema:
          default: false
          type: boolean
      - description: limits which fields are returned in the response body
        in: query
        name: responseFields
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Triggers an on-demand Reservation Rules Engine run for the caller's
      tags:
      - ReservationRules
      operationId: postCommerceJobsReservationRulesRun
      x-operation-id-source: derived
    servers:
    - description: Kibo Base URL
      url: '{baseUrl}/api'
      variables:
        baseUrl:
          default: https://t1000000.sb.usc1.gcp.kibocommerce.com
          description: Base URL
components:
  schemas:
    ProductRuleCode:
      properties:
        code:
          description: Unique identifier of the ProductRule. System-supplied and read-only.
          type:
          - string
          - 'null'
        masterCatalogId:
          description: Master Catalog Id of the ProductRule.
          format: int32
          type: integer
      type: object
    ReservationRule:
      description: Reservation Rule contract (CAT-7686)
      properties:
        auditInfo:
          $ref: '#/components/schemas/AuditInfo'
        callOffOrderRules:
          description: Referenced call-off-order rule codes. Max 1 entry.
          items:
            type: string
          type:
          - array
          - 'null'
        code:
          description: Unique identifier. Auto-generated when omitted on create.
          type:
          - string
          - 'null'
        customerRules:
          description: Referenced customer rule codes. Max 1 entry.
          items:
            type: string
          type:
          - array
          - 'null'
        description:
          description: Optional description, max 500 chars.
          type:
          - string
          - 'null'
        enabled:
          description: Whether the rule is active. Defaults to true on insert.
          type:
          - boolean
          - 'null'
        endDate:
          description: End of the rule's effective window. Null = never expires. Must be >= StartDate when both supplied.
          format: date-time
          type:
          - string
          - 'null'
        isActive:
          description: 'Read-only. Computed server-side: true when the current UTC instant is inside the effective window

            (StartDate null/≤now AND EndDate null/≥now), false otherwise. A rule with no dates is always active.

            This reflects the effective window alone and does not incorporate the enabled flag.'
          type:
          - boolean
          - 'null'
        metaData:
          description: Opaque JSON metadata. Passed through unchanged.
        name:
          description: Display name. Required, max 200 chars.
          type:
          - string
          - 'null'
        productRules:
          description: Referenced product rules. Max 1 entry.
          items:
            $ref: '#/components/schemas/ProductRuleCode'
          type:
          - array
          - 'null'
        rank:
          description: Priority rank, unique per master catalog within the tenant. Auto-assigned when omitted or ≤0.
          format: int32
          type: integer
        sortAttribute:
          description: Optional tiebreaker attribute name used by the reservation engine when two call-off orders match. Max 50 chars.
          type:
          - string
          - 'null'
        startDate:
          description: Start of the rule's effective window. Null = no lower bound (already active).
          format: date-time
          type:
          - string
          - 'null'
        timeFenceDays:
          description: Time fence in days. Inclusive [0, 365].
          format: int32
          type: integer
        validForAllSites:
          description: When true the rule applies to all sites; ValidSites is ignored.
          type:
          - boolean
          - 'null'
        validSites:
          description: Site IDs this rule applies to. Optional — when omitted and ValidForAllSites is not true, the server auto-sets ValidForAllSites=true (FR-022).
          items:
            format: int32
            type: integer
          type:
          - array
          - 'null'
      type: object
    AuditInfo:
      properties:
        createBy:
          type:
          - string
          - 'null'
        createDate:
          format: date-time
          type:
          - string
          - 'null'
        updateBy:
          type:
          - string
          - 'null'
        updateDate:
          format: date-time
          type:
          - string
          - 'null'
      type: object
    ReservationRuleCollection:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ReservationRule'
          type:
          - array
          - 'null'
        pageCount:
          format: int32
          type: integer
        pageSize:
          format: int32
          type: integer
        startIndex:
          format: int32
          type: integer
        totalCount:
          format: int32
          type: integer
      type: object
    UpdateRankRequest:
      description: Represents a request to update the rank of a SafetyStock, PurchaseLimit and Return Rule.
      properties:
        code:
          description: 'Gets or sets the code of the rule to be updated.

            It can be SafetyStock Code , PurchaseLimit Code or Return Rule Code'
          type:
          - string
          - 'null'
        newRank:
          description: Gets or sets the new rank of the rule.
          format: int32
          type: integer
        oldRank:
          description: Gets or sets the old rank of the rule.
          format: int32
          type: integer
      type: object
    ReservationLineOutcome:
      properties:
        itemId:
          description: "The CallOffOrder line — the auto-generated GUID\n            `CallOffOrderItem.Id`, used as the join key into `order.Items[]`."
          type:
          - string
          - 'null'
        lineId:
          description: "The operator-visible line sequence number (1, 2, ...) from\n            `CallOffOrderItem.LineId`."
          format: int32
          type:
          - integer
          - 'null'
        newFillRate:
          format: double
          type: number
        newLineStatus:
          type:
          - string
          - 'null'
        newReservedQty:
          format: int32
          type: integer
        previousReservedQty:
          format: int32
          type: integer
        productCode:
          type:
          - string
          - 'null'
      type: object
    ReservationRunFailureDetail:
      properties:
        errorMessage:
          type:
          - string
          - 'null'
        httpStatus:
          format: int32
          type:
          - integer
          - 'null'
        isTimeout:
          type: boolean
        responseBody:
          type:
          - string
          - 'null'
      type: object
    ReservationRunSummary:
      properties:
        allocatedCount:
          format: int32
          type: integer
        failedCount:
          format: int32
          type: integer
        finishedAt:
          format: date-time
          type: string
        noOpDeltaZeroCount:
          format: int32
          type: integer
        noOpFullyReservedCount:
          format: int32
          type: integer
        runId:
          type:
          - string
          - 'null'
        siteId:
          format: int32
          type: integer
        startedAt:
          format: date-time
          type: string
        tenantId:
          format: int32
          type: integer
        totalCount:
          format: int32
          type: integer
      type: object
    ReservationRunHistoryRecordCollection:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ReservationRunHistoryRecord'
          type:
          - array
          - 'null'
        nextPageToken:
          type:
          - string
          - 'null'
        totalCount:
          format: int32
          type: integer
      type: object
    ReservationRunSummaryCollection:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ReservationRunSummary'
          type:
          - array
          - 'null'
        nextPageToken:
          type:
          - string
          - 'null'
      type: object
    ReservationRunHistoryRecord:
      properties:
        callOffOrderId:
          type:
          - string
          - 'null'
        callOffOrderNumber:
          format: int32
          type:
          - integer
          - 'null'
        failureDetail:
          $ref: '#/components/schemas/ReservationRunFailureDetail'
        finishedAt:
          format: date-time
          type: string
        holderId:
          type:
          - string
          - 'null'
        id:
          type:
          - string
          - 'null'
        lineOutcomes:
          items:
            $ref: '#/components/schemas/ReservationLineOutcome'
          type:
          - array
          - 'null'
        outcome:
          type:
          - string
          - 'null'
        ruleId:
          type:
          - string
          - 'null'
        ruleRank:
          format: int32
          type: integer
        runId:
          type:
          - string
          - 'null'
        siteId:
          format: int32
          type: integer
        startedAt:
          format: date-time
          type: string
        tenantId:
          format: int32
          type: integer
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: JWT Authorization header using the Bearer scheme.
      scheme: bearer
      type: http
x-refined-from:
- openapi_openapi_catalog_admin.json
- openapi_openapi_commerce.json
- kibo-commerce-catalog-admin-openapi.yml
- kibo-commerce-commerce-openapi.yml