{
  "openapi": "3.0.3",
  "info": {
    "title": "BrandGuard Customer Business API",
    "version": "6.0.0-rc.3",
    "description": "Tenant-scoped server-to-server business API, independent of Live NFC verification. Canonical import supports optional durable Idempotency-Key and receipt recovery. Existing identity and production changes require current revisions/reasons and lifecycle permission. Legacy compatible upsert can create LegacySnapshot records; it cannot change passport targets. Unknown request JSON fields are rejected.",
    "x-platform-version": "6.0.0-rc.3"
  },
  "servers": [
    {
      "url": "https://staging-console.brandguard.co/api/customer/v1",
      "description": "Staging"
    }
  ],
  "security": [
    {
      "CustomerBearer": []
    }
  ],
  "paths": {
    "/items": {
      "get": {
        "operationId": "listItems",
        "summary": "List customer items",
        "x-required-scope": "items:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemPageEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/items/{itemId}": {
      "parameters": [
        {
          "name": "itemId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "maxLength": 128
          }
        }
      ],
      "get": {
        "operationId": "getItem",
        "summary": "Read one item",
        "x-required-scope": "items:read",
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ItemEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "operationId": "upsertItem",
        "summary": "Compatible business item update",
        "description": "Legacy compatible upsert, not a physical write. A missing path itemId can create a LegacySnapshot without catalog binding; use canonical import for new product-bound Items. Existing identity/production changes need expectedRevision + reason and lifecycle eligibility. Bound/locked/delivered Items and VariantBound identity remain protected. Passport URL changes are rejected. No external idempotency guarantee: reconcile an unknown write response before resending.",
        "x-required-scope": "items:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemWrite"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpsertResultEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Rejected input; unknown JSON properties produce ASP.NET validation problem. ImportPlanRejected includes row/field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationProblem"
                    }
                  ]
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblem"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/items/import": {
      "post": {
        "operationId": "importCanonicalItems",
        "summary": "Import using existing product and variant identity",
        "description": "Canonical product-bound import; existing productCode + variantSKU required. New Items require factoryIntent; PrepareForFactory requires batch. Maximum 1,000 quantity per row and 10,000 expanded Items. Persist tenant, environment, original key and exact body before a write. Optional Idempotency-Key gives same-tenant canonical-content replay protection; different content returns 409 IdempotencyConflict. Without the header every request may create additional Items. After unknown response, look up the original key and resend only unchanged keyed requests. A missing receipt does not prove no operation is in flight.",
        "x-required-scope": "items:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CanonicalImport"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Rejected input; unknown JSON properties produce ASP.NET validation problem. ImportPlanRejected includes row/field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationProblem"
                    }
                  ]
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblem"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Optional for legacy compatibility; strongly recommended for recoverable writes. Same key/body replays. receiptKey equals this key. Do not create a new key for a retry.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{1,128}$",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ]
      }
    },
    "/items/bulk-upsert": {
      "post": {
        "operationId": "bulkUpsertItems",
        "summary": "Compatible bulk business updates",
        "description": "Maximum 500 legacy compatible upserts; same constraints as PUT, including lifecycle and revision/reason for existing identity/production changes. Rejected batch rolls back. No external idempotency guarantee; reconcile unknown responses before resending.",
        "x-required-scope": "items:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkUpsert"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkResultEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Rejected input; unknown JSON properties produce ASP.NET validation problem. ImportPlanRejected includes row/field errors.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "$ref": "#/components/schemas/ValidationProblem"
                    }
                  ]
                }
              },
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationProblem"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/scans": {
      "get": {
        "operationId": "listScans",
        "summary": "List historical scan records",
        "description": "Includes legacy scans and terminal verification API operations once per logical request. Pending operations and HTTP diagnostics are excluded. source is legacy or customer_api; verificationOperationId identifies API decisions. scanId is null when no accepted ScanRecord exists; counter is null when not authenticated. Unknown tags have no UID or item. History and counts cannot establish verification for the current website visit.",
        "x-required-scope": "scans:read",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            }
          },
          {
            "name": "itemId",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanPageEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Request rejected; inspect message and optional reasonCode.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/items/imports/{receiptKey}": {
      "get": {
        "operationId": "getImportReceipt",
        "summary": "Read a committed import receipt in the current tenant",
        "x-required-scope": "items:read",
        "description": "Permanent receipt lookup, including with a replacement same-tenant token. 404 ImportReceiptNotFound means no committed receipt found now. A keyed original request may be resubmitted unchanged, including when another copy is still in flight. An unkeyed receipt can be read only if its generated receiptKey was received.",
        "parameters": [
          {
            "name": "receiptKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{1,128}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted request; success=true and data.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImportReceiptEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "InvalidReceiptKey",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing items:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "ImportReceiptNotFound",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Receipt authority unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "CustomerBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Customer API Token. Store server-side; select items:read, items:write, and/or scans:read. Raw token shown once. Expiry and revocation checked for every authenticated call."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "message": {
            "type": "string"
          },
          "reasonCode": {
            "type": "string",
            "nullable": true
          },
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ImportIssue"
            }
          }
        }
      },
      "Envelope": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "ItemWrite": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "expectedRevision": {
            "type": "integer",
            "nullable": true,
            "minimum": 1
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "productName": {
            "type": "string",
            "nullable": true,
            "maxLength": 200
          },
          "sku": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "style": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "color": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "size": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "batch": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "bagId": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "packGroup": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "productionRole": {
            "type": "string",
            "nullable": true,
            "maxLength": 40
          },
          "packSequence": {
            "type": "integer",
            "nullable": true,
            "minimum": 0
          },
          "tagType": {
            "type": "string",
            "nullable": true,
            "maxLength": 100
          },
          "notes": {
            "type": "string",
            "nullable": true,
            "maxLength": 500
          }
        }
      },
      "BulkUpsert": {
        "type": "object",
        "required": [
          "items"
        ],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "itemId"
              ],
              "properties": {
                "itemId": {
                  "type": "string",
                  "maxLength": 128
                },
                "expectedRevision": {
                  "type": "integer",
                  "nullable": true,
                  "minimum": 1
                },
                "reason": {
                  "type": "string",
                  "nullable": true
                },
                "productName": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 200
                },
                "sku": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "style": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "color": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "size": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "batch": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "bagId": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "packGroup": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "productionRole": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 40
                },
                "packSequence": {
                  "type": "integer",
                  "nullable": true,
                  "minimum": 0
                },
                "tagType": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "notes": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 500
                }
              }
            }
          }
        },
        "additionalProperties": false
      },
      "CanonicalImport": {
        "type": "object",
        "required": [
          "rows"
        ],
        "properties": {
          "rows": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "productCode",
                "variantSKU"
              ],
              "properties": {
                "productCode": {
                  "type": "string",
                  "maxLength": 100
                },
                "variantSKU": {
                  "type": "string",
                  "maxLength": 100
                },
                "itemId": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 128
                },
                "quantity": {
                  "type": "integer",
                  "minimum": 1,
                  "nullable": true,
                  "maximum": 1000,
                  "default": 1
                },
                "factoryIntent": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "NonFactory",
                    "PrepareForFactory"
                  ],
                  "description": "Required when creating an Item. NonFactory forbids batch/productionRole. PrepareForFactory requires batch."
                },
                "batch": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "passportMode": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "Inherited",
                    "Hosted",
                    "FixedUrl",
                    "DynamicTemplate",
                    "PassportOptOut"
                  ],
                  "description": "Omitting route fields inherits the configured route for a new Item and preserves the route of an existing Item."
                },
                "passportUrl": {
                  "type": "string",
                  "nullable": true
                },
                "passportUrlTemplate": {
                  "type": "string",
                  "nullable": true
                },
                "passportOptOut": {
                  "type": "boolean",
                  "nullable": true
                },
                "changeReason": {
                  "type": "string",
                  "nullable": true,
                  "description": "Required for applicable existing Item changes and explicit PassportOptOut."
                },
                "expectedMutationRevision": {
                  "type": "integer",
                  "minimum": 1,
                  "nullable": true,
                  "description": "Required exact mutationRevision for existing Item production changes."
                },
                "expectedRouteRevision": {
                  "type": "integer",
                  "minimum": 1,
                  "nullable": true,
                  "description": "Required exact route revision for eligible existing Item route changes; lifecycle locks still apply."
                },
                "bagId": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "packGroup": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "productionRole": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "Production",
                    "Buffer"
                  ]
                },
                "packSequence": {
                  "type": "integer",
                  "minimum": 0,
                  "nullable": true
                },
                "tagType": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 100
                },
                "notes": {
                  "type": "string",
                  "nullable": true,
                  "maxLength": 1000
                }
              }
            },
            "maxItems": 10000,
            "description": "At most 10,000 rows and 10,000 expanded items. New items require factoryIntent; it may be omitted for an existing Item update. Explicit itemId requires quantity=1."
          }
        },
        "additionalProperties": false
      },
      "Item": {
        "type": "object",
        "properties": {
          "productName": {
            "type": "string",
            "nullable": true
          },
          "sku": {
            "type": "string",
            "nullable": true
          },
          "style": {
            "type": "string",
            "nullable": true
          },
          "color": {
            "type": "string",
            "nullable": true
          },
          "size": {
            "type": "string",
            "nullable": true
          },
          "batch": {
            "type": "string",
            "nullable": true
          },
          "bagId": {
            "type": "string",
            "nullable": true
          },
          "packGroup": {
            "type": "string",
            "nullable": true
          },
          "productionRole": {
            "type": "string",
            "nullable": true
          },
          "tagType": {
            "type": "string",
            "nullable": true
          },
          "passportUrl": {
            "type": "string",
            "nullable": true
          },
          "passportUrlTemplate": {
            "type": "string",
            "nullable": true
          },
          "notes": {
            "type": "string",
            "nullable": true
          },
          "productCode": {
            "type": "string",
            "nullable": true
          },
          "variantSKU": {
            "type": "string",
            "nullable": true
          },
          "customerReference": {
            "type": "string",
            "nullable": true
          },
          "encodingConfigurationId": {
            "type": "string",
            "nullable": true
          },
          "uid": {
            "type": "string",
            "nullable": true
          },
          "tagStatus": {
            "type": "string",
            "nullable": true
          },
          "productId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "productVariantId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "packSequence": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "customerItemId": {
            "type": "integer",
            "format": "int64"
          },
          "mutationRevision": {
            "type": "integer",
            "format": "int64"
          },
          "routeRevision": {
            "type": "integer",
            "format": "int64"
          },
          "scanCount": {
            "type": "integer",
            "format": "int64",
            "description": "Historical verification activity count, which may include rejected requests; not the consumer accepted counter."
          },
          "itemId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "catalogBindingState": {
            "type": "string"
          },
          "importedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "boundAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        },
        "required": [
          "customerItemId",
          "itemId",
          "status",
          "mutationRevision",
          "routeRevision",
          "catalogBindingState"
        ]
      },
      "ItemEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/Item"
          }
        }
      },
      "Scan": {
        "type": "object",
        "properties": {
          "verificationOperationId": {
            "type": "string",
            "nullable": true
          },
          "source": {
            "type": "string",
            "nullable": true
          },
          "itemId": {
            "type": "string",
            "nullable": true
          },
          "uid": {
            "type": "string",
            "nullable": true
          },
          "failureReason": {
            "type": "string",
            "nullable": true
          },
          "location": {
            "type": "string",
            "nullable": true
          },
          "scanId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "counter": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "result": {
            "type": "string",
            "enum": [
              "Pass",
              "Fail"
            ]
          },
          "scannedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ItemPage": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "format": "int64"
          },
          "pageSize": {
            "type": "integer",
            "format": "int64"
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          }
        },
        "required": [
          "page",
          "pageSize",
          "total",
          "items"
        ]
      },
      "ItemPageEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ItemPage"
          }
        }
      },
      "ScanPage": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "format": "int64"
          },
          "pageSize": {
            "type": "integer",
            "format": "int64"
          },
          "total": {
            "type": "integer",
            "format": "int64"
          },
          "scans": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scan"
            }
          }
        },
        "required": [
          "page",
          "pageSize",
          "total",
          "scans"
        ]
      },
      "ScanPageEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ScanPage"
          }
        }
      },
      "ImportReceipt": {
        "type": "object",
        "properties": {
          "receiptKey": {
            "type": "string"
          },
          "idempotencyKey": {
            "type": "string",
            "nullable": true
          },
          "idempotencyGuaranteed": {
            "type": "boolean"
          },
          "created": {
            "type": "integer",
            "format": "int64"
          },
          "updated": {
            "type": "integer",
            "format": "int64"
          },
          "unchanged": {
            "type": "integer",
            "format": "int64"
          },
          "replayed": {
            "type": "boolean"
          },
          "committedAt": {
            "type": "string",
            "format": "date-time"
          },
          "warning": {
            "type": "string",
            "nullable": true
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "rowNumber": {
                  "type": "integer",
                  "minimum": 2
                },
                "customerItemId": {
                  "type": "integer",
                  "format": "int64"
                },
                "itemId": {
                  "type": "string"
                },
                "disposition": {
                  "type": "string",
                  "enum": [
                    "Created",
                    "Updated",
                    "Unchanged"
                  ]
                }
              },
              "required": [
                "rowNumber",
                "customerItemId",
                "itemId",
                "disposition"
              ]
            }
          }
        },
        "required": [
          "receiptKey",
          "idempotencyKey",
          "idempotencyGuaranteed",
          "created",
          "updated",
          "unchanged",
          "replayed",
          "committedAt",
          "items",
          "warning"
        ],
        "description": "Permanent committed receipt. With Idempotency-Key: receiptKey=idempotencyKey and same tenant/canonical body replays. Without the header, a receiptKey is generated but the call is non-idempotent; warning explains duplicate creation risk."
      },
      "ImportReceiptEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/ImportReceipt"
          }
        }
      },
      "ImportIssue": {
        "type": "object",
        "properties": {
          "rowNumber": {
            "type": "integer",
            "format": "int64"
          },
          "field": {
            "type": "string",
            "nullable": true
          },
          "code": {
            "type": "string"
          },
          "messageKey": {
            "type": "string"
          },
          "args": {
            "type": "object",
            "nullable": true,
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "ValidationProblem": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "traceId": {
            "type": "string"
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "UpsertResult": {
        "type": "object",
        "required": [
          "customerItemId",
          "itemId",
          "revision",
          "created"
        ],
        "properties": {
          "customerItemId": {
            "type": "integer"
          },
          "itemId": {
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "created": {
            "type": "boolean"
          }
        }
      },
      "UpsertResultEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/UpsertResult"
          }
        }
      },
      "BulkResult": {
        "type": "object",
        "required": [
          "requested",
          "created",
          "updated",
          "errors"
        ],
        "properties": {
          "requested": {
            "type": "integer"
          },
          "created": {
            "type": "integer"
          },
          "updated": {
            "type": "integer"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Empty on successful atomic upsert."
          }
        }
      },
      "BulkResultEnvelope": {
        "type": "object",
        "required": [
          "success",
          "data"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "data": {
            "$ref": "#/components/schemas/BulkResult"
          }
        }
      }
    }
  }
}
