{ "components": { "schemas": { "AnalyticsCandidatePage": { "properties": { "catalogue_generation": { "type": "string" }, "complete": { "type": "boolean" }, "country_code": { "type": "string" }, "evaluated_at": { "format": "date-time", "type": "string" }, "generation": { "type": "string" }, "items": { "items": { "properties": { "category_tag_codes": { "items": { "type": "string" }, "type": "array" }, "ordering": { "properties": { "name": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "name", "status", "sku_series_code", "updated_at" ], "type": "object" }, "sku_code": { "type": "string" } }, "required": [ "sku_code", "category_tag_codes", "ordering" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "market_code": { "type": "string" }, "next_offset": { "type": "integer" }, "pricing_generation": { "type": "string" }, "total": { "type": "integer" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "generation", "catalogue_generation", "pricing_generation", "market_code", "country_code", "evaluated_at", "total", "next_offset", "complete", "items" ], "type": "object" }, "AnalyticsCandidateQuery": { "additionalProperties": false, "properties": { "barcode": { "type": "string" }, "brand_code": { "type": "string" }, "brand_slug": { "type": "string" }, "category_slug": { "type": "string" }, "category_tag_code": { "type": "string" }, "channel": { "enum": [ "retail", "wholesale", "staff" ], "type": "string" }, "collection_code": { "type": "string" }, "collection_slug": { "type": "string" }, "generation": { "type": "string" }, "has_preorder_policy": { "type": "boolean" }, "lifecycle_tag": { "enum": [ "NEW", "RESTOCKED" ], "type": "string" }, "limit": { "maximum": 1000, "minimum": 1, "type": "integer" }, "market_code": { "type": "string" }, "offset": { "minimum": 0, "type": "integer" }, "on_promotion": { "type": "boolean" }, "preorder_available": { "type": "boolean" }, "search": { "type": "string" }, "sku_codes": { "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, "sku_series_code": { "type": "string" }, "soon_expiry": { "description": "Only products whose retail storefront_display.expiry is present (earliest sellable lot inside the effective soon-expiry lead days of the market listing), whatever their soon-expiry merchandising policy says.", "type": "boolean" }, "soon_expiry_policy_open": { "description": "Only products whose soon-expiry merchandising policy is enabled and inside its starts_at/ends_at window. An explicit policy filter; soon_expiry does not imply it.", "type": "boolean" }, "status": { "enum": [ "active", "draft", "archived", "discontinued" ], "type": "string" }, "storage_type": { "type": "string" }, "supplier_code": { "type": "string" } }, "required": [ "channel", "offset", "limit" ], "type": "object" }, "OpeningReceiptInput": { "additionalProperties": false, "description": "Temporary cutover API. Cost is positive GST-exclusive whole-line cost; AUD 5127 means AUD51.27 for the entire line. Server fixes source and condition. Dates use next midnight after the labelled Melbourne day. Identical authorized retries replay the original receipt before mutable eligibility checks; changed evidence conflicts.", "properties": { "batch_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "handling_unit": { "enum": [ "EACH", "CASE" ], "type": "string" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "net_goods_cost": { "additionalProperties": false, "properties": { "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "net_goods_amount": { "additionalProperties": false, "properties": { "amount_minor": { "format": "int64", "minimum": 1, "type": "integer" }, "currency": { "type": "string" } }, "required": [ "currency", "amount_minor" ], "type": "object" }, "reason": { "enum": [ "opening_balance" ], "type": "string" } }, "required": [ "currency", "currency_exponent", "net_goods_amount", "reason" ], "type": "object" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "received_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "source_line_id": { "pattern": "^opening-line:v1:[a-f0-9]{64}$", "type": "string" }, "stock_units": { "items": { "additionalProperties": false, "properties": { "clearance_label_code": { "type": "string" }, "evidence_media_urls": { "items": { "type": "string" }, "type": "array" }, "id": { "type": "string" }, "unit_label_code": { "type": "string" } }, "type": "object" }, "type": "array" } }, "required": [ "batch_id", "source_line_id", "idempotency_key", "sku_code", "destination_location", "package_option", "handling_unit", "received_composition", "net_goods_cost" ], "type": "object" }, "audience.Audience": { "additionalProperties": false, "properties": { "customer_type": { "$ref": "#/components/schemas/audience_enums.CustomerType" }, "platform": { "$ref": "#/components/schemas/audience_enums.Platform" } }, "required": [], "type": "object" }, "audience_enums.CustomerType": { "enum": [ "guest", "retail", "wholesale" ], "type": "string" }, "audience_enums.Platform": { "enum": [ "web", "mobile" ], "type": "string" }, "audit.LifecycleAction": { "properties": { "at": { "type": "string" }, "by": { "type": "string" }, "reason": { "type": "string" } }, "type": "object" }, "benefit.BenefitRef": { "properties": { "code": { "type": "string" }, "kind": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "bulk.ActivePatch": { "additionalProperties": false, "properties": { "is_active": { "type": "boolean" } }, "required": [ "is_active" ], "type": "object" }, "campaign.Campaign": { "additionalProperties": false, "properties": { "archived_at": { "format": "date-time", "type": "string" }, "audience": { "items": { "$ref": "#/components/schemas/campaign_enums.CampaignCustomerType" }, "type": "array" }, "campaign_code": { "type": "string" }, "country_code": { "$ref": "#/components/schemas/geography.CountryCode" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "currency_code": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array" }, "effective_status": { "type": "string" }, "ends_at": { "format": "date-time", "type": "string" }, "geographic_scope": { "$ref": "#/components/schemas/geography.GeographicScope" }, "id": { "type": "string" }, "market_code": { "type": "string" }, "media": { "$ref": "#/components/schemas/security.ObjectMedia" }, "offers": { "items": { "$ref": "#/components/schemas/campaign.OfferLink" }, "type": "array" }, "paused_at": { "format": "date-time", "type": "string" }, "placements": { "items": { "$ref": "#/components/schemas/campaign.Placement" }, "type": "array" }, "publication_revision": { "type": "integer" }, "publication_status": { "$ref": "#/components/schemas/campaign_enums.CampaignStatus" }, "published": { "type": "boolean" }, "published_at": { "format": "date-time", "type": "string" }, "revision": { "type": "integer" }, "schedule_timezone": { "type": "string" }, "starts_at": { "format": "date-time", "type": "string" }, "targets": { "$ref": "#/components/schemas/campaign.CampaignTarget" }, "title": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "campaign_code", "placements", "offers", "published", "audience", "publication_status", "effective_status", "revision", "publication_revision", "created_at", "updated_at" ], "type": "object" }, "campaign.CampaignCategoryTarget": { "additionalProperties": false, "properties": { "category_tag_code": { "type": "string" }, "collection_code": { "type": "string" } }, "required": [ "collection_code", "category_tag_code" ], "type": "object" }, "campaign.CampaignTarget": { "additionalProperties": false, "properties": { "categories": { "items": { "$ref": "#/components/schemas/campaign.CampaignCategoryTarget" }, "type": "array" }, "sku_codes": { "items": { "type": "string" }, "type": "array" } }, "required": [], "type": "object" }, "campaign.OfferLink": { "additionalProperties": false, "properties": { "display_order": { "type": "integer" }, "id": { "type": "string" }, "kind": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "kind", "id", "display_order" ], "type": "object" }, "campaign.Placement": { "additionalProperties": false, "properties": { "media": { "$ref": "#/components/schemas/security.ObjectMedia" }, "platforms": { "items": { "$ref": "#/components/schemas/campaign_enums.CampaignPlatform" }, "type": "array" }, "position": { "$ref": "#/components/schemas/campaign_enums.CampaignPlacement" }, "priority": { "type": "integer" } }, "required": [ "position", "platforms", "priority" ], "type": "object" }, "campaign_enums.CampaignCustomerType": { "enum": [ "retail", "wholesale" ], "type": "string" }, "campaign_enums.CampaignPlacement": { "enum": [ "announcement_bar", "home_banner", "account_banner", "home_modal" ], "type": "string" }, "campaign_enums.CampaignPlatform": { "enum": [ "web", "mobile" ], "type": "string" }, "campaign_enums.CampaignStatus": { "enum": [ "draft", "published", "paused", "archived" ], "type": "string" }, "catalog.BulkPreorderPolicy": { "additionalProperties": false, "description": "Replaces operational preorder fields. Omitted labels/descriptions preserve each selected product's own localized content; explicit arrays replace and [] or null clear those fields. Omitted enabled is false; omitted dates/limits are unset/zero. Uses existing single-product policy validation.", "properties": { "descriptions": { "anyOf": [ { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, { "type": "null" } ] }, "enabled": { "type": "boolean" }, "ends_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "expected_available_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] }, "labels": { "anyOf": [ { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, { "type": "null" } ] }, "max_quantity_per_customer": { "minimum": 0, "type": "integer" }, "max_quantity_per_order": { "minimum": 0, "type": "integer" }, "schedule_timezone": { "minLength": 1, "type": "string" }, "starts_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ] } }, "required": [ "schedule_timezone" ], "type": "object" }, "catalog.BulkPreorderPolicyRequest": { "additionalProperties": false, "properties": { "policy": { "anyOf": [ { "$ref": "#/components/schemas/catalog.BulkPreorderPolicy" }, { "type": "null" } ], "description": "Required. An object sets policy; explicit null clears preorder only." }, "sku_codes": { "description": "Trimmed, case-sensitive SKU business keys; 1-100 unique entries after trimming, maximum 128 UTF-8 bytes per code, no control characters. No all-products selector.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "sku_codes", "policy" ], "type": "object" }, "catalog.BulkPreorderPolicyResult": { "additionalProperties": false, "properties": { "sku_codes": { "description": "Trimmed, case-sensitive SKU business keys; 1-100 unique entries after trimming, maximum 128 UTF-8 bytes per code, no control characters. No all-products selector.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Number of selected products, including products whose business policy already matched.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "sku_codes", "updated_count" ], "type": "object" }, "catalog.BulkProductPatch": { "additionalProperties": false, "description": "Append tag codes as a set union after existing tags; never replace existing tags. Each selected product must satisfy current collection, brand and status validation for status/category changes. Lifecycle suppression flags are independent, persisted until explicitly restored, and share the individual lifecycle override mutation's guards and actor/history. Restoration does not restart a 14-day window or change listing/restock timestamps. Null fields and an empty patch are invalid.", "minProperties": 1, "properties": { "append_category_tag_codes": { "items": { "pattern": "^TAG[0-9]{4}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "new_suppressed": { "description": "Suppress automatic NEW across all markets when true; false restores evaluation against existing listing dates. Omission preserves the current override.", "type": "boolean" }, "restocked_suppressed": { "description": "Suppress automatic RESTOCKED when true; false restores evaluation against the existing restock timestamp. Omission preserves the current override.", "type": "boolean" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" } }, "type": "object" }, "catalog.BulkProductRequest": { "additionalProperties": false, "properties": { "patch": { "$ref": "#/components/schemas/catalog.BulkProductPatch" }, "sku_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed, case-sensitive code; at most 128 UTF-8 bytes and no control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "sku_codes", "patch" ], "type": "object" }, "catalog.BulkProductResult": { "additionalProperties": false, "properties": { "sku_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed, case-sensitive code; at most 128 UTF-8 bytes and no control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "sku_codes", "updated_count" ], "type": "object" }, "classification.Brand": { "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "id": { "type": "string" }, "logo": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "classification.BrandRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.CategoryTag": { "properties": { "code": { "type": "string" }, "collection_code": { "type": "string" }, "collection_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "display_order": { "description": "Position inside the tag's collection, 0-based (Supply-owned; set by PUT /collections/{slug}/category-tags/order). Tags of one collection are ordered by display_order, then name, then code. Present on category tag and collection endpoints; absent on product detail projections.", "minimum": 0, "type": "integer" }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "classification.CategoryTagRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.Collection": { "properties": { "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTag" }, "type": "array", "uniqueItems": false }, "code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "display_order": { "description": "Position among all collections, 0-based (Supply-owned; set by PUT /collections/order). Lists are ordered by display_order, then name, then code; equal positions are possible after deletes and are broken by name. Present on collection endpoints; absent on product detail projections.", "minimum": 0, "type": "integer" }, "icon": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "classification.CollectionRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.CountryCodeRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.ObjectMediaRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.ProductManufacturing": { "properties": { "company_name": { "type": "string" }, "country_ref": { "$ref": "#/components/schemas/classification.CountryCodeRef" } }, "type": "object" }, "classification.ProductSupplierRef": { "properties": { "code": { "type": "string" } }, "type": "object" }, "classification.ProductSupply": { "properties": { "manufacturing": { "$ref": "#/components/schemas/classification.ProductManufacturing" }, "suppliers": { "items": { "$ref": "#/components/schemas/classification.ProductSupplierRef" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "classification.SKUSeries": { "properties": { "code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "id": { "type": "string" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "primary_name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "classification.Supplier": { "properties": { "abn": { "description": "Registration and tax details.", "type": "string" }, "acn": { "type": "string" }, "available_market_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "available_products": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailableProduct" }, "type": "array", "uniqueItems": false }, "available_promotions": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailablePromotion" }, "type": "array", "uniqueItems": false }, "billing_address": { "$ref": "#/components/schemas/party.ContactAddress" }, "brand_name": { "type": "string" }, "business_number_label": { "type": "string" }, "code": { "description": "Code is the organisation / supplier business key (supplier_code /\norganisation_code) used as the canonical cross-struct reference. It is\nempty for person-like parties (e.g. an order customer) that have no\norganisation code.", "type": "string" }, "contact_person": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "currency_code": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "description": { "type": "string" }, "email": { "type": "string" }, "geographic_location": { "$ref": "#/components/schemas/geography.Address" }, "id": { "type": "string" }, "industry": { "description": "Additional business metadata.", "type": "string" }, "legal_name": { "type": "string" }, "logo": { "$ref": "#/components/schemas/security.ObjectMedia" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "name": { "type": "string" }, "phone": { "type": "string" }, "registered_address": { "$ref": "#/components/schemas/party.ContactAddress" }, "shipping_address": { "$ref": "#/components/schemas/party.ContactAddress" }, "tax_registered": { "type": "boolean" }, "tax_registration_id": { "type": "string" }, "timezone": { "type": "string" }, "trading_name": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "website": { "description": "Additional contact details (primary phone/email come from PartyRef).", "type": "string" } }, "type": "object" }, "classification.SupplierAvailableProduct": { "properties": { "manufacturing": { "$ref": "#/components/schemas/classification.ProductManufacturing" }, "minimum_purchase_quantity": { "type": "integer" }, "offered_price": { "$ref": "#/components/schemas/money.Money" }, "product_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" }, "supplier_sku_code": { "type": "string" } }, "type": "object" }, "classification.SupplierAvailablePromotion": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "classification_enums.StorageType": { "enum": [ "AMBIENT", "CHILLED", "FROZEN" ], "type": "string", "x-enum-varnames": [ "StorageAmbient", "StorageChilled", "StorageFrozen" ] }, "commerce_enums.OrderType": { "enum": [ "online", "pos", "b2b", "relay", "manual", "import" ], "type": "string", "x-enum-varnames": [ "OrderTypeOnline", "OrderTypePOS", "OrderTypeB2B", "OrderTypeRelay", "OrderTypeManual", "OrderTypeImport" ] }, "compliance.ArtifactReference": { "properties": { "checksum_sha256": { "type": "string" }, "filename": { "type": "string" }, "generated_at": { "type": "string" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/compliance_enums.ArtifactKind" }, "media_code": { "type": "string" }, "mime_type": { "type": "string" }, "revision_number": { "type": "integer" } }, "type": "object" }, "compliance.CatalogueReference": { "properties": { "effective_from": { "type": "string" }, "entry_id": { "type": "string" }, "id": { "type": "string" }, "jurisdiction": { "$ref": "#/components/schemas/compliance_enums.Jurisdiction" }, "retrieved_at": { "type": "string" }, "source_checksum_sha256": { "type": "string" }, "source_url": { "type": "string" }, "version": { "type": "string" } }, "type": "object" }, "compliance.DeclarationLine": { "properties": { "carton_count": { "type": "integer" }, "chinese_name": { "type": "string" }, "english_name": { "type": "string" }, "expiry_date": { "type": "string" }, "id": { "type": "string" }, "ingredients": { "type": "string" }, "manufacturing_process": { "type": "string" }, "note": { "type": "string" }, "ordered_quantity": { "type": "integer" }, "single_net_weight_grams": { "type": "integer" }, "sku_code": { "type": "string" }, "source_label_id": { "type": "string" }, "source_label_revision_number": { "type": "integer" }, "source_line_id": { "type": "string" }, "total_gross_weight_grams": { "type": "integer" }, "total_net_weight_grams": { "type": "integer" } }, "type": "object" }, "compliance.DeclarationShipment": { "properties": { "consignment_identifier": { "type": "string" }, "declaration_date": { "type": "string" }, "destination_port": { "type": "string" }, "import_mode": { "$ref": "#/components/schemas/compliance_enums.ImportMode" }, "port_of_loading": { "type": "string" }, "shipping_method": { "type": "string" }, "transport_reference": { "type": "string" } }, "type": "object" }, "compliance.DeclarationSignatory": { "properties": { "name": { "type": "string" }, "signature_media_code": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "compliance.EvidenceReference": { "properties": { "captured_at": { "type": "string" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/compliance_enums.EvidenceKind" }, "media_code": { "type": "string" }, "note": { "type": "string" }, "source_checksum_sha256": { "type": "string" }, "source_title": { "type": "string" }, "source_url": { "type": "string" }, "source_version": { "type": "string" } }, "type": "object" }, "compliance.LabelImporter": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "compliance.LabelLayout": { "properties": { "font_scale_basis_points": { "type": "integer" }, "include_barcode": { "type": "boolean" }, "orientation": { "$ref": "#/components/schemas/compliance_enums.LabelOrientation" }, "size": { "$ref": "#/components/schemas/compliance_enums.LabelSize" } }, "type": "object" }, "compliance.LabelMaster": { "properties": { "allergens": { "type": "string" }, "artifacts": { "items": { "$ref": "#/components/schemas/compliance.ArtifactReference" }, "type": "array", "uniqueItems": false }, "barcode": { "type": "string" }, "best_before": { "type": "string" }, "brand": { "type": "string" }, "chinese_name": { "type": "string" }, "country_code": { "type": "string" }, "country_of_origin": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "english_name": { "type": "string" }, "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "importer": { "$ref": "#/components/schemas/compliance.LabelImporter" }, "ingredients": { "type": "string" }, "layout": { "$ref": "#/components/schemas/compliance.LabelLayout" }, "manufacturing_process": { "type": "string" }, "market_code": { "description": "MarketCode and CountryCode are the denormalized market and country the\nrecord belongs to, carried so a geographically scoped staff query is\na plain indexed match.", "type": "string" }, "net_weight_grams": { "type": "integer" }, "nutrition_panels": { "items": { "$ref": "#/components/schemas/compliance.NutritionPanel" }, "type": "array", "uniqueItems": false }, "package_dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "package_photo_media_code": { "type": "string" }, "package_photo_name": { "type": "string" }, "revision": { "$ref": "#/components/schemas/compliance.RevisionMetadata" }, "second_nutrition_enabled": { "type": "boolean" }, "shelf_life": { "type": "string" }, "sku_code": { "type": "string" }, "source_product_evidence": { "$ref": "#/components/schemas/compliance.LabelProductEvidence" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "variant_code": { "type": "string" } }, "type": "object" }, "compliance.LabelProductEvidence": { "properties": { "alternate_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "barcode": { "type": "string" }, "brand": { "type": "string" }, "captured_at": { "type": "string" }, "chinese_name": { "type": "string" }, "english_name": { "type": "string" }, "market_code": { "description": "MarketCode and TaxCategoryCode replace the retired product-level Taxed\nflag: taxability is a market-listing fact, so compliance\nfreezes the market and its Pricing-owned tax category instead.", "type": "string" }, "sku_code": { "type": "string" }, "source_checksum_sha256": { "type": "string" }, "tax_category_code": { "type": "string" } }, "type": "object" }, "compliance.ManufacturerDetails": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "compliance.NutritionPanel": { "properties": { "carbohydrate_per_100_grams": { "type": "string" }, "carbohydrate_per_serve": { "type": "string" }, "energy_per_100_grams": { "type": "string" }, "energy_per_serve": { "type": "string" }, "fat_per_100_grams": { "type": "string" }, "fat_per_serve": { "type": "string" }, "protein_per_100_grams": { "type": "string" }, "protein_per_serve": { "type": "string" }, "saturated_fat_per_100_grams": { "type": "string" }, "saturated_fat_per_serve": { "type": "string" }, "serving_size": { "type": "string" }, "servings_per_pack": { "type": "string" }, "sodium_per_100_grams": { "type": "string" }, "sodium_per_serve": { "type": "string" }, "sugars_per_100_grams": { "type": "string" }, "sugars_per_serve": { "type": "string" }, "title": { "type": "string" } }, "type": "object" }, "compliance.PurchaseOrderSnapshot": { "properties": { "captured_at": { "type": "string" }, "expected_arrival": { "type": "string" }, "id": { "type": "string" }, "order_number": { "type": "string" }, "source_checksum_sha256": { "type": "string" }, "status": { "$ref": "#/components/schemas/purchase_enums.PurchaseOrderStatus" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" } }, "type": "object" }, "compliance.RFIBookingAgent": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "compliance.RFIExternalEvent": { "properties": { "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "external_reference": { "type": "string" }, "id": { "type": "string" }, "note": { "type": "string" }, "occurred_at": { "type": "string" }, "recorded_by": { "type": "string" }, "state": { "$ref": "#/components/schemas/compliance_enums.RFISubmissionState" } }, "type": "object" }, "compliance.RFIInspectionLocation": { "properties": { "business_name_and_aa_number": { "type": "string" }, "contact_name": { "type": "string" }, "contact_phone": { "type": "string" }, "opening_hours": { "type": "string" }, "premise_address": { "$ref": "#/components/schemas/geography.Address" }, "private_residence": { "type": "boolean" } }, "type": "object" }, "compliance.RFIRecord": { "properties": { "airway_bill": { "type": "string" }, "artifacts": { "items": { "$ref": "#/components/schemas/compliance.ArtifactReference" }, "type": "array", "uniqueItems": false }, "attachment_media_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "available_from": { "type": "string" }, "booking_agent": { "$ref": "#/components/schemas/compliance.RFIBookingAgent" }, "channel": { "$ref": "#/components/schemas/compliance_enums.RFIChannel" }, "comments": { "type": "string" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "current_submission_state": { "$ref": "#/components/schemas/compliance_enums.RFISubmissionState" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "email_body": { "type": "string" }, "email_subject_prefix": { "type": "string" }, "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "inspection_direction": { "type": "string" }, "inspection_location": { "$ref": "#/components/schemas/compliance.RFIInspectionLocation" }, "market_code": { "description": "MarketCode and CountryCode are the denormalized market and country the\nrecord belongs to, carried so a geographically scoped staff query is\na plain indexed match.", "type": "string" }, "overtime": { "type": "boolean" }, "quarantine_number": { "type": "string" }, "requested_date": { "type": "string" }, "requested_time": { "$ref": "#/components/schemas/compliance_enums.RFIRequestedTime" }, "revision": { "$ref": "#/components/schemas/compliance.RevisionMetadata" }, "submission_events": { "items": { "$ref": "#/components/schemas/compliance.RFIExternalEvent" }, "type": "array", "uniqueItems": false }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "compliance.RateValue": { "properties": { "basis_points": { "type": "integer" }, "raw": { "type": "string" } }, "type": "object" }, "compliance.RevisionMetadata": { "properties": { "approved": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "archived": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "base_revision_number": { "type": "integer" }, "number": { "type": "integer" }, "rejected": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "state": { "$ref": "#/components/schemas/compliance_enums.ReviewState" }, "submitted": { "$ref": "#/components/schemas/audit.LifecycleAction" } }, "type": "object" }, "compliance.TariffAssessment": { "properties": { "artifacts": { "items": { "$ref": "#/components/schemas/compliance.ArtifactReference" }, "type": "array", "uniqueItems": false }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "purchase_order": { "$ref": "#/components/schemas/compliance.PurchaseOrderSnapshot" }, "revision": { "$ref": "#/components/schemas/compliance.RevisionMetadata" }, "rows": { "items": { "$ref": "#/components/schemas/compliance.TariffAssessmentRow" }, "type": "array", "uniqueItems": false }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "compliance.TariffAssessmentRow": { "properties": { "australia": { "$ref": "#/components/schemas/compliance.TariffClassification" }, "id": { "type": "string" }, "notes": { "type": "string" }, "product": { "$ref": "#/components/schemas/compliance.TariffLineSnapshot" }, "published_profile_revision": { "type": "integer" }, "source": { "type": "string" }, "taiwan": { "$ref": "#/components/schemas/compliance.TariffClassification" }, "trademark": { "type": "string" }, "trademark_evidence_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "compliance.TariffClassification": { "properties": { "catalogue": { "$ref": "#/components/schemas/compliance.CatalogueReference" }, "code": { "type": "string" }, "duty_rate": { "$ref": "#/components/schemas/compliance.RateValue" }, "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "gst_rate": { "$ref": "#/components/schemas/compliance.RateValue" }, "jurisdiction": { "$ref": "#/components/schemas/compliance_enums.Jurisdiction" } }, "type": "object" }, "compliance.TariffLineSnapshot": { "properties": { "alternate_names": { "type": "string" }, "barcode": { "type": "string" }, "brand": { "type": "string" }, "id": { "type": "string" }, "ordered_quantity": { "type": "integer" }, "product_name": { "type": "string" }, "product_taxed": { "type": "boolean" }, "purchase_order_line_id": { "type": "string" }, "sku_code": { "type": "string" } }, "type": "object" }, "compliance_enums.ArtifactKind": { "enum": [ "pdf", "docx", "xlsx", "zip", "eml" ], "type": "string", "x-enum-varnames": [ "ArtifactKindPDF", "ArtifactKindDOCX", "ArtifactKindXLSX", "ArtifactKindZIP", "ArtifactKindEML" ] }, "compliance_enums.EvidenceKind": { "enum": [ "media", "official_source", "internal_record", "manual_citation", "automation_proposal" ], "type": "string", "x-enum-varnames": [ "EvidenceKindMedia", "EvidenceKindOfficialSource", "EvidenceKindInternalRecord", "EvidenceKindManualCitation", "EvidenceKindAutomationProposal" ] }, "compliance_enums.ImportMode": { "enum": [ "air_cargo", "sea_ambient", "sea_frozen" ], "type": "string", "x-enum-varnames": [ "ImportModeAirCargo", "ImportModeSeaAmbient", "ImportModeSeaFrozen" ] }, "compliance_enums.Jurisdiction": { "enum": [ "AU", "TW" ], "type": "string", "x-enum-varnames": [ "JurisdictionAustralia", "JurisdictionTaiwan" ] }, "compliance_enums.LabelOrientation": { "enum": [ "portrait", "landscape" ], "type": "string", "x-enum-varnames": [ "LabelOrientationPortrait", "LabelOrientationLandscape" ] }, "compliance_enums.LabelSize": { "enum": [ "100x60", "100x80", "80x50", "65x45", "60x40", "50x30" ], "type": "string", "x-enum-varnames": [ "LabelSize100x60", "LabelSize100x80", "LabelSize80x50", "LabelSize65x45", "LabelSize60x40", "LabelSize50x30" ] }, "compliance_enums.RFIChannel": { "enum": [ "biosecurity_portal", "email_exception" ], "type": "string", "x-enum-varnames": [ "RFIChannelBiosecurityPortal", "RFIChannelEmailException" ] }, "compliance_enums.RFIRequestedTime": { "enum": [ "anytime", "am", "pm" ], "type": "string", "x-enum-varnames": [ "RFIRequestedTimeAnytime", "RFIRequestedTimeAM", "RFIRequestedTimePM" ] }, "compliance_enums.RFISubmissionState": { "enum": [ "not_submitted", "submitted", "confirmed", "rescheduled", "cancelled", "closed" ], "type": "string", "x-enum-varnames": [ "RFISubmissionStateNotSubmitted", "RFISubmissionStateSubmitted", "RFISubmissionStateConfirmed", "RFISubmissionStateRescheduled", "RFISubmissionStateCancelled", "RFISubmissionStateClosed" ] }, "compliance_enums.ReviewState": { "enum": [ "draft", "in_review", "approved", "rejected", "archived" ], "type": "string", "x-enum-varnames": [ "ReviewStateDraft", "ReviewStateInReview", "ReviewStateApproved", "ReviewStateRejected", "ReviewStateArchived" ] }, "courier.CarrierBookingAttempt": { "properties": { "attempted_at": { "format": "date-time", "type": "string" }, "attempted_by": { "type": "string" }, "carrier_reference": { "type": "string" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "delivery_company": { "$ref": "#/components/schemas/courier.DeliveryCompanyRef" }, "edits": { "$ref": "#/components/schemas/courier.CarrierBookingEdits" }, "error_code": { "$ref": "#/components/schemas/courier_enums.CarrierBookingErrorCode" }, "error_fields": { "description": "Booking input names the carrier rejected; unmapped carrier fields are \"other\".", "items": { "type": "string" }, "type": "array" }, "error_message": { "type": "string" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "order_number": { "type": "string" }, "outcome": { "$ref": "#/components/schemas/courier_enums.CarrierBookingOutcome" }, "override_reason": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "request_summary": { "items": { "$ref": "#/components/schemas/courier.CarrierBookingRequestSummaryEntry" }, "type": "array" }, "resolved_at": { "format": "date-time", "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "sandbox": { "type": "boolean" }, "shipment_ids": { "items": { "type": "string" }, "type": "array" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "order_number", "shipment_ids", "delivery_company", "outcome", "sandbox", "attempted_by", "attempted_at" ], "type": "object" }, "courier.CarrierBookingEdits": { "additionalProperties": false, "description": "Values staff changed for one attempt. An absent field was not edited; an empty instructions or delivery_type clears it. intake_date overrides production_date. Edits never rewrite the accepted delivery selection; edited instructions also replace the shipments' note.", "properties": { "box_count": { "maximum": 99, "minimum": 1, "type": "integer" }, "delivery_date": { "format": "date", "type": "string" }, "delivery_type": { "maxLength": 128, "type": "string" }, "instructions": { "maxLength": 1024, "type": "string" }, "intake_date": { "format": "date", "type": "string" }, "time_window": { "$ref": "#/components/schemas/courier.CarrierBookingTimeWindow" } }, "type": "object" }, "courier.CarrierBookingRequestSummaryEntry": { "additionalProperties": false, "properties": { "key": { "type": "string" }, "value": { "description": "Redacted display text; never credentials, sensitive configuration values or contact details.", "type": "string" } }, "required": [ "key", "value" ], "type": "object" }, "courier.CarrierBookingSummary": { "additionalProperties": false, "properties": { "attempt_id": { "type": "string" }, "box_count": { "type": "integer" }, "carrier_reference": { "type": "string" }, "delivery_date": { "description": "Values actually sent to the carrier in this booking, after edits and defaults; absent when not sent.", "format": "date", "type": "string" }, "delivery_type": { "type": "string" }, "instructions": { "type": "string" }, "intake_date": { "format": "date", "type": "string" }, "outcome": { "$ref": "#/components/schemas/courier_enums.CarrierBookingOutcome" }, "outcome_at": { "format": "date-time", "type": "string" }, "time_window": { "$ref": "#/components/schemas/courier.CarrierBookingTimeWindow" } }, "required": [ "attempt_id", "outcome", "outcome_at" ], "type": "object" }, "courier.CarrierBookingTimeWindow": { "additionalProperties": false, "description": "Wall clock in the delivery (recipient's) timezone. Either side may be omitted to keep the value derived from the order.", "properties": { "from_time": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" }, "to_time": { "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$", "type": "string" } }, "type": "object" }, "courier.DeliveryCompanyConfigurationEntry": { "description": "Admin-authored arbitrary JSON value. Sensitive read values are masked; strings have no provider-specific format restrictions.", "properties": { "key": { "maxLength": 256, "minLength": 1, "type": "string" }, "sensitive": { "type": "boolean" }, "value": {} }, "required": [ "key", "value", "sensitive" ], "type": "object" }, "courier.DeliveryCompanyCustomMetadataEntry": { "additionalProperties": false, "description": "Inert non-secret operator metadata. The JSON value must match value_type. Never forwarded as provider runtime configuration.", "properties": { "key": { "maxLength": 64, "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "value": {}, "value_type": { "enum": [ "string", "number", "boolean", "object", "array", "null" ], "type": "string" } }, "required": [ "key", "value_type", "value" ], "type": "object" }, "courier.DeliveryCompanyRef": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "code", "name", "revision" ], "type": "object" }, "courier_enums.CarrierBookingErrorCode": { "enum": [ "invalid_address", "invalid_contact", "duplicate_job", "invalid_date", "invalid_parcel", "auth_failed", "rate_limited", "timeout", "unsupported_area", "carrier_error" ], "type": "string" }, "courier_enums.CarrierBookingOutcome": { "enum": [ "pending", "booked", "already_booked", "rejected", "unreachable" ], "type": "string" }, "data": { "properties": { "data": { "$ref": "#/components/schemas/warehouse.WMSDraft" } }, "type": "object" }, "depots.BulkCoverageRequest": { "additionalProperties": false, "properties": { "ids": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed Mongo ObjectId, returned as lowercase hex.", "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "patch": { "$ref": "#/components/schemas/bulk.ActivePatch" } }, "required": [ "ids", "patch" ], "type": "object" }, "depots.BulkCoverageResult": { "additionalProperties": false, "properties": { "ids": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed Mongo ObjectId, returned as lowercase hex.", "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "ids", "updated_count" ], "type": "object" }, "depots.BulkDepotRequest": { "additionalProperties": false, "properties": { "depot_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "patch": { "$ref": "#/components/schemas/bulk.ActivePatch" } }, "required": [ "depot_codes", "patch" ], "type": "object" }, "depots.BulkDepotResult": { "additionalProperties": false, "properties": { "depot_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "depot_codes", "updated_count" ], "type": "object" }, "depots.BulkLocationKey": { "additionalProperties": false, "properties": { "depot_code": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" }, "location_code": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" } }, "required": [ "depot_code", "location_code" ], "type": "object" }, "depots.BulkLocationPatch": { "additionalProperties": false, "minProperties": 1, "properties": { "is_active": { "type": "boolean" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" } }, "type": "object" }, "depots.BulkLocationRequest": { "additionalProperties": false, "properties": { "locations": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "$ref": "#/components/schemas/depots.BulkLocationKey" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "patch": { "$ref": "#/components/schemas/depots.BulkLocationPatch" } }, "required": [ "locations", "patch" ], "type": "object" }, "depots.BulkLocationResult": { "additionalProperties": false, "properties": { "locations": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "$ref": "#/components/schemas/depots.BulkLocationKey" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "locations", "updated_count" ], "type": "object" }, "depots.BulkRegionRequest": { "additionalProperties": false, "properties": { "patch": { "$ref": "#/components/schemas/bulk.ActivePatch" }, "region_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "region_codes", "patch" ], "type": "object" }, "depots.BulkRegionResult": { "additionalProperties": false, "properties": { "region_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed and normalized to uppercase.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,62}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "region_codes", "updated_count" ], "type": "object" }, "depots.PhysicalReceivingLocationEvidence": { "properties": { "country_code": { "type": "string" }, "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "market_code": { "type": "string" }, "state_code": { "type": "string" } }, "required": [ "market_code", "depot_code", "location_code", "country_code", "state_code" ], "type": "object" }, "depots.PhysicalReceivingLocationQuery": { "additionalProperties": false, "properties": { "depot_code": { "minLength": 1, "type": "string" }, "location_code": { "minLength": 1, "type": "string" }, "market_code": { "minLength": 1, "type": "string" } }, "required": [ "market_code", "depot_code", "location_code" ], "type": "object" }, "depots.PhysicalReceivingLocationResponse": { "properties": { "data": { "$ref": "#/components/schemas/depots.PhysicalReceivingLocationEvidence" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "depots.ReceivingLocationRequest": { "additionalProperties": false, "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "market_code": { "type": "string" } }, "required": [ "market_code", "address" ], "type": "object" }, "depots.ReceivingLocationResult": { "properties": { "captured_at": { "format": "date-time", "type": "string" }, "coverage_revision": { "type": "string" }, "geographic_context": { "$ref": "#/components/schemas/geography.GeographicContext" }, "status": { "enum": [ "resolved", "unresolved" ], "type": "string" } }, "required": [ "status", "geographic_context", "coverage_revision", "captured_at" ], "type": "object" }, "favourite.FavouriteList": { "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "default_name_slot": { "type": "integer" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "$ref": "#/components/schemas/favourite.FavouriteListOwner" }, "products": { "items": { "$ref": "#/components/schemas/favourite.FavouriteListProduct" }, "type": "array", "uniqueItems": false }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "favourite.FavouriteListOwner": { "properties": { "organisation_code": { "type": "string" }, "type": { "$ref": "#/components/schemas/favourite_enums.FavouriteListOwnerType" }, "user_id": { "type": "string" } }, "type": "object" }, "favourite.FavouriteListProduct": { "properties": { "added_at": { "type": "string" }, "sku_code": { "type": "string" } }, "type": "object" }, "favourite_enums.FavouriteListOwnerType": { "enum": [ "retail_user", "wholesale_organisation" ], "type": "string", "x-enum-varnames": [ "FavouriteListOwnerTypeRetailUser", "FavouriteListOwnerTypeWholesaleOrganisation" ] }, "filteroptions.Item": { "additionalProperties": false, "properties": { "value": { "description": "Exact stored string, at most 512 UTF-8 bytes. Includes service actors; no display-name hydration.", "maxLength": 512, "type": "string" } }, "required": [ "value" ], "type": "object" }, "filteroptions.Result": { "additionalProperties": false, "properties": { "field": { "enum": [ "cause_type", "performed_by", "cause_id", "operator" ], "type": "string" }, "has_more": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/filteroptions.Item" }, "maxItems": 100, "type": "array" }, "next_after": { "description": "Present only when has_more=true. Pass unchanged as after with the same filters and search.", "maxLength": 512, "type": "string" } }, "required": [ "field", "items", "has_more" ], "type": "object" }, "forecasting.CampaignComparableEvent": { "properties": { "audience": { "items": { "$ref": "#/components/schemas/campaign_enums.CampaignCustomerType" }, "type": "array" }, "campaign_code": { "type": "string" }, "ends_at": { "type": "string" }, "geographic_scope": { "$ref": "#/components/schemas/geography.GeographicScope" }, "match_source": { "$ref": "#/components/schemas/marketing_enums.CampaignPredictionSource" }, "placements": { "items": { "$ref": "#/components/schemas/campaign.Placement" }, "type": "array" }, "resolved_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "schedule_timezone": { "type": "string" }, "starts_at": { "type": "string" } }, "type": "object" }, "forecasting.CampaignPrediction": { "properties": { "algorithm_version": { "type": "string" }, "campaign_code": { "type": "string" }, "missing_prerequisites": { "items": { "type": "string" }, "type": "array" }, "predicted_at": { "type": "string" }, "prediction_key": { "type": "string" }, "products": { "items": { "$ref": "#/components/schemas/forecasting.CampaignProductPrediction" }, "type": "array", "uniqueItems": false }, "resolved_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "revision": { "type": "integer" }, "status": { "$ref": "#/components/schemas/marketing_enums.CampaignPredictionStatus" }, "suppliers": { "items": { "$ref": "#/components/schemas/forecasting.CampaignSupplierPrediction" }, "type": "array", "uniqueItems": false }, "warnings": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "forecasting.CampaignPredictionEvidence": { "properties": { "campaign_code": { "type": "string" }, "normalized_base_units": { "type": "integer" }, "raw_net_base_units": { "type": "integer" }, "source": { "$ref": "#/components/schemas/marketing_enums.CampaignPredictionSource" }, "weight": { "type": "number" }, "window_end": { "type": "string" }, "window_start": { "type": "string" } }, "type": "object" }, "forecasting.CampaignProductPrediction": { "properties": { "confirmed_inbound_base_units": { "type": "integer" }, "evidence": { "items": { "$ref": "#/components/schemas/forecasting.CampaignPredictionEvidence" }, "type": "array", "uniqueItems": false }, "minimum_order_base_units": { "type": "integer" }, "net_required_base_units": { "type": "integer" }, "orderable": { "type": "boolean" }, "predicted_demand_base_units": { "type": "integer" }, "sellable_available_base_units": { "type": "integer" }, "sku_code": { "type": "string" }, "source": { "$ref": "#/components/schemas/marketing_enums.CampaignPredictionSource" }, "suggested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "suggested_order_base_units": { "type": "integer" }, "supplier_code": { "type": "string" }, "warnings": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "forecasting.CampaignSupplierPrediction": { "properties": { "products": { "items": { "$ref": "#/components/schemas/forecasting.CampaignProductPrediction" }, "type": "array", "uniqueItems": false }, "supplier_code": { "type": "string" }, "total_base_units": { "type": "integer" }, "warnings": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "forecasting.DailyPrediction": { "properties": { "date": { "type": "string" }, "qty": { "type": "number" } }, "type": "object" }, "forecasting.ForecastAvailabilitySnapshot": { "properties": { "as_of": { "type": "string" }, "quality_hold_base_units": { "type": "integer" }, "reserved_base_units": { "type": "integer" }, "revision": { "type": "integer" }, "sellable_available_base_units": { "type": "integer" }, "staged_base_units": { "type": "integer" } }, "type": "object" }, "forecasting.SKUDemandForecast": { "properties": { "alert_level": { "$ref": "#/components/schemas/security_enums.AlertLevel" }, "algorithm": { "type": "string" }, "algorithm_params": { "$ref": "#/components/schemas/metadata.Metadata" }, "availability_at_run": { "$ref": "#/components/schemas/forecasting.ForecastAvailabilitySnapshot" }, "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "computed_at": { "type": "string" }, "country_code": { "description": "CountryCode is the denormalized country the forecast is attributed to,\nso a country-scoped principal is filtered by a plain indexed match. An\nempty value provides no geographic evidence and is handled fail-closed\nby the consumer.", "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "days_until_stockout": { "description": "DaysUntilStockout is nil when no stock-out is predicted within the horizon.", "type": "number" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "forecast_horizon_days": { "type": "integer" }, "history_days": { "type": "integer" }, "market_code": { "type": "string" }, "predicted_daily": { "description": "PredictedDaily is an ordered list of per-day demand predictions\ncovering the forecast horizon.", "items": { "$ref": "#/components/schemas/forecasting.DailyPrediction" }, "type": "array", "uniqueItems": false }, "predicted_demand_total": { "type": "number" }, "product_name": { "type": "string" }, "sku_code": { "type": "string" }, "timezone": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "forecasts.BulkClearInput": { "additionalProperties": false, "properties": { "forecasts": { "items": { "$ref": "#/components/schemas/forecasts.BulkForecastKey" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "forecasts" ], "type": "object" }, "forecasts.BulkClearResponse": { "properties": { "data": { "properties": { "forecasts": { "items": { "$ref": "#/components/schemas/forecasts.BulkForecastKey" }, "type": "array" }, "updated_count": { "description": "Selected records including already-clear records, matching individual clear semantics.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "forecasts", "updated_count" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "forecasts.BulkForecastKey": { "additionalProperties": false, "properties": { "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "depot_code": { "maxLength": 128, "type": "string" }, "sku_code": { "maxLength": 128, "type": "string" }, "timezone": { "description": "Valid IANA location, for example Australia/Sydney or Etc/UTC.", "maxLength": 128, "type": "string" } }, "required": [ "sku_code", "depot_code", "channel", "timezone" ], "type": "object" }, "fulfilment.OutboundContainerContent": { "properties": { "allocation_id": { "type": "string" }, "bucket_id": { "type": "string" }, "lot_id": { "type": "string" }, "order_item_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "fulfilment.OutboundContainerPlan": { "properties": { "container_code": { "type": "string" }, "contents": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerContent" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "is_manually_planned": { "type": "boolean" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "updated_at": { "type": "string" } }, "type": "object" }, "fulfilment.OutboundShipment": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "carrier": { "description": "Carrier is the optional delivery-company code recorded by Supply\n(for example parcel-fleet).", "type": "string" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "containers": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerPlan" }, "type": "array", "uniqueItems": false }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "customer_name": { "type": "string" }, "data_owner_id": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "delivered_at": { "type": "string" }, "delivery_selection": { "$ref": "#/components/schemas/shipping.DeliverySelection" }, "depot_code": { "type": "string" }, "dispatched_at": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "latest_carrier_booking": { "$ref": "#/components/schemas/courier.CarrierBookingSummary" }, "legal_hold": { "type": "boolean" }, "market_code": { "description": "MarketCode and CountryCode are the denormalized market and country of\nthe dispatching depot, carried so a geographically scoped staff query\nis a plain indexed match.", "type": "string" }, "note": { "type": "string" }, "operator": { "type": "string" }, "order_number": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "recipient": { "$ref": "#/components/schemas/party.Recipient" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "status": { "$ref": "#/components/schemas/warehouse_enums.OutboundShipmentStatus" }, "tracking_number": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "fulfilment.PackageSubstitutionSnapshot": { "properties": { "captured_at": { "type": "string" }, "fulfilled_sealed_case_count": { "type": "integer" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "operator": { "type": "string" }, "reason_code": { "type": "string" }, "replacement_base_units": { "type": "integer" }, "replacement_each_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_case_count": { "type": "integer" }, "requested_case_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_units_per_case": { "type": "integer" }, "source_bucket_id": { "type": "string" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "fulfilment.PackingDamage": { "properties": { "affected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "id": { "type": "string" }, "note": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "resulting_movement_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "type": "object" }, "fulfilment.PackingDiscrepancy": { "properties": { "damage_handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/warehouse_enums.PackingDiscrepancyKind" }, "notified": { "type": "boolean" }, "observed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_date": { "format": "date-time", "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "product_name": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "recorded_at": { "format": "date-time", "type": "string" }, "recorded_by": { "type": "string" }, "refund_amount": { "$ref": "#/components/schemas/money.Money" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "withdrawals": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDiscrepancyWithdrawal" }, "type": "array" } }, "required": [ "id", "order_number", "order_item_id", "sku_code", "kind", "requested_composition", "observed_composition", "notified", "recorded_at" ], "type": "object" }, "fulfilment.PackingDiscrepancyWithdrawal": { "properties": { "method": { "$ref": "#/components/schemas/warehouse_enums.PackingDiscrepancyWithdrawalMethod" }, "withdrawn_at": { "format": "date-time", "type": "string" }, "withdrawn_base_units": { "format": "int64", "minimum": 1, "type": "integer" }, "withdrawn_by": { "type": "string" } }, "required": [ "withdrawn_base_units", "method", "withdrawn_by", "withdrawn_at" ], "type": "object" }, "fulfilment.PackingLine": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "id": { "type": "string" }, "order_item_id": { "type": "string" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "product_name": { "type": "string" }, "refunded_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "substituted_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "fulfilment.PackingRecord": { "properties": { "closed_at": { "format": "date-time", "type": "string" }, "containers": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerPlan" }, "type": "array" }, "created_at": { "format": "date-time", "type": "string" }, "damages": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDamage" }, "type": "array" }, "discrepancies": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDiscrepancy" }, "type": "array" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "id": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/fulfilment.PackingLine" }, "type": "array" }, "operator": { "type": "string" }, "order_number": { "type": "string" }, "packed_at": { "format": "date-time", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "started_at": { "format": "date-time", "type": "string" }, "status": { "$ref": "#/components/schemas/order_enums.FulfillmentStatus" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "order_number", "fulfillment_generation", "revision", "status", "lines", "created_at", "updated_at" ], "type": "object" }, "geography.Address": { "properties": { "administrative_area": { "$ref": "#/components/schemas/geography.AdministrativeAreaRef" }, "country": { "$ref": "#/components/schemas/geography.CountryRef" }, "formatted_address": { "type": "string" }, "label": { "type": "string" }, "latitude": { "type": "number" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "locality": { "description": "Locality covers a city, suburb, town, municipality, or equivalent\npostal locality.", "type": "string" }, "longitude": { "type": "number" }, "place_id": { "type": "string" }, "postal_code": { "type": "string" } }, "type": "object" }, "geography.AdministrativeAreaRef": { "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/geography_enums.AdministrativeAreaType" } }, "type": "object" }, "geography.CountryCode": { "type": "string" }, "geography.CountryRef": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "geography.GeographicContext": { "properties": { "evaluation_timezone": { "type": "string" }, "market_code": { "type": "string" }, "matched_path": { "$ref": "#/components/schemas/geography.GeographicPath" }, "path": { "$ref": "#/components/schemas/geography.GeographicPath" }, "rule_revision": { "type": "integer" }, "scope_revision": { "type": "integer" }, "source": { "$ref": "#/components/schemas/geography_enums.GeographicContextSource" } }, "required": [ "source", "scope_revision", "rule_revision", "evaluation_timezone" ], "type": "object" }, "geography.GeographicPath": { "additionalProperties": false, "description": "Independent contiguous Country -\u003e Market -\u003e official State -\u003e Depot path. The service validates authoritative ancestry.", "properties": { "country_code": { "pattern": "^[A-Z]{2}$", "type": "string" }, "depot_code": { "minLength": 1, "type": "string" }, "market_code": { "minLength": 1, "type": "string" }, "state_code": { "minLength": 1, "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "geography.GeographicScope": { "properties": { "mode": { "$ref": "#/components/schemas/geography_enums.GeographicScopeMode" }, "targets": { "items": { "$ref": "#/components/schemas/geography.GeographicPath" }, "maxItems": 100, "type": "array", "uniqueItems": true } }, "required": [ "mode" ], "type": "object" }, "geography.GeographicTarget": { "properties": { "code": { "type": "string" }, "kind": { "$ref": "#/components/schemas/geography_enums.GeographicTargetKind" } }, "type": "object" }, "geography_enums.AdministrativeAreaType": { "enum": [ "STATE", "TERRITORY", "PROVINCE", "PREFECTURE", "REGION", "DISTRICT" ], "type": "string", "x-enum-varnames": [ "AdministrativeAreaState", "AdministrativeAreaTerritory", "AdministrativeAreaProvince", "AdministrativeAreaPrefecture", "AdministrativeAreaRegion", "AdministrativeAreaDistrict" ] }, "geography_enums.GeographicContextSource": { "enum": [ "DELIVERY_ADDRESS", "FULFILMENT_DEPOT", "WHOLESALE_ORGANISATION_PROFILE", "GLOBAL_FALLBACK" ], "type": "string", "x-enum-varnames": [ "GeographicContextSourceDeliveryAddress", "GeographicContextSourceFulfilmentDepot", "GeographicContextSourceWholesaleOrganisationProfile", "GeographicContextSourceGlobalFallback" ] }, "geography_enums.GeographicScopeMode": { "enum": [ "GLOBAL", "TARGETED" ], "type": "string", "x-enum-varnames": [ "GeographicScopeModeGlobal", "GeographicScopeModeTargeted" ] }, "geography_enums.GeographicTargetKind": { "enum": [ "COUNTRY", "SUBDIVISION", "DEPOT_REGION", "DEPOT" ], "type": "string", "x-enum-varnames": [ "GeographicTargetCountry", "GeographicTargetSubdivision", "GeographicTargetDepotRegion", "GeographicTargetDepot" ] }, "geometry.BoundingBox": { "properties": { "max": { "$ref": "#/components/schemas/geometry.Vector3" }, "min": { "$ref": "#/components/schemas/geometry.Vector3" } }, "type": "object" }, "geometry.Rotation3": { "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "type": "object" }, "geometry.Size3D": { "properties": { "depth_mm": { "type": "integer" }, "height_mm": { "type": "integer" }, "width_mm": { "type": "integer" } }, "type": "object" }, "geometry.Transform": { "properties": { "position": { "$ref": "#/components/schemas/geometry.Vector3" }, "rotation": { "$ref": "#/components/schemas/geometry.Rotation3" }, "scale": { "$ref": "#/components/schemas/geometry.Vector3" } }, "type": "object" }, "geometry.Vector3": { "description": "offset to apply when placing the model", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "z": { "type": "number" } }, "type": "object" }, "geopaths.APIResponse": { "properties": { "data": { "$ref": "#/components/schemas/geopaths.Response" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "geopaths.Path": { "additionalProperties": false, "description": "Contiguous country, market, official state, depot path; parents may not be omitted.", "properties": { "country_code": { "pattern": "^[A-Z]{2}$", "type": "string" }, "depot_code": { "maxLength": 128, "minLength": 1, "type": "string" }, "market_code": { "maxLength": 128, "minLength": 1, "type": "string" }, "state_code": { "maxLength": 16, "minLength": 1, "type": "string" } }, "required": [ "country_code" ], "type": "object" }, "geopaths.Request": { "additionalProperties": false, "properties": { "paths": { "items": { "$ref": "#/components/schemas/geopaths.Path" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "paths" ], "type": "object" }, "geopaths.Response": { "properties": { "items": { "items": { "properties": { "path": { "$ref": "#/components/schemas/geopaths.Path" }, "reason": { "type": "string" }, "valid": { "type": "boolean" } }, "required": [ "path", "valid" ], "type": "object" }, "type": "array" }, "resolved_at": { "format": "date-time", "type": "string" } }, "required": [ "items", "resolved_at" ], "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_gcsstorage.BucketInfo": { "properties": { "created_at": { "type": "string" }, "location": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.CatalogProduct": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot" }, "type": "array", "uniqueItems": false }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "image_url": { "type": "string" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "package_options": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "type": "array", "uniqueItems": false }, "price_availability": { "$ref": "#/components/schemas/productmodel.PriceAvailability" }, "selected_depot_availability": { "$ref": "#/components/schemas/productmodel.POSDepotAvailability" }, "selling_product": { "$ref": "#/components/schemas/product.SellingProduct" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "updated_at": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.DetailImage": { "properties": { "alt_text": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "caption": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "media_code": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.PreorderPolicy": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "enabled": { "type": "boolean" }, "ends_at": { "type": "string" }, "expected_available_at": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "max_quantity_per_customer": { "type": "integer" }, "max_quantity_per_order": { "type": "integer" }, "schedule_timezone": { "type": "string" }, "starts_at": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot": { "properties": { "captured_at": { "type": "string" }, "code": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "format": { "$ref": "#/components/schemas/product_enums.BarcodeFormat" }, "is_primary": { "type": "boolean" }, "manufacturer_code": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot": { "properties": { "captured_at": { "type": "string" }, "code": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "sku_code": { "minLength": 1, "type": "string" }, "units_per_package": { "type": "integer" }, "version": { "format": "int64", "minimum": 1, "type": "integer" }, "weight": { "$ref": "#/components/schemas/measurement.Weight" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.Snapshot": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot" }, "type": "array", "uniqueItems": false }, "brands": { "items": { "$ref": "#/components/schemas/classification.BrandRef" }, "type": "array", "uniqueItems": false }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/classification.CollectionRef" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "image_url": { "type": "string" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "supply": { "$ref": "#/components/schemas/classification.ProductSupply" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.SoonExpiryMerchandisingPolicy": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "enabled": { "type": "boolean" }, "ends_at": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "show_exact_expiry_date": { "type": "boolean" }, "starts_at": { "type": "string" }, "window_days": { "description": "Stored as 30 for compatibility. It does not drive storefront_display.expiry, whose window is the effective listing soon-expiry lead days.", "type": "integer" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCategoryTagDetail": { "properties": { "code": { "description": "Immutable category tag relationship code.", "type": "string" }, "collection_code": { "type": "string" }, "collection_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "slug": { "type": "string" } }, "required": [ "code", "id", "slug", "name", "collection_code", "collection_name" ], "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCommercial": { "description": "Retail availability for the exact package_option within depots serving the resolved request market_code. Display evidence is provisional and does not reserve inventory.", "properties": { "as_of": { "description": "UTC evaluation time of the scoped inventory read.", "type": "string" }, "available_base_units": { "description": "Sum of current positive unreserved GOOD STANDARD_SELLABLE balances for this package SKU, code and version in eligible market depots, excluding expired, expiry-held and staged stock. Omitted when availability is unknown. This is a market-wide total across depots, lots and locations; a single cart line can buy at most max_line_base_units of it.", "type": "integer" }, "market": { "description": "Country code of the resolved market; inventory scope is determined by the request market_code and its effective depot associations.", "type": "string" }, "max_line_base_units": { "description": "Largest quantity, in base units, that ONE cart line of this package can buy now in the resolved market on the standard path. An online line is quoted from a single stock bucket, so this is the largest single counted bucket, capped by its depot's signed net stock of the SKU (deficits booked at that depot reduce it), never more than available_base_units and 0 when out of stock; available_base_units may be larger when stock is split across lots, locations or depots. Clients should cap a line's quantity stepper at this value. Present exactly when available_base_units is present and omitted when availability is unknown. Provisional display evidence, not a reservation or a guarantee of a later quote.", "format": "int64", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "stock_state": { "$ref": "#/components/schemas/product_enums.StorefrontStockState" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontDisplay": { "description": "StorefrontDisplay is the customer-safe projection of the stored\nstorefront_merchandising policy, computed at read time.", "properties": { "expiry": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontExpiryDisplay" }, "preorder": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontPreorderDisplay" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontExpiryDisplay": { "description": "Retail soon-expiry display, served on list and detail storefront reads for EVERY product whose earliest sellable lot (selling_product.expiry_date) falls inside the effective soon-expiry lead days, and omitted otherwise. The lead days are the market listing's expiry_lead_days_override when it is positive, else the Pricing-owned market's expiry_lead_days (0 means no soon-expiry window), else 30: the same value sale eligibility uses for the soon-expiry price path, with the same instant rule (now \u003c date_mark_at \u003c now + lead days). The product's soon-expiry merchandising policy does not decide whether it is shown; when that policy is enabled and inside its starts_at/ends_at window it supplies labels, descriptions and show_exact_expiry_date, otherwise the exact best-before is shown without labels. If Pricing cannot answer the lead days the display falls back to the market default, else 30 days, and the read still succeeds.", "properties": { "alert_level": { "$ref": "#/components/schemas/security_enums.AlertLevel" }, "days_to_expiry": { "description": "Calendar days from today to the earliest lot's date mark, counted in the mark's own timezone. alert_level is critical from seven days before the mark and warning before that.", "type": "integer" }, "descriptions": { "description": "The open soon-expiry policy's descriptions; empty when the policy is absent, disabled or outside its window.", "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "expires_at": { "description": "UTC instant of the earliest lot's date mark, present when show_exact_expiry_date is true.", "type": "string" }, "labels": { "description": "The open soon-expiry policy's labels; empty when the policy is absent, disabled or outside its window.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "show_exact_expiry_date": { "description": "The open policy's show_exact_expiry_date; true when no soon-expiry policy is enabled and open.", "type": "boolean" }, "soon_expiry": { "description": "Always true when the display is present.", "type": "boolean" }, "status": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontExpiryStatus" }, "window_days": { "description": "The effective soon-expiry lead days in force for this product's market listing (listing expiry_lead_days_override, else the market's expiry_lead_days, else 30). It is never the merchandising policy's stored window_days.", "type": "integer" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontExpiryStatus": { "enum": [ "not_applicable", "soon_expiry", "expired" ], "type": "string", "x-enum-varnames": [ "StorefrontExpiryStatusNotApplicable", "StorefrontExpiryStatusSoonExpiry", "StorefrontExpiryStatusExpired" ] }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontMerchandising": { "description": "StorefrontMerchandising is admin-authored display policy. It is stored,\nnever returned raw to customers: read models project it into\nproductmodel.StorefrontDisplay at request time.", "properties": { "preorder": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.PreorderPolicy" }, "soon_expiry": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.SoonExpiryMerchandisingPolicy" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontOrigin": { "description": "Country-of-origin display block, accepted on product create and update\nand stored as content.origin. country_code is upper-cased and must be an\nISO 3166-1 alpha-2 code. Every label and statement entry needs a\nlanguage and text, one entry per language; label text is at most 120\ncharacters and statement text at most 1000. Violations answer 400 with\ndetails.reason_code COUNTRY_OF_ORIGIN_INVALID and details.field naming\nthe offending field.", "properties": { "country_code": { "description": "ISO 3166-1 alpha-2 country code; lower-case input is upper-cased.", "pattern": "^[A-Za-z]{2}$", "type": "string" }, "label": { "description": "Short origin label, one entry per language, text at most 120 characters.", "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "statement": { "description": "Longer origin statement, one entry per language, text at most 1000 characters.", "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false } }, "required": [ "country_code" ], "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontPreorderDisplay": { "properties": { "available": { "type": "boolean" }, "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "ends_at": { "type": "string" }, "expected_available_at": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "max_quantity_per_customer": { "type": "integer" }, "max_quantity_per_order": { "type": "integer" }, "schedule_timezone": { "type": "string" }, "starts_at": { "type": "string" }, "status": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontPreorderStatus" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontPreorderStatus": { "enum": [ "unavailable", "upcoming", "open", "closed", "sold_out" ], "type": "string", "x-enum-varnames": [ "StorefrontPreorderStatusUnavailable", "StorefrontPreorderStatusUpcoming", "StorefrontPreorderStatusOpen", "StorefrontPreorderStatusClosed", "StorefrontPreorderStatusSoldOut" ] }, "github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.WholesalePriceMode": { "enum": [ "fixed", "on_request" ], "type": "string", "x-enum-varnames": [ "WholesalePriceModeFixed", "WholesalePriceModeOnRequest" ] }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.FrozenSubstitutionPolicy": { "properties": { "allow_case_to_each": { "type": "boolean" }, "replacement_each_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.GroupOrderReservationContext": { "properties": { "group_order_code": { "type": "string" }, "parent_allocation_line_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "parent_fulfilment_id": { "type": "string" }, "parent_order_number": { "type": "string" }, "role": { "$ref": "#/components/schemas/group_order_enums.GroupOrderRole" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReferenceCommand": { "properties": { "expected_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "order_number": { "type": "string" }, "ref_number": { "type": "string" }, "ref_type": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationAllocation": { "properties": { "allocation": { "$ref": "#/components/schemas/inventory.StockReservationAllocation" }, "group_order_code": { "type": "string" }, "group_order_role": { "$ref": "#/components/schemas/group_order_enums.GroupOrderRole" }, "order_item_id": { "type": "string" }, "parent_allocation_line_id": { "type": "string" }, "parent_fulfilment_id": { "type": "string" }, "parent_order_number": { "type": "string" }, "reservation_id": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationCommand": { "properties": { "channel": { "allOf": [ { "$ref": "#/components/schemas/commerce_enums.OrderType" } ], "description": "Optional sales channel of the order (the shared commerce order type, lower case - online, pos, b2b, relay, manual, import). online is all-or-nothing - when any line cannot be held in full the command is refused with 409 INSUFFICIENT_STOCK and nothing is held, spent or recorded. Any other channel, or none, holds what it can and reports the remainder in shortages. An unknown value is a 400 VALIDATION error. The channel is part of the idempotency fingerprint." }, "depot_code": { "type": "string" }, "expires_at": { "type": "string" }, "group_order": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.GroupOrderReservationContext" }, "idempotency_key": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationLine" }, "type": "array", "uniqueItems": false }, "order_number": { "type": "string" }, "ref_number": { "type": "string" }, "ref_type": { "type": "string" }, "timezone": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationLine": { "properties": { "eligibility_token": { "type": "string" }, "listing_revision": { "type": "integer" }, "market_code": { "type": "string" }, "order_item_id": { "type": "string" }, "parent_allocation_line_id": { "type": "string" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "substitution_policy": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.FrozenSubstitutionPolicy" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationResult": { "properties": { "allocations": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationAllocation" }, "type": "array", "uniqueItems": false }, "replayed": { "type": "boolean" }, "reservation_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "shortages": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationShortage" }, "type": "array", "uniqueItems": false }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationShortage": { "properties": { "missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_item_id": { "type": "string" }, "parent_allocation_line_id": { "type": "string" }, "sku_code": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_modules_deletioncontrol_deletionwire.AccountDeletionOperation": { "enum": [ "restrict", "eligibility", "erase_or_deidentify", "unrestrict" ], "type": "string", "x-enum-varnames": [ "AccountDeletionOperationRestrict", "AccountDeletionOperationEligibility", "AccountDeletionOperationEraseOrDeidentify", "AccountDeletionOperationUnrestrict" ] }, "github_com_Potato-Mart_Backend-Supply_internal_modules_deletioncontrol_deletionwire.CommandEnvelope": { "properties": { "idempotency_key": { "type": "string" }, "policy_version": { "type": "string" }, "request_id": { "type": "string" }, "snapshot_version": { "type": "string" }, "user_id": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_modules_deletioncontrol_deletionwire.ServiceOperation": { "properties": { "envelope": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_modules_deletioncontrol_deletionwire.CommandEnvelope" }, "operation": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_modules_deletioncontrol_deletionwire.AccountDeletionOperation" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error": { "properties": { "code": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse_apiresponse_enums.Code" }, "details": { "additionalProperties": { "type": "string" }, "type": "object" }, "message": { "type": "string" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse_apiresponse_enums.Code": { "enum": [ "INTERNAL_ERROR", "BAD_REQUEST", "VALIDATION_ERROR", "NOT_FOUND", "CONFLICT", "UNAUTHORIZED", "FORBIDDEN", "TOO_MANY_REQUESTS", "REQUEST_BODY_TOO_LARGE", "SERVICE_UNAVAILABLE", "AUTH_INVALID_CREDENTIALS", "AUTH_INVALID_TOKEN", "AUTH_EXPIRED_TOKEN", "AUTH_WRONG_PORTAL", "AUTH_ACCOUNT_DISABLED", "AUTH_MFA_REQUIRED", "AUTH_REAUTH_REQUIRED", "EMAIL_VERIFICATION_REQUIRED", "SECURITY_POLICY_VIOLATION", "IDENTITY_ACCOUNT_TYPE_NOT_ALLOWED", "IDENTITY_PORTAL_ACCESS_DENIED", "IDENTITY_PORTAL_ACCESS_REVOKED", "IDENTITY_ACCOUNT_SUSPENDED", "IDENTITY_AUTH_IDENTITY_DISABLED", "IDENTITY_MFA_REQUIRED", "IDENTITY_WHOLESALE_ORGANISATION_NOT_APPROVED", "IDENTITY_ORGANISATION_ACCESS_REQUIRED", "MEMBERSHIP_NOT_FOUND", "MEMBERSHIP_INACTIVE", "MEMBERSHIP_INSUFFICIENT_POINTS", "MEMBERSHIP_REWARD_UNAVAILABLE", "MEMBERSHIP_POINT_RESERVATION_EXPIRED", "USER_EMAIL_TAKEN", "SKU_CODE_TAKEN", "STORAGE_LOCATION_CODE_TAKEN", "PRODUCT_CODE_TAKEN", "STORAGE_MISMATCH", "INSUFFICIENT_STOCK", "NO_LOT_AT_LOCATION", "COST_REQUIRED", "PRODUCT_NOT_FOUND", "ORDER_SET_MISMATCH", "PACKING_SHORTAGE_REFUND_APPLIED", "PACKING_LINE_NOT_RESERVED", "ORDER_INVALID_TRANSITION", "ORDER_TERMINAL", "ORDER_EMPTY", "CART_NOT_ACTIVE", "DISCOUNT_NOT_FOUND", "DISCOUNT_INACTIVE", "DISCOUNT_NOT_STARTED", "DISCOUNT_EXPIRED", "DISCOUNT_EXHAUSTED", "DISCOUNT_MIN_NOT_MET", "DISCOUNT_CODE_TAKEN", "DISCOUNT_INAPPLICABLE", "TERMINAL_NOT_CONNECTED", "TERMINAL_NOT_REGISTERED", "TERMINAL_OUTCOME_UNKNOWN", "TERMINAL_SIGNATURE_FAIL", "TERMINAL_TIMEOUT", "TERMINAL_REQUEST_REJECTED", "TERMINAL_BUSY" ], "type": "string", "x-enum-varnames": [ "CodeInternal", "CodeBadRequest", "CodeValidation", "CodeNotFound", "CodeConflict", "CodeUnauthorized", "CodeForbidden", "CodeTooManyRequests", "CodeRequestTooLarge", "CodeServiceUnavailable", "CodeAuthInvalidCredentials", "CodeAuthInvalidToken", "CodeAuthExpiredToken", "CodeAuthWrongPortal", "CodeAuthAccountDisabled", "CodeAuthMFARequired", "CodeAuthReauthRequired", "CodeEmailVerificationRequired", "CodeSecurityPolicyViolation", "CodeIdentityAccountTypeNotAllowed", "CodeIdentityPortalAccessDenied", "CodeIdentityPortalAccessRevoked", "CodeIdentityAccountSuspended", "CodeIdentityAuthIdentityDisabled", "CodeIdentityMFARequired", "CodeIdentityWholesaleOrganisationNotApproved", "CodeIdentityOrganisationAccessRequired", "CodeMembershipNotFound", "CodeMembershipInactive", "CodeMembershipInsufficientPoints", "CodeMembershipRewardUnavailable", "CodeMembershipPointReservationExpired", "CodeUserEmailTaken", "CodeSKUCodeTaken", "CodeStorageLocationCodeTaken", "CodeProductCodeTaken", "CodeStorageMismatch", "CodeInsufficientStock", "CodeNoLotAtLocation", "CodeCostRequired", "CodeProductNotFound", "CodeOrderSetMismatch", "CodePackingShortageRefundApplied", "CodePackingLineNotReserved", "CodeOrderInvalidTransition", "CodeOrderTerminal", "CodeOrderEmpty", "CodeCartNotActive", "CodeDiscountNotFound", "CodeDiscountInactive", "CodeDiscountNotStarted", "CodeDiscountExpired", "CodeDiscountExhausted", "CodeDiscountMinNotMet", "CodeDiscountCodeTaken", "CodeDiscountInapplicable", "CodeTerminalNotConnected", "CodeTerminalNotRegistered", "CodeTerminalOutcomeUnknown", "CodeTerminalSignatureFail", "CodeTerminalTimeout", "CodeTerminalRequestRejected", "CodeTerminalBusy" ] }, "github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" }, "github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse": { "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total_items": { "type": "integer" }, "total_pages": { "type": "integer" } }, "type": "object" }, "group_order_enums.GroupOrderRole": { "enum": [ "CONSOLIDATED_PARENT", "PARTICIPANT" ], "type": "string", "x-enum-varnames": [ "GroupOrderRoleConsolidatedParent", "GroupOrderRoleParticipant" ] }, "internal_modules_catalog.AcknowledgeProductReviewsRequest": { "additionalProperties": false, "properties": { "entry_ids": { "items": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "entry_ids" ], "type": "object" }, "internal_modules_catalog.AcknowledgeProductReviewsResult": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.PurchaseOrderProductReview" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "internal_modules_catalog.BrandInput": { "properties": { "active": { "type": "boolean" }, "clear_logo": { "description": "Update only. true removes the brand logo and releases its managed media reference. Cannot be combined with logo.", "type": "boolean" }, "code": { "type": "string" }, "expected_updated_at": { "description": "Update only. The brand's updated_at as last read. When present and the brand has changed since (compared at millisecond precision), the update answers 409 CONFLICT and writes nothing. Omit to update without the fence.", "format": "date-time", "type": "string" }, "logo": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.CategoryProductOrderInput": { "description": "Replaces the whole product order of a category. Array order becomes position (0-based). sku_codes must name exactly the products currently in the category (the set GET returns); a missing or extra code answers 422 ORDER_SET_MISMATCH and changes nothing. A row whose product is null may be omitted, which removes it from the order. A category can be reordered while it holds at most 2000 products.", "properties": { "expected_revision": { "description": "The revision the caller last read. A category whose order was never saved is at revision 1.", "format": "int64", "minimum": 1, "type": "integer" }, "sku_codes": { "items": { "type": "string" }, "maxItems": 2000, "type": "array", "uniqueItems": true } }, "required": [ "expected_revision", "sku_codes" ], "type": "object" }, "internal_modules_catalog.CategoryTagOrderInput": { "description": "Replaces the tag order of one collection. Array order becomes display_order (0-based). category_tag_codes must name exactly the collection's tags (the set GET /collections/{slug}/category-tags/order returns); a missing or extra code answers 422 ORDER_SET_MISMATCH and changes nothing.", "properties": { "category_tag_codes": { "items": { "minLength": 1, "type": "string" }, "maxItems": 500, "type": "array", "uniqueItems": true }, "expected_revision": { "description": "The revision the caller last read. An order that was never saved is at revision 1.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_revision", "category_tag_codes" ], "type": "object" }, "internal_modules_catalog.CollectionOrderInput": { "description": "Replaces the one order every collection shares. Array order becomes display_order (0-based). collection_codes must name exactly every collection (the set GET /collections/order returns); a missing or extra code answers 422 ORDER_SET_MISMATCH and changes nothing.", "properties": { "collection_codes": { "items": { "minLength": 1, "type": "string" }, "maxItems": 500, "type": "array", "uniqueItems": true }, "expected_revision": { "description": "The revision the caller last read. An order that was never saved is at revision 1.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_revision", "collection_codes" ], "type": "object" }, "internal_modules_catalog.CreateInput": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/product.ProductBarcodeAssignment" }, "type": "array", "uniqueItems": false }, "brand_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "category_tags": { "description": "CategoryTags are first-class merchandising labels, separate from\nboth the collection and the SKU master. When collection is omitted\nand every tag belongs to the same collection, the server infers the\ncollection from the tags.", "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/classification.CollectionRef", "description": "Optional when every category tag belongs to the same collection; the\nserver infers it. Required when the tags belong to more than one\ncollection (400 \"category tags require a collection\" with the sorted\ncollection_codes in details). An explicit collection must contain\nevery tag." }, "country_of_origin": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontOrigin", "description": "Optional country-of-origin display block, validated with the same rules as the update path and returned as content.origin." }, "cover_media_code": { "type": "string" }, "creation_context": { "description": "Optional explicit purchase-order quick-create origin. Omission is ordinary creation; supplied null, empty or unknown values are rejected. Requires an authenticated actor and atomically registers a pending shared review; no purchase order ID is needed.", "enum": [ "purchase_order" ], "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "detail_images": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.DetailImageInput" }, "type": "array", "uniqueItems": false }, "image_media_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "name": { "description": "Required, non-blank primary display name. It may be in any language;\nit is stored in the \"en\" slot of the product name, and translations\ngo in other_names.", "type": "string" }, "net_content": { "$ref": "#/components/schemas/internal_modules_catalog.NetContentInput" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "type": "array", "uniqueItems": false }, "purchase_classification": { "description": "Explicit product classification; omission leaves it unknown. Stored value includes gift cards.", "enum": [ "merchandise", "stored_value" ], "type": "string" }, "sku_code": { "description": "Manual business key is trimmed and uppercased; any nonempty format is accepted except the reserved GIFT-CARD- prefix. A nonempty alphanumeric prefix followed by exactly four positive sequence digits advances that complete prefix's counter independently of product classification. Other manual formats do not advance counters. Reservation-backed suggestions must match their canonical lease. URL-encode the complete key in path routes.", "minLength": 1, "type": "string" }, "sku_code_reservation_id": { "type": "string" }, "sku_series_code": { "description": "Existing series code, trimmed and uppercased to one or more ASCII letters or digits with no fixed length.", "minLength": 1, "type": "string" }, "status": { "type": "string" }, "stock_tracked": { "description": "false creates a non-stock (service / non-inventory) SKU that is always POS sale-eligible with non_stock evidence and never reserves, settles stock or books a POS deficit. Omitted means stock tracked. OPEN0001..OPEN0020 open-price placeholders are non-stock regardless.", "type": "boolean" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType", "description": "Required authoritative product storage. The selected SKU series supplies the initial UI default; any valid product storage may override it." }, "supply": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSupplyInput" } }, "required": [ "name", "package_options", "sku_code", "sku_series_code", "storage_type" ], "type": "object" }, "internal_modules_catalog.DetailImageInput": { "properties": { "alt_text": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.LocalizedTextInput" }, "type": "array", "uniqueItems": false }, "caption": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.LocalizedTextInput" }, "type": "array", "uniqueItems": false }, "media_code": { "type": "string" } }, "required": [ "media_code" ], "type": "object" }, "internal_modules_catalog.InternalProductQueryContext": { "properties": { "channel": { "type": "string" }, "geography": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryGeography" }, "profile_revision": { "type": "integer" } }, "required": [ "channel", "profile_revision" ], "type": "object" }, "internal_modules_catalog.InternalProductQueryGeography": { "properties": { "country_code": { "type": "string" }, "delivery_area_code": { "type": "string" }, "depot_code": { "type": "string" }, "region_code": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.InternalProductQueryItem": { "properties": { "correlation_id": { "maxLength": 64, "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "resolve_base_package_option": { "description": "Resolve the current canonical EACH package when package_option is omitted.", "type": "boolean" }, "sku_code": { "type": "string" } }, "required": [ "correlation_id", "sku_code" ], "type": "object" }, "internal_modules_catalog.InternalProductQueryPreorderPolicy": { "properties": { "allowed": { "type": "boolean" }, "available_from": { "type": "string" }, "available_until": { "type": "string" }, "expected_available_at": { "description": "ExpectedAvailableAt is when stock is expected to arrive, copied verbatim\nfrom the stored policy. It is a different fact from AvailableFrom, which\nis when the ordering window opens, and it is never derived from it: a\npolicy with no expected date returns none rather than borrowing the\nwindow start.", "type": "string" }, "max_quantity_per_customer": { "description": "MaxQuantityPerCustomer is the per-customer preorder limit. nil means the\nstored policy sets no cap, which is not the same as a cap of zero.", "type": "integer" }, "max_quantity_per_order": { "description": "MaxQuantityPerOrder is the per-order preorder limit. nil means the stored\npolicy sets no limit, which is not the same as a limit of zero.", "type": "integer" }, "policy_version": { "description": "PolicyVersion is the immutable concurrency key Orders stamps onto the\ncart line, so a policy edited after the line was created is detectable\nas stale rather than silently honoured.\n\nIt is a content fingerprint of the preorder policy being returned, not a\nstored counter: Supply persists no preorder policy version, and inventing\na monotonic number would fabricate provenance. An earlier implementation\nused the same kind of value (\"sha256:\"+hex over the marshalled policy\nprojection); this narrows that\nhash to the preorder policy alone, so an unrelated product edit no longer\ninvalidates a stamped preorder line.\n\nThe frozen schema types it as a string, matching the contract\n(orders/order.PreorderItemSnapshot.PolicyVersion). An earlier revision of\nthe schema declared an integer; that was corrected in D14a, because no\ninteger version exists anywhere in Supply's data and one could only have\nbeen satisfied by inventing a counter.", "type": "string" }, "schedule_timezone": { "description": "ScheduleTimezone is the IANA zone the preorder window is expressed in,\ncopied verbatim from the stored policy. It is never defaulted: an empty\nstored value stays empty rather than becoming UTC.", "type": "string" } }, "type": "object" }, "internal_modules_catalog.InternalProductQueryRequest": { "properties": { "context": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryContext" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryItem" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "context", "items" ], "type": "object" }, "internal_modules_catalog.InternalProductQueryResponse": { "properties": { "context_revision": { "type": "integer" }, "resolved_at": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryResult" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.InternalProductQueryResult": { "properties": { "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "correlation_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "preorder_policy": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryPreorderPolicy" }, "product_image": { "$ref": "#/components/schemas/security.ObjectMedia" }, "product_name": { "type": "string" }, "product_package_option": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "product_revision": { "format": "int64", "type": "integer" }, "purchase_classification": { "description": "Explicit Supply product classification; omission means unknown.", "enum": [ "merchandise", "stored_value" ], "type": "string" }, "sku_code": { "type": "string" }, "visibility": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryVisibility" } }, "type": "object" }, "internal_modules_catalog.InternalProductQueryVisibility": { "properties": { "audience": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "reason": { "type": "string" }, "visible": { "type": "boolean" } }, "type": "object" }, "internal_modules_catalog.LifecycleTagOverrideInput": { "additionalProperties": false, "description": "Supplied flags are updated independently. True suppresses the tag until\nexplicitly restored with false; omitted flags remain unchanged. Null is\ninvalid. At least one flag is required even when expected_revision is\nsupplied.", "minProperties": 1, "properties": { "expected_revision": { "description": "Optional optimistic-concurrency token: the product revision the\ncaller last read. When present and different from the stored\nrevision the patch answers 409 with details.reason_code\nPRODUCT_REVISION_STALE, details.expected_revision and\ndetails.current_revision. Omit to keep today's flag-level guards only.", "format": "int64", "minimum": 1, "type": "integer" }, "new_suppressed": { "type": "boolean" }, "restocked_suppressed": { "type": "boolean" } }, "type": "object" }, "internal_modules_catalog.LifecycleTagOverrideResponse": { "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/product.Product" }, { "$ref": "#/components/schemas/internal_modules_catalog.productView" } ] }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.LifecycleTagOverrides": { "additionalProperties": false, "description": "Persistent product-wide suppression of automatic lifecycle tags. An absent object or flag means false.", "properties": { "new_suppressed": { "default": false, "type": "boolean" }, "restocked_suppressed": { "default": false, "type": "boolean" } }, "required": [ "new_suppressed", "restocked_suppressed" ], "type": "object" }, "internal_modules_catalog.LocalizedTextInput": { "properties": { "language": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.MeasureInput": { "description": "One exact measure: amount x 10^exponent in unit. amount must be positive\nand exponent within -18..18 (omitted exponent is 0). unit is the closed,\ncase-sensitive net-content vocabulary published by Shared Contract\nv53.1.0 measurement_enums.NetContentUnit; any other value answers 400\nwith details.reason_code NET_CONTENT_UNIT_UNSUPPORTED and\ndetails.supported_units.", "properties": { "amount": { "format": "int64", "minimum": 1, "type": "integer" }, "exponent": { "format": "int32", "maximum": 18, "minimum": -18, "type": "integer" }, "unit": { "description": "Dimensions: mass (g, kg), volume (mL, L), length (m), count (ea).\nUnits are case-sensitive.", "enum": [ "g", "kg", "mL", "L", "m", "ea" ], "type": "string" } }, "required": [ "amount", "unit" ], "type": "object" }, "internal_modules_catalog.NetContentInput": { "description": "Net content declaration accepted on product create and update.\nnet_quantity and standard_measure must describe the same dimension\n(both mass, both volume, both length or both count); otherwise the\nrequest answers 400 with details.reason_code\nNET_CONTENT_DIMENSION_MISMATCH. Responses return the stored declaration\nas measurement.NetContent.", "properties": { "net_quantity": { "$ref": "#/components/schemas/internal_modules_catalog.MeasureInput" }, "standard_measure": { "$ref": "#/components/schemas/internal_modules_catalog.MeasureInput" } }, "required": [ "net_quantity", "standard_measure" ], "type": "object" }, "internal_modules_catalog.POSMasterChange": { "description": "Upserts contain product and omit deleted. Tombstones contain deleted=true and omit product. Apply by sku_code.", "properties": { "deleted": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterProduct" }, "sku_code": { "type": "string" } }, "required": [ "sku_code" ], "type": "object" }, "internal_modules_catalog.POSMasterClassificationRef": { "description": "Snapshot of a classification master, in the shape of product.SellingProductClassificationRef without media.", "properties": { "code": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "slug": { "type": "string" } }, "required": [ "code", "name", "slug" ], "type": "object" }, "internal_modules_catalog.POSMasterPackageOption": { "allOf": [ { "$ref": "#/components/schemas/product.ProductPackageOption" }, { "required": [ "sku_code", "code", "version", "is_active", "is_canonical", "handling_unit", "units_per_package", "effective_from" ], "type": "object" } ], "description": "Authored package definition, including inactive versions. Identity is the complete SKU/code/version tuple. Flags and effective dates are not evaluated away." }, "internal_modules_catalog.POSMasterPage": { "properties": { "expires_at": { "description": "Logical expiry for this page's cursor evidence. Retention is 24 hours from snapshot creation and never slides on reads or requalification. Bootstrap after expiry.", "format": "date-time", "type": "string" }, "has_more": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterChange" }, "type": "array" }, "master_generation": { "description": "Opaque immutable master snapshot identity, independent of volatile price and stock observations.", "type": "string" }, "next_cursor": { "description": "Present only when has_more=true. Continue this frozen snapshot or delta, even if current prices or stock change.", "type": "string" }, "sync_cursor": { "description": "Persist after applying this page; pass as cursor to continue or poll a completed snapshot. No-change terminal polls return the supplied cursor unchanged.", "type": "string" } }, "required": [ "items", "master_generation", "sync_cursor", "has_more", "expires_at" ], "type": "object" }, "internal_modules_catalog.POSMasterProduct": { "description": "Stable authored master data. Contains no selling price, stock observation, sales metrics or signed media URL.", "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/product.ProductBarcodeAssignment" }, "type": "array" }, "brands": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterClassificationRef" }, "type": "array" }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array" }, "collection": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterClassificationRef" }, "image_url": { "type": "string" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "package_options": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterPackageOption" }, "type": "array" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "type": "string" }, "storage_type": { "type": "string" } }, "required": [ "sku_code", "sku_series_code", "name", "storage_type", "status", "package_options", "barcode_assignments" ], "type": "object" }, "internal_modules_catalog.POSMasterResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterPage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.POSRefreshAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.POSRefreshResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.POSRefreshItem": { "properties": { "eligible": { "description": "Current market membership and active product evidence, independent of stock quantity. Without a canonical EACH, price_availability is PACKAGE_OPTION_UNAVAILABLE and selling_product is absent while exact package stock remains available. Display evidence does not authorize a sale.", "type": "boolean" }, "price_availability": { "$ref": "#/components/schemas/productmodel.PriceAvailability" }, "removal_reason": { "description": "Present when eligible=false; volatile price and stock fields are then absent.", "enum": [ "PRODUCT_UNAVAILABLE", "MARKET_INELIGIBLE" ], "type": "string" }, "selected_depot_availability": { "$ref": "#/components/schemas/productmodel.POSDepotAvailability" }, "selling_product": { "$ref": "#/components/schemas/product.SellingProduct" }, "sku_code": { "type": "string" } }, "required": [ "sku_code", "eligible" ], "type": "object" }, "internal_modules_catalog.POSRefreshRequest": { "additionalProperties": false, "properties": { "sku_codes": { "description": "Exact SKU codes with no surrounding whitespace or control characters. Duplicate entries are rejected.", "items": { "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "sku_codes" ], "type": "object" }, "internal_modules_catalog.POSRefreshResponse": { "properties": { "items": { "description": "Exactly one result per requested SKU, in request order, including explicit removals.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.POSRefreshItem" }, "type": "array" }, "price_evaluated_at": { "format": "date-time", "type": "string" }, "price_generation": { "type": "string" }, "price_next_boundary_at": { "description": "Earliest applicable owner schedule, price-validity or package-effectivity boundary. Refresh by this time and never use an expired price.", "format": "date-time", "type": "string" }, "stock_as_of": { "description": "Original stock observation time; absent when there are no eligible active products. Treat stock older than 30 seconds as unknown while refreshing.", "format": "date-time", "type": "string" } }, "required": [ "items", "price_generation", "price_evaluated_at" ], "type": "object" }, "internal_modules_catalog.POSStoreView": { "properties": { "country_code": { "type": "string" }, "depot_code": { "description": "Authoritative physical depot; equal to store_code.", "type": "string" }, "market_code": { "type": "string" }, "name": { "description": "Depot display name for the register header. Omitted when the depot has no name; clients fall back to depot_code.", "type": "string" }, "store_code": { "description": "Physical depot code supplied as store_code in the request; never an ESL configuration key.", "type": "string" } }, "required": [ "store_code", "depot_code", "market_code", "country_code" ], "type": "object" }, "internal_modules_catalog.ProductManufacturingInput": { "properties": { "company_name": { "type": "string" }, "country_ref": { "$ref": "#/components/schemas/geography.CountryRef" } }, "type": "object" }, "internal_modules_catalog.ProductRecord": { "properties": { "lifecycle_tag_overrides": { "$ref": "#/components/schemas/internal_modules_catalog.LifecycleTagOverrides" }, "purchase_classification": { "enum": [ "merchandise", "stored_value" ], "type": "string" }, "sales_performance": { "$ref": "#/components/schemas/product.SalesPerformanceStats", "description": "Insights-owned evidence returned only by explicit sales selection or ranking; ordinary product reads omit it. Never stored in Supply." }, "stock_tracked": { "description": "Authored inventory flag; absent means stock tracked, false marks a non-stock SKU.", "type": "boolean" }, "storefront_merchandising": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontMerchandising" }, "storefront_sort": { "$ref": "#/components/schemas/internal_modules_catalog.StorefrontSortProjection" } }, "type": "object" }, "internal_modules_catalog.ProductSelectionInput": { "additionalProperties": false, "description": "Create body. Images are optional at create; publish rules (cover; icon when kind is badge; at least one product) apply whenever the resulting status is published, so a selection cannot be created as published (it has no products yet). The code is generated by the server; a body that names code is rejected (400) as an unknown field.", "properties": { "cover": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Active public media code uploaded to folder selection-cover. Must differ from icon." }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array" }, "display_order": { "default": 0, "minimum": 0, "type": "integer" }, "icon": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Active public media code uploaded to folder selection-badge-icon." }, "kind": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" }, "name": { "description": "At least one non-empty name.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "minItems": 1, "type": "array" }, "slug": { "description": "Optional. Normalised to lowercase a-z, 0-9 and hyphens. When omitted it is derived from the English (en) name; 400 when neither yields a slug. 409 when already used by any selection, including soft-deleted ones.", "type": "string" }, "status": { "$ref": "#/components/schemas/selection_enums.ProductSelectionStatus", "description": "Defaults to draft." } }, "required": [ "kind", "name" ], "type": "object" }, "internal_modules_catalog.ProductSelectionItemsInput": { "description": "Atomically replaces the whole ordered membership. Array order becomes position (0-based). Every sku_code must name an existing product; an unknown or duplicate code answers 400 and leaves membership unchanged. An empty list is allowed unless the selection is published (members_required).", "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "sku_codes": { "items": { "type": "string" }, "maxItems": 200, "type": "array", "uniqueItems": true } }, "required": [ "expected_revision", "sku_codes" ], "type": "object" }, "internal_modules_catalog.ProductSelectionOrderInput": { "description": "Every published, non-deleted selection of one kind, in the new display order. The selections are renumbered 1..N in one transaction and each revision is incremented. Items naming anything other than exactly that set (a draft, archived, deleted, unknown or other-kind selection, or omitting one) answer 409 CONFLICT with details.reason order_set_mismatch and details.unexpected_code or details.missing_code. Any stale expected_revision answers 409 CONFLICT with details.code. Nothing changes on any error.", "properties": { "items": { "description": "In display order; the first item gets display_order 1.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSelectionOrderItem" }, "type": "array" }, "kind": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" } }, "required": [ "kind", "items" ], "type": "object" }, "internal_modules_catalog.ProductSelectionOrderItem": { "properties": { "code": { "pattern": "^[A-Z0-9]{8}$", "type": "string" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "code", "expected_revision" ], "type": "object" }, "internal_modules_catalog.ProductSelectionPatch": { "description": "Partial update guarded by expected_revision (409 CONFLICT when stale). Absent fields are unchanged. The merged result is validated as a whole, including the publish rules when the resulting status is published (400 VALIDATION_ERROR with details.reason cover_required, icon_required or members_required).", "properties": { "clear_cover": { "description": "Removes the cover. Rejected while the result is published.", "type": "boolean" }, "clear_icon": { "description": "Removes the icon. Rejected while the result is a published badge.", "type": "boolean" }, "cover": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Replaces the cover (folder selection-cover). Must not be combined with clear_cover." }, "description": { "description": "Replaces all descriptions; an empty array clears them.", "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array" }, "display_order": { "description": "Moving an already published selection onto the display_order of another published, non-deleted selection of the same kind answers 409 CONFLICT (details.field display_order); reorder published selections with PUT /product-selections/order. When a selection enters the published set of a kind (publishing, or changing kind while published) and its resulting display_order is taken there, it is placed after the last published selection of that kind (N+1) instead.", "minimum": 0, "type": "integer" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "icon": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Replaces the icon (folder selection-badge-icon). Must not be combined with clear_icon." }, "kind": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" }, "name": { "description": "Replaces all names; at least one non-empty name.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "minItems": 1, "type": "array" }, "slug": { "description": "Accepted only while the stored status is draft; a different slug while published or archived answers 400 (unpublish to draft first). Sending the current slug is a no-op.", "type": "string" }, "status": { "$ref": "#/components/schemas/selection_enums.ProductSelectionStatus" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_catalog.ProductSupplierInput": { "properties": { "code": { "type": "string" }, "name": { "description": "Name is accepted only so an authored value can be rejected explicitly;\nit is never persisted as supplier truth.", "type": "string" } }, "type": "object" }, "internal_modules_catalog.ProductSupplyInput": { "properties": { "manufacturing": { "$ref": "#/components/schemas/internal_modules_catalog.ProductManufacturingInput" }, "suppliers": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSupplierInput" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.PurchaseOrderProductReview": { "properties": { "acknowledged_at": { "format": "date-time", "type": "string" }, "acknowledged_by": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "id": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "product_id": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "enum": [ "pending", "acknowledged" ], "type": "string" } }, "required": [ "id", "product_id", "sku_code", "sku_series_code", "name", "other_names", "status", "created_at", "created_by" ], "type": "object" }, "internal_modules_catalog.PurchaseOrderProductReviewPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.PurchaseOrderProductReview" }, "type": "array" }, "next_after": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } }, "required": [ "items" ], "type": "object" }, "internal_modules_catalog.ReserveSKUCodeInput": { "properties": { "sku": { "description": "Existing series code, trimmed and uppercased to nonempty ASCII letters and digits with no fixed length. Suggestions append exactly four digits, 0001 through 9999; exhausted series cannot allocate another code.", "minLength": 1, "type": "string" } }, "required": [ "sku" ], "type": "object" }, "internal_modules_catalog.SKUCodeReservation": { "properties": { "created_at": { "type": "string" }, "last_heartbeat_at": { "type": "string" }, "lease_expires_at": { "type": "string" }, "reservation_id": { "type": "string" }, "sku": { "type": "string" }, "sku_code": { "description": "Complete series code followed by exactly four sequence digits. The lease is bound to this full code, series, actor, and expiry; allocated codes are never reused.", "type": "string" } }, "type": "object" }, "internal_modules_catalog.SKUInput": { "properties": { "code": { "description": "Trimmed and uppercased on creation; must contain one or more ASCII letters or digits, with no fixed length. Existing series codes remain immutable on update.", "minLength": 1, "type": "string" }, "other_names": { "description": "Exactly two nonempty translations in canonical order, zh-TW then zh-CN.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "maxItems": 2, "minItems": 2, "type": "array", "uniqueItems": false }, "primary_name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" } }, "required": [ "code", "primary_name", "other_names", "storage_type" ], "type": "object" }, "internal_modules_catalog.SetImagesInput": { "properties": { "cover_media_code": { "type": "string" }, "detail_images": { "anyOf": [ { "items": { "$ref": "#/components/schemas/internal_modules_catalog.DetailImageInput" }, "type": "array" }, { "type": "null" } ], "description": "Replaces product detail images when present; null clears the collection." }, "expected_revision": { "description": "Optional optimistic-concurrency token: the product revision the\ncaller last read. When present and different from the stored\nrevision the replacement answers 409 with details.reason_code\nPRODUCT_REVISION_STALE, details.expected_revision and\ndetails.current_revision. Omit to keep today's behaviour.", "format": "int64", "minimum": 1, "type": "integer" }, "image_media_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.StorefrontBrandSummary": { "properties": { "active_product_count": { "type": "integer" }, "id": { "type": "string" }, "logo_url": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.StorefrontSortProjection": { "description": "StorefrontSort carries the derived storefront sort keys behind the\nstorefront_restocked_sort index and the RESTOCKED lifecycle tag.\nMaintained on-write; never customer-visible raw.", "properties": { "last_restocked_at": { "description": "LastRestockedAt is the most recent 0→positive availability transition\nacross customer-accessible standard locations ($max, monotonic).", "type": "string" } }, "type": "object" }, "internal_modules_catalog.UpdateInput": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/product.ProductBarcodeAssignment" }, "type": "array", "uniqueItems": false }, "brand_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "category_tags": { "description": "CategoryTags replaces the tag list wholesale when present.", "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/classification.CollectionRef", "description": "Omit to keep the stored collection. When the product has no stored\ncollection and every category tag belongs to the same collection, the\nserver infers it." }, "country_of_origin": { "anyOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontOrigin" }, { "type": "null" } ], "description": "Omit to preserve the stored origin, null to clear it, a value to replace it." }, "cover_media_code": { "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "detail_images": { "anyOf": [ { "items": { "$ref": "#/components/schemas/internal_modules_catalog.DetailImageInput" }, "type": "array" }, { "type": "null" } ], "description": "Replaces product detail images when present; null clears the collection." }, "expected_revision": { "description": "Optional optimistic-concurrency token: the product revision the\ncaller last read (product.revision). When present and different\nfrom the stored revision the patch answers 409 with\ndetails.reason_code PRODUCT_REVISION_STALE,\ndetails.expected_revision and details.current_revision, and nothing\nis written. Zero or negative values answer 400. Omit to keep today's\nserver-observed concurrency guards only.", "format": "int64", "minimum": 1, "type": "integer" }, "image_media_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "name": { "description": "Replaces the primary display name when present; it must not be\nblank. It may be in any language; it is stored in the \"en\" slot of\nthe product name, and translations go in other_names.", "type": "string" }, "net_content": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_catalog.NetContentInput" }, { "type": "null" } ], "description": "Omit to preserve, null to clear; exact positive same-dimension measures from the closed unit vocabulary when present." }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "type": "array", "uniqueItems": false }, "purchase_classification": { "description": "Explicitly replace the classification; omission leaves it unchanged.", "enum": [ "merchandise", "stored_value" ], "type": "string" }, "status": { "type": "string" }, "stock_tracked": { "description": "Set the authored inventory flag; false marks a non-stock SKU. Omission leaves it unchanged.", "type": "boolean" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType", "description": "Omit to preserve product storage. A supplied valid value replaces the authoritative product storage and may differ from its SKU-series default." }, "supply": { "$ref": "#/components/schemas/internal_modules_catalog.nullableField-internal_modules_catalog_ProductSupplyInput" } }, "type": "object" }, "internal_modules_catalog.approvedStorefrontProduct": { "properties": { "audience": { "$ref": "#/components/schemas/market_enums.PriceAudience" }, "availability": { "$ref": "#/components/schemas/inventory.ProductStockSummary" }, "barcode_assignments": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot" }, "type": "array", "uniqueItems": false }, "brands": { "items": { "$ref": "#/components/schemas/classification.BrandRef" }, "type": "array", "uniqueItems": false }, "category_tag_details": { "description": "Category display names resolved from current masters at read time; unknown codes remain in category_tags.", "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCategoryTagDetail" }, "type": "array" }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/classification.CollectionRef" }, "commercial": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCommercial" }, "country_of_origin": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontOrigin" }, "cover_url": { "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "detail_images": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.DetailImage" }, "type": "array", "uniqueItems": false }, "image_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "listing_policy": { "$ref": "#/components/schemas/productmodel.ListingPolicy" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "package_options": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "type": "array", "uniqueItems": false }, "package_price": { "$ref": "#/components/schemas/internal_modules_catalog.approvedWholesalePackagePrice" }, "place_availability": { "items": { "$ref": "#/components/schemas/inventory.StorefrontPlaceAvailability" }, "type": "array", "uniqueItems": false }, "price_availability": { "$ref": "#/components/schemas/productmodel.PriceAvailability" }, "sales_performance": { "$ref": "#/components/schemas/product.SalesPerformanceStats" }, "selling_product": { "$ref": "#/components/schemas/product.SellingProduct" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "storefront_display": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontDisplay" }, "supply": { "$ref": "#/components/schemas/classification.ProductSupply" }, "wholesale_mode": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.WholesalePriceMode" } }, "required": [ "package_price" ], "type": "object" }, "internal_modules_catalog.approvedStorefrontProductBatchResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProduct" }, "type": "array", "uniqueItems": false }, "missing_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.approvedStorefrontProductPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProduct" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "internal_modules_catalog.approvedWholesalePackagePrice": { "description": "Exact whole-package price and increment for an approved wholesale product.", "properties": { "base_units_increment": { "format": "int64", "minimum": 1, "type": "integer" }, "effective_amount": { "$ref": "#/components/schemas/money.Money" }, "handling_unit": { "enum": [ "CASE" ], "type": "string" }, "package_count_increment": { "enum": [ 1 ], "format": "int64", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "regular_amount": { "$ref": "#/components/schemas/money.Money" }, "units_per_package": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "package_option", "handling_unit", "units_per_package", "package_count_increment", "base_units_increment", "regular_amount", "effective_amount" ], "type": "object" }, "internal_modules_catalog.barcodeLookupView": { "properties": { "assignment": { "$ref": "#/components/schemas/product.ProductBarcodeAssignment" }, "package_option": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "product": { "$ref": "#/components/schemas/internal_modules_catalog.productView" } }, "type": "object" }, "internal_modules_catalog.categoryLeaderboardAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.categoryLeaderboardItem" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_catalog.categoryLeaderboardItem": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "net_units": { "minimum": 1, "type": "integer" }, "paid_order_count": { "minimum": 1, "type": "integer" }, "product": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProduct" }, "rank": { "minimum": 1, "type": "integer" }, "timezone": { "type": "string" }, "window": { "enum": [ "7d" ], "type": "string" }, "window_days": { "enum": [ 7 ], "type": "integer" } }, "type": "object" }, "internal_modules_catalog.categoryProductOrderAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.categoryProductOrderView" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.categoryProductOrderItemView": { "description": "One product in a category's order. product is null when the SKU no longer resolves to a product.", "properties": { "added_at": { "description": "When the product joined the category. Products tagged before ordering existed report their created_at.", "format": "date-time", "type": "string" }, "position": { "minimum": 0, "type": "integer" }, "product": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_catalog.categoryProductSummary" }, { "type": "null" } ] }, "sku_code": { "type": "string" } }, "required": [ "sku_code", "position", "added_at", "product" ], "type": "object" }, "internal_modules_catalog.categoryProductOrderView": { "properties": { "products": { "description": "The complete list, ordered by position ascending.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.categoryProductOrderItemView" }, "type": "array" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "revision", "products" ], "type": "object" }, "internal_modules_catalog.categoryProductSummary": { "description": "Current product facts for one row of a category's product order.", "properties": { "available_stock_units": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ], "description": "Sellable stock units across all depots (good, sellable, not on expiry hold or online staging, on hand minus reserved, floored at 0). null when the SKU has no sellable stock bucket or stock evidence is unavailable." }, "cover": { "$ref": "#/components/schemas/security.ObjectMedia", "description": "Product cover image; omitted when the product has none." }, "created_at": { "format": "date-time", "type": "string" }, "last30_days_net_units": { "anyOf": [ { "format": "int64", "type": "integer" }, { "type": "null" } ], "description": "Net units sold in the last 30 days (Insights, staff channel, market_code or the default market). null when sales evidence is unavailable." }, "names": { "description": "Primary product name first, followed by its other localized names.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "names", "status", "created_at", "updated_at", "last30_days_net_units", "available_stock_units" ], "type": "object" }, "internal_modules_catalog.categoryTagOrderAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.categoryTagOrderView" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.categoryTagOrderView": { "properties": { "items": { "description": "Every category tag of the collection, ordered by display_order.", "items": { "$ref": "#/components/schemas/classification.CategoryTag" }, "type": "array" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "revision", "items" ], "type": "object" }, "internal_modules_catalog.collectionOrderAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.collectionOrderView" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.collectionOrderView": { "properties": { "items": { "description": "Every collection with its category tags, ordered by display_order.", "items": { "$ref": "#/components/schemas/classification.Collection" }, "type": "array" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "revision", "items" ], "type": "object" }, "internal_modules_catalog.internalProductQueryAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.InternalProductQueryResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_catalog.nullableField-int64": { "properties": { "set": { "type": "boolean" }, "value": { "type": "integer" } }, "type": "object" }, "internal_modules_catalog.nullableField-internal_modules_catalog_ProductSupplyInput": { "properties": { "set": { "type": "boolean" }, "value": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSupplyInput" } }, "type": "object" }, "internal_modules_catalog.posStoreAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.POSStoreView" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.preorderPolicyInput": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "enabled": { "type": "boolean" }, "ends_at": { "type": "string" }, "expected_available_at": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "max_quantity_per_customer": { "type": "integer" }, "max_quantity_per_order": { "type": "integer" }, "schedule_timezone": { "type": "string" }, "starts_at": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.productBrandDisplay": { "properties": { "code": { "type": "string" }, "id": { "type": "string" }, "logo": { "$ref": "#/components/schemas/security.ObjectMedia" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.productSelectionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/selection.ProductSelection" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.productSelectionItemView": { "description": "A membership item with its product summary. product is null when the member SKU no longer resolves to a product.", "properties": { "position": { "minimum": 0, "type": "integer" }, "product": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionProductSummary" }, { "type": "null" } ] }, "selection_code": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "selection_code", "sku_code", "position", "product" ], "type": "object" }, "internal_modules_catalog.productSelectionItemsAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionItemsView" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.productSelectionItemsView": { "properties": { "items": { "description": "Ordered by position ascending.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionItemView" }, "maxItems": 200, "type": "array" }, "selection": { "$ref": "#/components/schemas/selection.ProductSelection" } }, "required": [ "selection", "items" ], "type": "object" }, "internal_modules_catalog.productSelectionListAPIResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/selection.ProductSelection" }, "type": "array" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.productSelectionPageAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/selection.ProductSelection" }, "type": "array" }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.productSelectionProductSummary": { "description": "Current product facts for an admin membership row.", "properties": { "cover": { "$ref": "#/components/schemas/security.ObjectMedia", "description": "Product cover image; omitted when the product has none." }, "name": { "description": "Primary product name first, followed by its other localized names.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "sku_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" } }, "required": [ "sku_code", "name", "status" ], "type": "object" }, "internal_modules_catalog.productSupplierDisplay": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "internal_modules_catalog.productView": { "properties": { "brand_details": { "description": "Master-backed display projections are response-only. Persisted Product\nrelationships remain code-only under the current contract.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.productBrandDisplay" }, "type": "array", "uniqueItems": false }, "category_tag_details": { "items": { "$ref": "#/components/schemas/classification.CategoryTag" }, "type": "array", "uniqueItems": false }, "collection_details": { "$ref": "#/components/schemas/classification.Collection" }, "commercial": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCommercial" }, "display_status": { "description": "DisplayStatus is the computed read-time merge of status + recency +\nstock (new/restocked/out_of_stock/active). Never stored.", "type": "string" }, "lifecycle_tag_overrides": { "$ref": "#/components/schemas/internal_modules_catalog.LifecycleTagOverrides" }, "lifecycle_tags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "listing_policy": { "$ref": "#/components/schemas/productmodel.ListingPolicy" }, "new_expires_at": { "type": "string" }, "sales_performance": { "$ref": "#/components/schemas/product.SalesPerformanceStats", "description": "Insights-owned evidence returned only by explicit sales selection or ranking; ordinary product reads omit it. Never stored in Supply." }, "storefront_display": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontDisplay" }, "storefront_merchandising": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontMerchandising" }, "storefront_sort": { "$ref": "#/components/schemas/internal_modules_catalog.StorefrontSortProjection" }, "supplier_details": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.productSupplierDisplay" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.soonExpiryPolicyInput": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "enabled": { "type": "boolean" }, "ends_at": { "type": "string" }, "labels": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "show_exact_expiry_date": { "description": "Whether storefront_display.expiry shows the exact date while this policy is enabled and open. Without an open policy the exact date is shown.", "type": "boolean" }, "starts_at": { "type": "string" }, "window_days": { "description": "Optional; 0 or 30, stored as 30. It no longer decides when a product shows storefront_display.expiry. The display window is the effective soon-expiry lead days of the market listing (Pricing expiry_lead_days_override, else the market's expiry_lead_days, else 30), and the display is shown whether or not this policy is enabled; an enabled, open policy only supplies labels, descriptions and show_exact_expiry_date.", "type": "integer" } }, "type": "object" }, "internal_modules_catalog.storefrontBrandSummaryAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontBrandSummaryPage" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_catalog.storefrontBrandSummaryPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.StorefrontBrandSummary" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "type": "object" }, "internal_modules_catalog.storefrontCategoryTag": { "properties": { "code": { "description": "Immutable category tag relationship code, independent of its ID and public slug.", "type": "string" }, "collection_code": { "type": "string" }, "collection_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "slug": { "type": "string" } }, "required": [ "code" ], "type": "object" }, "internal_modules_catalog.storefrontCollection": { "properties": { "category_tags": { "items": { "properties": { "active_product_count": { "description": "Distinct active products the resolved market lists under this collection and tag. Present only when market_code or exclude_empty_tags was sent; never on product payloads.", "format": "int64", "minimum": 0, "type": "integer" }, "code": { "description": "Immutable category tag relationship code, usable as category_code in product rankings.", "type": "string" }, "collection_code": { "type": "string" }, "collection_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "slug": { "type": "string" } }, "required": [ "id", "code", "name", "collection_code", "collection_name" ], "type": "object" }, "type": "array" }, "code": { "description": "Stable collection business code, independent of translated names and public slug.", "example": "COL0001", "type": "string" }, "icon": { "$ref": "#/components/schemas/security.ObjectMedia" }, "id": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "slug": { "description": "Public collection filter value; may contain Unicode characters.", "type": "string" } }, "required": [ "id", "code", "name", "category_tags" ], "type": "object" }, "internal_modules_catalog.storefrontCollectionRef": { "properties": { "code": { "type": "string" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.storefrontMerchandisingInput": { "properties": { "preorder": { "$ref": "#/components/schemas/internal_modules_catalog.preorderPolicyInput" }, "soon_expiry": { "$ref": "#/components/schemas/internal_modules_catalog.soonExpiryPolicyInput" } }, "type": "object" }, "internal_modules_catalog.storefrontProduct": { "properties": { "audience": { "$ref": "#/components/schemas/market_enums.PriceAudience" }, "availability": { "$ref": "#/components/schemas/inventory.ProductStockSummary" }, "barcode_assignments": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot" }, "type": "array", "uniqueItems": false }, "brands": { "items": { "$ref": "#/components/schemas/classification.BrandRef" }, "type": "array", "uniqueItems": false }, "category_tag_details": { "description": "Category display names resolved from current masters at read time; unknown codes remain in category_tags.", "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCategoryTagDetail" }, "type": "array" }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/classification.CollectionRef" }, "commercial": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontCommercial" }, "country_of_origin": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontOrigin" }, "cover_url": { "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "detail_images": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.DetailImage" }, "type": "array", "uniqueItems": false }, "image_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "lifecycle_tags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "listing_policy": { "$ref": "#/components/schemas/productmodel.ListingPolicy" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "new_expires_at": { "type": "string" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "type": "array", "uniqueItems": false }, "place_availability": { "items": { "$ref": "#/components/schemas/inventory.StorefrontPlaceAvailability" }, "type": "array", "uniqueItems": false }, "price_availability": { "$ref": "#/components/schemas/productmodel.PriceAvailability" }, "rating_summary": { "$ref": "#/components/schemas/review.RatingSummary" }, "sales_performance": { "$ref": "#/components/schemas/product.SalesPerformanceStats" }, "selling_product": { "$ref": "#/components/schemas/product.SellingProduct" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "storefront_display": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontDisplay" }, "supply": { "$ref": "#/components/schemas/classification.ProductSupply" }, "wholesale_mode": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.WholesalePriceMode" } }, "type": "object" }, "internal_modules_catalog.storefrontProductBatchRequest": { "properties": { "sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "sku_codes" ], "type": "object" }, "internal_modules_catalog.storefrontProductBatchResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProduct" }, "type": "array", "uniqueItems": false }, "missing_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_catalog.storefrontProductPageAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProduct" }, "type": "array" }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.storefrontProductSelection": { "description": "Public projection of a published selection. No status, revision or audit fields.", "properties": { "code": { "example": "7KQ2M9XA", "pattern": "^[A-Z0-9]{8}$", "type": "string" }, "cover": { "$ref": "#/components/schemas/security.ObjectMedia" }, "description": { "description": "Omitted when empty.", "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array" }, "display_order": { "type": "integer" }, "icon": { "$ref": "#/components/schemas/security.ObjectMedia", "description": "Always present for badge selections; present for a section only when one is set." }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "products": { "description": "Present only on the list endpoint when preview_limit \u003e 0. Up to preview_limit products eligible in the requested market, in curated order. May be empty.", "items": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProduct" }, "type": "array" }, "slug": { "type": "string" }, "total_products": { "description": "Present only when products is present. Number of members eligible in the requested market.", "minimum": 0, "type": "integer" } }, "required": [ "id", "code", "slug", "kind", "name", "cover", "display_order" ], "type": "object" }, "internal_modules_catalog.storefrontProductSelectionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductSelection" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.storefrontProductSelectionPageAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductSelection" }, "type": "array" }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_catalog.topPickItem": { "properties": { "net_units": { "type": "integer" }, "paid_order_count": { "type": "integer" }, "product": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProduct" }, "rank": { "type": "integer" }, "window_days": { "type": "integer" } }, "type": "object" }, "internal_modules_catalog.topPicksResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.topPickItem" }, "type": "array", "uniqueItems": false }, "window_days": { "type": "integer" } }, "type": "object" }, "internal_modules_catalog.wholesaleStorefrontProduct": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductBarcodeAssignmentSnapshot" }, "type": "array", "uniqueItems": false }, "brands": { "items": { "$ref": "#/components/schemas/classification.BrandRef" }, "type": "array", "uniqueItems": false }, "category_tags": { "items": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontCategoryTag" }, "type": "array", "uniqueItems": false }, "collection": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontCollectionRef" }, "cover_url": { "type": "string" }, "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "detail_images": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.DetailImage" }, "type": "array", "uniqueItems": false }, "image_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "lifecycle_tags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "listing_policy": { "$ref": "#/components/schemas/productmodel.ListingPolicy" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "new_expires_at": { "type": "string" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.ProductPackageOptionSnapshot" }, "type": "array", "uniqueItems": false }, "sales_performance": { "$ref": "#/components/schemas/product.SalesPerformanceStats" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "storefront_display": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.StorefrontDisplay" } }, "type": "object" }, "internal_modules_costs.AcquisitionAdvice": { "properties": { "available": { "type": "boolean" }, "candidates": { "items": { "$ref": "#/components/schemas/internal_modules_costs.AcquisitionCandidate" }, "type": "array" }, "candidates_truncated": { "description": "True when more than the latest 200 acquisition candidates exist.", "type": "boolean" }, "current": { "$ref": "#/components/schemas/internal_modules_costs.BaseAcquisitionCostRecord" }, "revision": { "format": "int64", "type": "integer" } }, "required": [ "revision", "available", "candidates", "candidates_truncated" ], "type": "object" }, "internal_modules_costs.AcquisitionCandidate": { "properties": { "active": { "type": "boolean" }, "adjustments": { "items": { "$ref": "#/components/schemas/internal_modules_netgoods.FinancialAdjustment" }, "type": "array" }, "confirmed_at": { "format": "date-time", "type": "string" }, "currency": { "type": "string" }, "id": { "type": "string" }, "invoice_id": { "type": "string" }, "invoice_revision": { "format": "int64", "type": "integer" }, "issue_date": { "type": "string" }, "sku_code": { "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/procurement.NetGoodsCostSourceSnapshot" }, "type": "array" } }, "required": [ "id", "invoice_id", "sku_code", "currency", "issue_date", "confirmed_at", "invoice_revision", "active", "sources" ], "type": "object" }, "internal_modules_costs.BaseAcquisitionCostRecord": { "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "amount_includes_tax": { "description": "Present and true only when the amount was entered tax-inclusive; amount is always tax-exclusive.", "type": "boolean" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "currency": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "effective_from": { "format": "date-time", "type": "string" }, "entered_amount_minor": { "description": "Tax-inclusive amount as entered.", "format": "int64", "type": "integer" }, "financial_adjustments": { "items": { "$ref": "#/components/schemas/internal_modules_netgoods.FinancialAdjustment" }, "type": "array" }, "id": { "type": "string" }, "manual_lock": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "source_id": { "type": "string" }, "source_type": { "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/procurement.NetGoodsCostSourceSnapshot" }, "type": "array" }, "tax_category_code": { "description": "Tax category whose rate netted the tax off.", "type": "string" }, "tax_minor": { "description": "Tax portion netted off; entered_amount_minor minus amount.amount_minor.", "format": "int64", "type": "integer" }, "tax_rate_denominator": { "format": "int64", "type": "integer" }, "tax_rate_numerator": { "format": "int64", "type": "integer" }, "unavailable": { "type": "boolean" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "sku_code", "currency", "amount", "revision", "effective_from", "created_at", "updated_at" ], "type": "object" }, "internal_modules_costs.PackageAdvice": { "additionalProperties": false, "properties": { "available": { "type": "boolean" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "evaluated_at": { "format": "date-time", "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "selected_package_cost": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "available", "package_option", "currency_exponent", "evaluated_at" ], "type": "object" }, "internal_modules_costs.PackageAdviceInput": { "additionalProperties": false, "properties": { "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" } }, "required": [ "package_option" ], "type": "object" }, "internal_modules_costs.ReceiptCostInput": { "properties": { "accepted_loose_base_units": { "type": "integer" }, "accepted_pack_count": { "description": "Accepted quantity, expressed the way the supplier delivered it. Packs\nexpand using the composition CAPTURED here, never today's catalogue.", "type": "integer" }, "base_units_per_pack": { "type": "integer" }, "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "depot_code": { "type": "string" }, "duty_minor": { "type": "integer" }, "freight_minor": { "type": "integer" }, "gross_cost_minor": { "type": "integer" }, "idempotency_key": { "type": "string" }, "receipt_id": { "type": "string" }, "recoverable_tax_minor": { "type": "integer" }, "rejected_base_units": { "type": "integer" }, "sku_code": { "type": "string" } }, "required": [ "currency", "depot_code", "idempotency_key", "receipt_id", "sku_code" ], "type": "object" }, "internal_modules_costs.RecordCostInput": { "properties": { "amount_includes_tax": { "description": "When true, amount_minor is tax-inclusive and Supply stores amount = round_half_up(amount_minor × tax_rate_denominator / (tax_rate_denominator + tax_rate_numerator)), recording the entered amount, rate and tax portion on the record. tax_category_code, tax_rate_numerator and tax_rate_denominator are then required; a missing or invalid rate is rejected with 400 and details.reason_code TAX_CATEGORY_REQUIRED, TAX_RATE_REQUIRED or TAX_RATE_INVALID. When false or absent, amount_minor is stored as given and the three tax fields must be absent (reason_code TAX_TREATMENT_WITHOUT_INCLUSIVE_AMOUNT).", "type": "boolean" }, "amount_minor": { "description": "Tax-exclusive acquisition cost in minor units, or the tax-inclusive figure as entered when amount_includes_tax is true.", "type": "integer" }, "currency": { "type": "string" }, "effective_from": { "type": "string" }, "expected_revision": { "type": "integer" }, "reason": { "description": "Required audited reason; establishes a manual acquisition-cost lock.", "minLength": 1, "type": "string" }, "sku_code": { "type": "string" }, "source_id": { "type": "string" }, "source_type": { "type": "string" }, "tax_category_code": { "description": "Tax category whose in-force rate the caller used, for example GST.", "type": "string" }, "tax_rate_denominator": { "description": "Rate denominator.", "format": "int64", "minimum": 1, "type": "integer" }, "tax_rate_numerator": { "description": "Rate numerator; 1 with denominator 10 is 10 percent.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "currency", "sku_code", "reason" ], "type": "object" }, "internal_modules_costs.ReleaseCostLockInput": { "properties": { "expected_revision": { "format": "int64", "type": "integer" }, "reason": { "type": "string" } }, "required": [ "expected_revision", "reason" ], "type": "object" }, "internal_modules_costs.SupplierReturnInput": { "properties": { "currency": { "type": "string" }, "depot_code": { "type": "string" }, "idempotency_key": { "type": "string" }, "return_id": { "type": "string" }, "returned_base_units": { "type": "integer" }, "reverses_movement_id": { "description": "ReversesMovementID is REQUIRED. A return reverses the receipt it came\nfrom, so an unlinked return has nothing to reverse and is refused.", "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "currency", "depot_code", "idempotency_key", "return_id", "returned_base_units", "reverses_movement_id", "sku_code" ], "type": "object" }, "internal_modules_costs.TransferCostInput": { "properties": { "base_units": { "type": "integer" }, "currency": { "type": "string" }, "destination_depot_code": { "type": "string" }, "idempotency_key": { "type": "string" }, "reference_id": { "type": "string" }, "sku_code": { "type": "string" }, "source_depot_code": { "type": "string" } }, "required": [ "base_units", "currency", "idempotency_key", "reference_id", "sku_code", "source_depot_code" ], "type": "object" }, "internal_modules_courier.AvailabilityMapping": { "additionalProperties": false, "description": "Disjoint scalar exact matches. Unknown/malformed value fails; never treats malformed data as empty availability.", "properties": { "available_values": { "items": {}, "maxItems": 32, "minItems": 1, "type": "array" }, "unavailable_values": { "items": {}, "maxItems": 32, "minItems": 1, "type": "array" }, "value": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" } }, "required": [ "value", "available_values", "unavailable_values" ], "type": "object" }, "internal_modules_courier.BookingInput": { "additionalProperties": false, "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "buyer_type": { "type": "string" }, "container_count": { "maximum": 99, "minimum": 1, "type": "integer" }, "delivery_date": { "format": "date", "type": "string" }, "delivery_type": { "maxLength": 128, "type": "string" }, "instructions": { "maxLength": 1024, "type": "string" }, "order_number": { "maxLength": 64, "type": "string" }, "production_date": { "format": "date", "type": "string" }, "recipient": { "$ref": "#/components/schemas/party.Recipient" }, "time_window_end": { "type": "string" }, "time_window_start": { "type": "string" } }, "required": [ "order_number", "container_count", "recipient", "address" ], "type": "object" }, "internal_modules_courier.BookingLookup": { "additionalProperties": false, "description": "Optional GET re-query used by the carrier-booking sweeper; inputs order_number and sandbox only.", "properties": { "endpoint": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "headers": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "not_found_statuses": { "items": { "maximum": 499, "minimum": 400, "type": "integer" }, "maxItems": 16, "minItems": 1, "type": "array" }, "path": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "query": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "reference": { "$ref": "#/components/schemas/internal_modules_courier.BookingReference" }, "timeout_ms": { "maximum": 12000, "minimum": 0, "type": "integer" } }, "required": [ "endpoint", "reference", "not_found_statuses" ], "type": "object" }, "internal_modules_courier.BookingMatch": { "additionalProperties": false, "description": "Matches a 4xx answer whose lower-cased text under paths contains a term of every text_all_of group.", "properties": { "paths": { "items": { "type": "string" }, "maxItems": 16, "minItems": 1, "type": "array" }, "statuses": { "items": { "maximum": 499, "minimum": 400, "type": "integer" }, "maxItems": 16, "minItems": 1, "type": "array" }, "text_all_of": { "items": { "items": { "type": "string" }, "type": "array" }, "maxItems": 8, "minItems": 1, "type": "array" } }, "required": [ "statuses", "paths", "text_all_of" ], "type": "object" }, "internal_modules_courier.BookingReadiness": { "additionalProperties": false, "properties": { "blocking_reason": { "description": "The refusal reason live booking would return first; empty when ready.", "enum": [ "", "company_disabled", "booking_not_configured", "sandbox_test_required", "configuration_invalid", "credential_revoked" ], "type": "string" }, "booking_configured": { "description": "The current revision has a booking_request.", "type": "boolean" }, "credential_revoked": { "description": "The bound credential version is revoked; false when none is bound.", "type": "boolean" }, "enabled": { "description": "The company is enabled.", "type": "boolean" }, "ready": { "description": "Every live-booking gate that does not depend on the order passes; exactly what live booking accepts.", "type": "boolean" }, "sandbox_test_passed": { "description": "A passed sandbox test booking covers the current booking fingerprint (or, for a receipt recorded before fingerprints, the exact current revision and credential version).", "type": "boolean" } }, "required": [ "enabled", "booking_configured", "sandbox_test_passed", "credential_revoked", "ready", "blocking_reason" ], "type": "object" }, "internal_modules_courier.BookingReference": { "additionalProperties": false, "properties": { "fallback_input": { "type": "string" }, "value": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" } }, "required": [ "value" ], "type": "object" }, "internal_modules_courier.BookingRequest": { "additionalProperties": false, "description": "Revisioned carrier booking request (booking purpose). Inputs: order_number, container_count, container_number (inside per_container only), delivery_date, time_window_start, time_window_end, instructions, delivery_type, buyer_type, production_date, recipient_name, recipient_phone, recipient_email, line1, line2, locality, state_code, state_name, postal_code, country_code, sandbox (\"true\" or \"false\"). Booking-only expression sources: per_container, join (with separator), coalesce, and a text map. Validated when saved; live booking requires a passed sandbox test booking for the current booking fingerprint of the company: this booking_request (lookup included), the bound credential version and the values of the non-sensitive settings it reads. Saves that change none of these (enabled, name, default_instructions, policy, slot_request or custom metadata) keep the receipt valid; a configuration write that stores a new credential version does not.", "properties": { "body": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "endpoint": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "headers": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "lookup": { "$ref": "#/components/schemas/internal_modules_courier.BookingLookup" }, "method": { "enum": [ "POST", "PUT", "PATCH" ], "type": "string" }, "path": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "query": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "type": "array" }, "response": { "$ref": "#/components/schemas/internal_modules_courier.BookingResponseMapping" }, "sandbox_endpoint": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "sent_values": { "additionalProperties": false, "description": "JSON pointers into the built request body locating the values written back onto the shipments' latest_carrier_booking. box_count may point at an array (its length) or a number.", "properties": { "box_count": { "type": "string" }, "delivery_date": { "type": "string" }, "delivery_type": { "type": "string" }, "instructions": { "type": "string" }, "intake_date": { "type": "string" }, "time_window_end": { "type": "string" }, "time_window_start": { "type": "string" } }, "type": "object" }, "timeout_ms": { "maximum": 12000, "minimum": 0, "type": "integer" } }, "required": [ "endpoint", "sandbox_endpoint", "method", "body", "response" ], "type": "object" }, "internal_modules_courier.BookingResponseMapping": { "additionalProperties": false, "description": "2xx is booked with reference; 408, 5xx or an unreadable answer is unreachable (408/504 and carrier timeouts with error code timeout); other answers are checked against already_booked, then errors in order, then rejected as carrier_error (401/403 auth_failed, 429 rate_limited).", "properties": { "already_booked": { "additionalProperties": false, "properties": { "match": { "$ref": "#/components/schemas/internal_modules_courier.BookingMatch" }, "reference": { "$ref": "#/components/schemas/internal_modules_courier.BookingReference" } }, "required": [ "match" ], "type": "object" }, "errors": { "items": { "additionalProperties": false, "properties": { "code": { "$ref": "#/components/schemas/courier_enums.CarrierBookingErrorCode" }, "match": { "$ref": "#/components/schemas/internal_modules_courier.BookingMatch" } }, "required": [ "match", "code" ], "type": "object" }, "maxItems": 32, "type": "array" }, "field_errors": { "additionalProperties": false, "properties": { "field": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" }, "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "items": { "type": "string" } }, "required": [ "items", "field", "fields" ], "type": "object" }, "message": { "items": { "type": "string" }, "maxItems": 8, "type": "array" }, "reference": { "$ref": "#/components/schemas/internal_modules_courier.BookingReference" } }, "required": [ "reference" ], "type": "object" }, "internal_modules_courier.BookingTestFailure": { "additionalProperties": false, "description": "Non-secret summary of the latest failed sandbox booking test for the current booking fingerprint. Never includes an error message, request summary or carrier response body.", "properties": { "configuration_revision": { "description": "Revision the failed test ran on.", "format": "int64", "type": "integer" }, "credential_version": { "description": "Opaque credential version the test ran with; absent when the revision binds none.", "type": "string" }, "diagnostics": { "items": { "$ref": "#/components/schemas/internal_modules_courier.Diagnostic" }, "type": "array" }, "error_code": { "$ref": "#/components/schemas/courier_enums.CarrierBookingErrorCode" }, "error_fields": { "items": { "type": "string" }, "type": "array" }, "http_status": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/courier_enums.CarrierBookingOutcome" }, "tested_at": { "format": "date-time", "type": "string" } }, "required": [ "configuration_revision", "tested_at", "error_fields", "diagnostics" ], "type": "object" }, "internal_modules_courier.BookingTestStatus": { "additionalProperties": false, "description": "Non-secret summary of the passing sandbox booking test that satisfies the live-booking sandbox gate. Never includes an error message, request summary or carrier response body.", "properties": { "configuration_revision": { "description": "Revision the passing test ran on. May be earlier than the current revision when later saves left the booking fingerprint (booking_request, credential version and the settings it reads) unchanged.", "format": "int64", "type": "integer" }, "credential_version": { "description": "Opaque credential version the test ran with; absent when the revision binds none.", "type": "string" }, "passed": { "description": "Always true.", "type": "boolean" }, "test_id": { "type": "string" }, "tested_at": { "format": "date-time", "type": "string" } }, "required": [ "passed", "test_id", "configuration_revision", "tested_at" ], "type": "object" }, "internal_modules_courier.CompanyExecutionInput": { "additionalProperties": false, "properties": { "policy": { "$ref": "#/components/schemas/internal_modules_courier.PolicyReference" }, "rules": { "$ref": "#/components/schemas/internal_modules_courier.RuleContext" } }, "required": [ "policy", "rules" ], "type": "object" }, "internal_modules_courier.CompanyExecutionResult": { "additionalProperties": false, "properties": { "company_code": { "type": "string" }, "configuration_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "expires_at": { "format": "date-time", "type": "string" }, "reason": { "enum": [ "address_required", "invalid_address", "no_coverage", "no_available_slots", "provider_unavailable", "provider_response_invalid", "configuration_unavailable", "configuration_invalid", "company_disabled", "credential_revoked", "test_required", "rule_context_invalid", "quote_expired" ], "type": "string" }, "slots": { "items": { "$ref": "#/components/schemas/internal_modules_courier.DeliverySlot" }, "maxItems": 1000, "type": "array" }, "status": { "enum": [ "available", "unavailable", "failed" ], "type": "string" } }, "required": [ "company_code", "configuration_revision", "status", "slots" ], "type": "object" }, "internal_modules_courier.CompanyRevisionMetadata": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "country_codes": { "items": { "type": "string" }, "type": "array" }, "credential_revoked": { "type": "boolean" }, "credential_version": { "type": "string" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "required_inputs": { "items": { "type": "string" }, "type": "array" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "service_areas": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ServiceArea" }, "type": "array" }, "status": { "enum": [ "draft" ], "type": "string" } }, "required": [ "code", "name", "revision", "enabled", "credential_revoked", "country_codes", "service_areas", "required_inputs", "status" ], "type": "object" }, "internal_modules_courier.CompanyRevisionReference": { "additionalProperties": false, "properties": { "code": { "pattern": "^[a-z0-9][a-z0-9-]{1,31}$", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "code", "revision" ], "type": "object" }, "internal_modules_courier.CompanyRevisionsInput": { "additionalProperties": false, "properties": { "companies": { "items": { "$ref": "#/components/schemas/internal_modules_courier.CompanyRevisionReference" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "companies" ], "type": "object" }, "internal_modules_courier.CompanyRevisionsResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.CompanyRevisionsResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_courier.CompanyRevisionsResult": { "additionalProperties": false, "properties": { "companies": { "items": { "$ref": "#/components/schemas/internal_modules_courier.CompanyRevisionMetadata" }, "type": "array" } }, "required": [ "companies" ], "type": "object" }, "internal_modules_courier.ConfigurationDetail": { "properties": { "booking_request": { "$ref": "#/components/schemas/internal_modules_courier.BookingRequest" }, "booking_test": { "description": "Passing sandbox booking test that satisfies the live-booking sandbox gate for this configuration's booking fingerprint (booking_request, credential version and the settings it reads). Always present; null when live booking would be refused with sandbox_test_required.", "oneOf": [ { "$ref": "#/components/schemas/internal_modules_courier.BookingTestStatus" }, { "type": "null" } ] }, "booking_test_failure": { "description": "Latest failed sandbox booking test for the current booking fingerprint. Always present; null unless that failure is newer than the passing test, or no passing test exists.", "oneOf": [ { "$ref": "#/components/schemas/internal_modules_courier.BookingTestFailure" }, { "type": "null" } ] }, "code": { "type": "string" }, "configuration": { "items": { "$ref": "#/components/schemas/courier.DeliveryCompanyConfigurationEntry" }, "type": "array" }, "credential_revoked": { "type": "boolean" }, "credential_version": { "type": "string" }, "enabled": { "type": "boolean" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "slot_request": { "$ref": "#/components/schemas/internal_modules_courier.SlotRequest" }, "status": { "enum": [ "draft" ], "type": "string" } }, "required": [ "code", "revision", "configuration", "status", "enabled", "credential_revoked", "booking_test", "booking_test_failure" ], "type": "object" }, "internal_modules_courier.ConfigurationDetailResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.ConfigurationDetail" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_courier.ConfigurationRevisionSummary": { "additionalProperties": false, "properties": { "credential_version": { "description": "Opaque credential version bound by this revision; absent when it binds none.", "type": "string" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" }, "saved_at": { "description": "When this revision was saved.", "format": "date-time", "type": "string" }, "saved_by": { "description": "Actor that saved this revision, when recorded.", "type": "string" } }, "required": [ "revision", "saved_at" ], "type": "object" }, "internal_modules_courier.ConfigurationWriteInput": { "additionalProperties": false, "properties": { "booking_request": { "$ref": "#/components/schemas/internal_modules_courier.BookingRequest" }, "configuration": { "items": { "$ref": "#/components/schemas/courier.DeliveryCompanyConfigurationEntry" }, "type": "array" }, "custom_metadata": { "$ref": "#/components/schemas/internal_modules_courier.CustomMetadataPatch" }, "expected_revision": { "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "replace_sensitive_keys": { "description": "Explicitly replace named sensitive entries, including a literal mask value. Omit to preserve existing masked secrets.", "items": { "maxLength": 256, "minLength": 1, "type": "string" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "slot_request": { "$ref": "#/components/schemas/internal_modules_courier.SlotRequest" } }, "required": [ "expected_revision", "idempotency_key" ], "type": "object" }, "internal_modules_courier.ConfiguredSchedule": { "additionalProperties": false, "properties": { "dst_policy": { "enum": [ "reject", "earlier", "later" ], "type": "string" }, "horizon_days": { "maximum": 31, "minimum": 1, "type": "integer" }, "overnight_policy": { "enum": [ "reject", "next_day" ], "type": "string" }, "timezone": { "maxLength": 128, "type": "string" }, "windows": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ScheduleWindow" }, "maxItems": 32, "minItems": 1, "type": "array" } }, "required": [ "timezone", "horizon_days", "windows", "dst_policy", "overnight_policy" ], "type": "object" }, "internal_modules_courier.CredentialState": { "additionalProperties": false, "properties": { "credential_revoked": { "description": "True when the bound credential version has been permanently revoked; false when it has not or no credential is bound. Null (unknown) when the credential revocation status store is unavailable.", "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "credential_version": { "description": "Opaque credential version bound by the current revision; absent when it binds none.", "type": "string" }, "revision": { "description": "Current configuration revision.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "revision", "credential_revoked" ], "type": "object" }, "internal_modules_courier.CustomMetadataPatch": { "additionalProperties": false, "properties": { "remove": { "items": { "pattern": "^[a-z][a-z0-9_-]{0,63}$", "type": "string" }, "maxItems": 64, "type": "array", "uniqueItems": true }, "set": { "items": { "$ref": "#/components/schemas/courier.DeliveryCompanyCustomMetadataEntry" }, "maxItems": 64, "type": "array" } }, "type": "object" }, "internal_modules_courier.DeliveryCompanyDetail": { "allOf": [ { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyView" }, { "properties": { "booking_readiness": { "description": "Whether the current configuration may book live, evaluated with the same gates as live booking. Detail read only. Null (unknown) when the test receipt or credential revocation status store is unavailable.", "oneOf": [ { "$ref": "#/components/schemas/internal_modules_courier.BookingReadiness" }, { "type": "null" } ] }, "credential": { "description": "Non-secret credential safety state of the current configuration revision. Readable with courier.settings.read. Null until the company has a connection configuration.", "oneOf": [ { "$ref": "#/components/schemas/internal_modules_courier.CredentialState" }, { "type": "null" } ] } }, "required": [ "credential", "booking_readiness" ], "type": "object" } ] }, "internal_modules_courier.DeliveryCompanyResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyView" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_courier.DeliveryCompanyView": { "properties": { "code": { "type": "string" }, "configuration": { "items": { "$ref": "#/components/schemas/courier.DeliveryCompanyConfigurationEntry" }, "type": "array" }, "country_codes": { "items": { "type": "string" }, "type": "array" }, "created_at": { "type": "string" }, "custom_metadata": { "items": { "$ref": "#/components/schemas/courier.DeliveryCompanyCustomMetadataEntry" }, "type": "array" }, "default_instructions": { "type": "string" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "service_areas": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ServiceArea" }, "type": "array" }, "slot_request": { "$ref": "#/components/schemas/internal_modules_courier.SlotRequest" }, "status": { "enum": [ "draft" ], "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "zone_details": { "description": "Live Orders zone display evidence; never persisted as coverage authority.", "items": { "$ref": "#/components/schemas/internal_modules_courier.ZoneDetail" }, "type": "array" } }, "type": "object" }, "internal_modules_courier.DeliveryOptionsInput": { "additionalProperties": false, "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "companies": { "items": { "$ref": "#/components/schemas/internal_modules_courier.CompanyExecutionInput" }, "maxItems": 20, "minItems": 1, "type": "array" }, "market_code": { "maxLength": 128, "type": "string" }, "zone_id": { "maxLength": 128, "type": "string" } }, "required": [ "market_code", "address", "companies" ], "type": "object" }, "internal_modules_courier.DeliveryOptionsResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryOptionsResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_courier.DeliveryOptionsResult": { "additionalProperties": false, "properties": { "companies": { "items": { "$ref": "#/components/schemas/internal_modules_courier.CompanyExecutionResult" }, "maxItems": 20, "type": "array" } }, "required": [ "companies" ], "type": "object" }, "internal_modules_courier.DeliverySlot": { "additionalProperties": false, "description": "Opaque stable hash binds company, local date, exact instants, provider reference and source.", "properties": { "delivery_date": { "format": "date", "type": "string" }, "end_at": { "format": "date-time", "type": "string" }, "id": { "pattern": "^[a-f0-9]{64}$", "type": "string" }, "source": { "enum": [ "provider", "configured_schedule" ], "type": "string" }, "start_at": { "format": "date-time", "type": "string" }, "timezone": { "type": "string" } }, "required": [ "id", "start_at", "end_at", "timezone", "source", "delivery_date" ], "type": "object" }, "internal_modules_courier.Diagnostic": { "additionalProperties": false, "properties": { "code": { "enum": [ "address_required", "invalid_address", "no_coverage", "no_available_slots", "provider_unavailable", "provider_response_invalid", "configuration_unavailable", "configuration_invalid", "company_disabled", "credential_revoked", "test_required", "rule_context_invalid", "quote_expired", "input_missing", "input_invalid", "booking_not_configured", "sandbox_booking_failed" ], "type": "string" }, "field": { "type": "string" } }, "required": [ "field", "code" ], "type": "object" }, "internal_modules_courier.InputCondition": { "additionalProperties": false, "description": "present has no RHS. Other comparisons require the input and a non-secret literal/setting/input RHS. Secret-dependent conditions are prohibited.", "properties": { "input": { "enum": [ "postal_code", "locality", "country_code", "state_code", "line1", "line2", "zone_id", "market_code", "production_date", "ready_at", "cutoff_at", "evaluated_at", "next_transition_at" ], "type": "string" }, "operator": { "enum": [ "present", "equal", "not_equal", "in" ], "type": "string" }, "value": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" } }, "required": [ "input", "operator" ], "type": "object" }, "internal_modules_courier.InstantMapping": { "additionalProperties": false, "description": "local combines date/time with mapped IANA timezone. Local end may inherit start date; overnight rollover requires next_day.", "properties": { "date": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" }, "date_format": { "enum": [ "iso_date", "compact_date", "day_first_date" ], "type": "string" }, "format": { "enum": [ "rfc3339", "unix_seconds", "unix_milliseconds", "local" ], "type": "string" }, "time": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" }, "timestamp": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" } }, "required": [ "format" ], "type": "object" }, "internal_modules_courier.PolicyInput": { "additionalProperties": false, "description": "Save immutable country, market and live shipping-zone coverage as a draft. Saving does not publish a runtime policy.", "properties": { "country_codes": { "items": { "type": "string" }, "type": "array" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "service_areas": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ServiceArea" }, "type": "array" } }, "required": [ "expected_revision", "country_codes", "service_areas" ], "type": "object" }, "internal_modules_courier.PolicyReference": { "additionalProperties": false, "properties": { "company_code": { "pattern": "^[a-z0-9][a-z0-9-]{1,31}$", "type": "string" }, "configuration_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "credential_version": { "maxLength": 128, "type": "string" }, "policy_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "rule_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "test_id": { "pattern": "^[a-f0-9]{24}$", "type": "string" } }, "required": [ "company_code", "policy_revision", "configuration_revision", "rule_revision", "credential_version", "test_id" ], "type": "object" }, "internal_modules_courier.ProviderCreateInput": { "additionalProperties": false, "properties": { "code": { "description": "Open immutable company slug; no provider allowlist.", "pattern": "^[a-z0-9][a-z0-9-]{1,31}$", "type": "string" }, "country_codes": { "items": { "pattern": "^[A-Z]{2}$", "type": "string" }, "maxItems": 8, "type": "array", "uniqueItems": true }, "default_instructions": { "type": "string" }, "enabled": { "description": "Current safety intent; a new company has no published runtime policy.", "type": "boolean" }, "name": { "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "internal_modules_courier.ProviderUpdateInput": { "additionalProperties": false, "properties": { "default_instructions": { "type": "string" }, "enabled": { "description": "Current safety override for all revisions. Enabling does not publish a draft.", "type": "boolean" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "name": { "type": "string" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_courier.RequestBinding": { "additionalProperties": false, "properties": { "key": { "maxLength": 128, "type": "string" }, "value": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "when": { "$ref": "#/components/schemas/internal_modules_courier.InputCondition" } }, "required": [ "key", "value" ], "type": "object" }, "internal_modules_courier.RequestDiagnostic": { "additionalProperties": false, "description": "Transient resolved request with sensitive/address values redacted. Never stored. No arbitrary provider body, headers or error text.", "properties": { "body": {}, "headers": { "additionalProperties": { "type": "string" }, "type": "object" }, "method": { "type": "string" }, "query": { "additionalProperties": { "type": "string" }, "type": "object" }, "url": { "type": "string" } }, "required": [ "method", "url", "headers", "query" ], "type": "object" }, "internal_modules_courier.ResponseMapping": { "additionalProperties": false, "description": "Maximum1000 total rows. coverage and expires_at select root values. A false coverage match is no_coverage; true coverage with valid empty rows is no_available_slots. Nonexistent wall times always fail; folds use explicit DST policy.", "properties": { "availability": { "$ref": "#/components/schemas/internal_modules_courier.AvailabilityMapping" }, "coverage": { "$ref": "#/components/schemas/internal_modules_courier.AvailabilityMapping" }, "dst_policy": { "enum": [ "reject", "earlier", "later" ], "type": "string" }, "end": { "$ref": "#/components/schemas/internal_modules_courier.InstantMapping" }, "expires_at": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" }, "groups": { "description": "Optional group-array pointer. Present empty string selects a root array of groups; omission selects one root group.", "maxLength": 512, "type": "string" }, "items": { "maxLength": 512, "type": "string" }, "overnight_policy": { "enum": [ "reject", "next_day" ], "type": "string" }, "reference": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" }, "start": { "$ref": "#/components/schemas/internal_modules_courier.InstantMapping" }, "timezone": { "$ref": "#/components/schemas/internal_modules_courier.ResponseValue" } }, "required": [ "items", "reference", "start", "end", "timezone", "dst_policy", "overnight_policy" ], "type": "object" }, "internal_modules_courier.ResponseValue": { "additionalProperties": false, "description": "RFC6901 JSON pointer, empty means scope root. Explicit bounded default applies only when the selected path is missing or null; malformed present values fail. Literal scope has no path/default.", "properties": { "default": {}, "literal": {}, "path": { "maxLength": 512, "type": "string" }, "scope": { "enum": [ "literal", "root", "group", "item" ], "type": "string" } }, "required": [ "scope" ], "type": "object" }, "internal_modules_courier.RuleContext": { "additionalProperties": false, "description": "Only exact svc-orders may supply rule evaluator output. Runtime uses real time; stale/future evaluations fail closed.", "properties": { "allowed_delivery_days": { "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 1, "type": "array", "uniqueItems": true }, "company_code": { "type": "string" }, "cutoff_at": { "format": "date-time", "type": "string" }, "evaluated_at": { "format": "date-time", "type": "string" }, "excluded_delivery_dates": { "items": { "format": "date", "type": "string" }, "maxItems": 366, "type": "array", "uniqueItems": true }, "next_transition_at": { "format": "date-time", "type": "string" }, "production_date": { "format": "date", "type": "string" }, "ready_at": { "format": "date-time", "type": "string" }, "rule_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "company_code", "rule_revision", "evaluated_at", "production_date", "ready_at", "next_transition_at", "allowed_delivery_days", "excluded_delivery_dates" ], "type": "object" }, "internal_modules_courier.ScheduleWindow": { "additionalProperties": false, "properties": { "days_of_week": { "items": { "maximum": 6, "minimum": 0, "type": "integer" }, "maxItems": 7, "minItems": 1, "type": "array", "uniqueItems": true }, "end_time": { "type": "string" }, "reference": { "maxLength": 256, "minLength": 1, "type": "string" }, "start_time": { "type": "string" } }, "required": [ "reference", "start_time", "end_time", "days_of_week" ], "type": "object" }, "internal_modules_courier.ServiceArea": { "additionalProperties": false, "description": "Supply-owned bounded coverage assertion. Optional linked Orders zone is a live upper bound. zone requires a shipping_zone. include_only requires explicit postcodes. Provider all_except additionally requires mapped coverage; configured_schedule all_except is an administrator-authored assertion. No address verification is performed.", "properties": { "code": { "maxLength": 128, "type": "string" }, "country_code": { "pattern": "^[A-Z]{2}$", "type": "string" }, "enabled": { "type": "boolean" }, "exclude_postal_codes": { "items": { "maxLength": 32, "type": "string" }, "maxItems": 1000, "type": "array", "uniqueItems": true }, "include_postal_codes": { "items": { "maxLength": 32, "type": "string" }, "maxItems": 1000, "type": "array", "uniqueItems": true }, "market_code": { "maxLength": 128, "type": "string" }, "postal_code_mode": { "enum": [ "zone", "include_only", "all_except" ], "type": "string" }, "shipping_zone": { "$ref": "#/components/schemas/internal_modules_courier.ShippingZoneReference" }, "state_codes": { "items": { "maxLength": 32, "type": "string" }, "maxItems": 100, "type": "array", "uniqueItems": true } }, "required": [ "code", "country_code", "market_code", "state_codes", "postal_code_mode", "include_postal_codes", "exclude_postal_codes", "enabled" ], "type": "object" }, "internal_modules_courier.ShippingZoneReference": { "additionalProperties": false, "properties": { "id": { "maxLength": 128, "type": "string" } }, "required": [ "id" ], "type": "object" }, "internal_modules_courier.SlotRequest": { "additionalProperties": false, "description": "Source is explicit; provider failures never fall back to local schedules. Endpoint authority accepts only trusted literal/non-sensitive setting, HTTPS hostname, no query/userinfo/fragment/IP. Dynamic values bind escaped path/query/body. Resolved URL8KiB, headers16KiB, query8KiB, body16KiB; transport headers forbidden.", "properties": { "availability_lookup": { "type": "boolean" }, "body": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "endpoint": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "headers": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "maxItems": 64, "type": "array" }, "method": { "description": "GET default, body prohibited. POST/PUT/PATCH require availability_lookup=true, explicit read-only availability semantics, and are never retried.", "type": "string" }, "path": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "maxItems": 32, "type": "array" }, "query": { "items": { "$ref": "#/components/schemas/internal_modules_courier.RequestBinding" }, "maxItems": 64, "type": "array" }, "response": { "$ref": "#/components/schemas/internal_modules_courier.ResponseMapping" }, "schedule": { "$ref": "#/components/schemas/internal_modules_courier.ConfiguredSchedule" }, "source": { "description": "provider or configured_schedule; incomplete drafts remain non-executable until tested.", "type": "string" }, "timeout_ms": { "description": "Omitted or zero selects the 12000ms provider default; explicit overrides must be 100-12000ms. One aggregate deadline covers DNS, connection, TLS, response headers and response body. Earlier company or caller cancellation wins.", "maximum": 12000, "minimum": 0, "not": { "maximum": 99, "minimum": 1 }, "type": "integer" } }, "required": [ "source", "availability_lookup" ], "type": "object" }, "internal_modules_courier.TestBookingInput": { "additionalProperties": false, "properties": { "booking": { "$ref": "#/components/schemas/internal_modules_courier.BookingInput" }, "configuration_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "configuration_revision", "booking" ], "type": "object" }, "internal_modules_courier.TestBookingResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.TestBookingResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_courier.TestBookingResult": { "additionalProperties": false, "properties": { "carrier_reference": { "type": "string" }, "company_code": { "type": "string" }, "configuration_revision": { "format": "int64", "type": "integer" }, "credential_version": { "type": "string" }, "diagnostics": { "items": { "$ref": "#/components/schemas/internal_modules_courier.Diagnostic" }, "type": "array" }, "error_code": { "$ref": "#/components/schemas/courier_enums.CarrierBookingErrorCode" }, "error_fields": { "items": { "type": "string" }, "type": "array" }, "error_message": { "type": "string" }, "http_status": { "type": "integer" }, "outcome": { "$ref": "#/components/schemas/courier_enums.CarrierBookingOutcome" }, "passed": { "type": "boolean" }, "request_summary": { "items": { "$ref": "#/components/schemas/courier.CarrierBookingRequestSummaryEntry" }, "type": "array" }, "test_id": { "type": "string" }, "tested_at": { "format": "date-time", "type": "string" } }, "required": [ "company_code", "configuration_revision", "passed", "tested_at", "error_fields", "diagnostics", "request_summary" ], "type": "object" }, "internal_modules_courier.TestConfigurationInput": { "additionalProperties": false, "description": "Orders-authorized staff test. Rules evaluated_at may simulate years2000..2200; the simulation clock advances with actual elapsed I/O time. No client clock is accepted by runtime execution.", "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "company_code": { "pattern": "^[a-z0-9][a-z0-9-]{1,31}$", "type": "string" }, "configuration_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "credential_version": { "maxLength": 128, "type": "string" }, "market_code": { "maxLength": 128, "type": "string" }, "rule_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "rules": { "$ref": "#/components/schemas/internal_modules_courier.RuleContext" }, "zone_id": { "maxLength": 128, "type": "string" } }, "required": [ "company_code", "configuration_revision", "credential_version", "rule_revision", "market_code", "address", "rules" ], "type": "object" }, "internal_modules_courier.TestConfigurationResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.TestConfigurationResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_courier.TestConfigurationResult": { "additionalProperties": false, "description": "Successful receipt stores only test_id, company/config/rule/credential tuple and real tested_at. It never binds or stores sample address, slots, simulation time or raw payload. Current disable/revocation always overrides receipts.", "properties": { "company_code": { "type": "string" }, "configuration_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "credential_version": { "type": "string" }, "diagnostics": { "items": { "$ref": "#/components/schemas/internal_modules_courier.Diagnostic" }, "type": "array" }, "expires_at": { "format": "date-time", "type": "string" }, "http_status": { "type": "integer" }, "passed": { "type": "boolean" }, "request": { "$ref": "#/components/schemas/internal_modules_courier.RequestDiagnostic" }, "rule_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "slots": { "items": { "$ref": "#/components/schemas/internal_modules_courier.DeliverySlot" }, "maxItems": 1000, "type": "array" }, "test_id": { "type": "string" }, "tested_at": { "format": "date-time", "type": "string" } }, "required": [ "company_code", "configuration_revision", "credential_version", "rule_revision", "passed", "tested_at", "diagnostics", "slots" ], "type": "object" }, "internal_modules_courier.ValueExpression": { "additionalProperties": false, "description": "Closed declarative tree: depth8,256 total expressions. False conditions omit object properties or array items. Settings exclude sensitive entries; secret source reads the exact versioned encrypted bundle.", "properties": { "format": { "description": "iso_date, compact_date, day_first_date, rfc3339, unix_seconds, unix_milliseconds", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "maxItems": 64, "type": "array" }, "key": { "maxLength": 128, "type": "string" }, "map": { "additionalProperties": { "type": "string" }, "description": "Booking only. Translates a resolved text value; unmatched values pass through.", "maxProperties": 64, "type": "object" }, "prefix": { "maxLength": 1024, "type": "string" }, "properties": { "additionalProperties": { "$ref": "#/components/schemas/internal_modules_courier.ValueExpression" }, "maxProperties": 64, "type": "object" }, "separator": { "description": "Booking join source only.", "maxLength": 16, "type": "string" }, "source": { "description": "Execution sources: literal, setting, secret, input, object, array; booking also per_container, join, coalesce. Drafts may be incomplete.", "type": "string" }, "suffix": { "maxLength": 1024, "type": "string" }, "timezone": { "maxLength": 128, "type": "string" }, "type": { "description": "Execution types: text, integer, decimal, boolean, object, array.", "type": "string" }, "value": {}, "when": { "$ref": "#/components/schemas/internal_modules_courier.InputCondition" } }, "required": [ "source", "type" ], "type": "object" }, "internal_modules_courier.ZoneDetail": { "properties": { "id": { "type": "string" }, "status": { "enum": [ "active", "inactive", "missing", "unavailable" ], "type": "string" }, "zone": { "$ref": "#/components/schemas/shipping.Zone" } }, "required": [ "id", "status" ], "type": "object" }, "internal_modules_damage.CreateInput": { "properties": { "affected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "bucket_id": { "type": "string" }, "loss_value": { "$ref": "#/components/schemas/money.Money" }, "note": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "reference_id": { "type": "string" }, "reported_by": { "type": "string" }, "sku_code": { "type": "string" }, "stage": { "$ref": "#/components/schemas/warehouse_enums.DamageStage" }, "stock_unit_id": { "type": "string" } }, "required": [ "affected_composition", "bucket_id", "quality_assessment_id", "reported_by", "sku_code", "stage" ], "type": "object" }, "internal_modules_depots.CoverageRuleInput": { "properties": { "administrative_area_code": { "type": "string" }, "country_code": { "type": "string" }, "is_active": { "type": "boolean" }, "postal_code": { "type": "string" }, "priority": { "type": "integer" } }, "required": [ "country_code" ], "type": "object" }, "internal_modules_depots.CoverageRuleRecord": { "properties": { "revision": { "type": "integer" } }, "type": "object" }, "internal_modules_depots.DeleteInput": { "properties": { "expected_revision": { "type": "integer" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_depots.DepotInput": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "allowed_fulfilment_intents": { "items": { "$ref": "#/components/schemas/shipping_enums.FulfilmentIntent" }, "type": "array", "uniqueItems": false }, "code": { "type": "string" }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "layout_id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "region_code": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "address", "code", "name", "region_code", "timezone" ], "type": "object" }, "internal_modules_depots.DepotRecord": { "properties": { "allowed_fulfilment_intents": { "items": { "$ref": "#/components/schemas/shipping_enums.FulfilmentIntent" }, "type": "array", "uniqueItems": false }, "fulfilment_policy_revision": { "type": "integer" }, "is_public": { "type": "boolean" }, "pos_deficit_location_code": { "description": "Depot-qualified standard location designated for unallocated POS deficits. Setting it enables POS negative selling at this depot - a short or zero-stock channel=pos sale-eligibility line becomes eligible with pos_deficit evidence; without it such lines are refused.", "type": "string" }, "revision": { "type": "integer" } }, "type": "object" }, "internal_modules_depots.LocationInput": { "properties": { "access": { "$ref": "#/components/schemas/warehouse_enums.StockLocationAccess" }, "collection_eligibility": { "items": { "$ref": "#/components/schemas/warehouse.StockLocationCollectionEligibility" }, "type": "array", "uniqueItems": false }, "collection_mode": { "$ref": "#/components/schemas/warehouse_enums.StockLocationCollectionMode" }, "color": { "type": "string" }, "depot_code": { "type": "string" }, "handling_mode": { "$ref": "#/components/schemas/warehouse_enums.StockLocationHandlingMode" }, "is_active": { "type": "boolean" }, "layout_node_id": { "type": "string" }, "location_code": { "type": "string" }, "name": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/warehouse_enums.StockLocationPurpose" }, "shape": { "$ref": "#/components/schemas/warehouse_enums.ShapeType" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "transform": { "$ref": "#/components/schemas/geometry.Transform" } }, "required": [ "access", "collection_mode", "depot_code", "handling_mode", "location_code", "purpose", "storage_type" ], "type": "object" }, "internal_modules_depots.RegionInput": { "properties": { "administrative_area_code": { "type": "string" }, "code": { "type": "string" }, "country_code": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "administrative_area_code", "code", "country_code", "name" ], "type": "object" }, "internal_modules_depots.ResolveRequest": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "fulfilment_intent": { "$ref": "#/components/schemas/shipping_enums.FulfilmentIntent" }, "market_code": { "description": "Authoritative owning market; resolved depot must serve this market.", "minLength": 1, "type": "string" }, "selected_depot_code": { "type": "string" }, "source": { "$ref": "#/components/schemas/geography_enums.GeographicContextSource" } }, "required": [ "fulfilment_intent", "source", "market_code" ], "type": "object" }, "internal_modules_depots.ResolveResult": { "properties": { "coverage_rule": { "$ref": "#/components/schemas/internal_modules_depots.CoverageRuleRecord" }, "depot": { "$ref": "#/components/schemas/internal_modules_depots.DepotRecord" }, "evaluation_timezone": { "type": "string" }, "geographic_context": { "$ref": "#/components/schemas/geography.GeographicContext" }, "match_level": { "type": "string" }, "match_source": { "type": "string" }, "matched_country_code": { "type": "string" }, "matched_subdivision_code": { "type": "string" }, "region": { "$ref": "#/components/schemas/warehouse.DepotRegion" }, "rule_revision": { "type": "integer" }, "scope_revision": { "type": "integer" } }, "type": "object" }, "internal_modules_depots.UpdateCoverageRuleInput": { "properties": { "administrative_area_code": { "type": "string" }, "country_code": { "type": "string" }, "expected_revision": { "type": "integer" }, "is_active": { "type": "boolean" }, "postal_code": { "type": "string" }, "priority": { "type": "integer" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_depots.UpdateDepotInput": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "allowed_fulfilment_intents": { "items": { "$ref": "#/components/schemas/shipping_enums.FulfilmentIntent" }, "type": "array", "uniqueItems": false }, "expected_revision": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_public": { "type": "boolean" }, "layout_id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "pos_deficit_location_code": { "description": "Active standard location in this depot for unallocated POS deficits; an empty string clears the designation. Setting it enables POS negative selling (pos_deficit sale-eligibility evidence); clearing it turns that off.", "type": "string" }, "region_code": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_depots.UpdateLocationInput": { "properties": { "access": { "$ref": "#/components/schemas/warehouse_enums.StockLocationAccess" }, "collection_eligibility": { "items": { "$ref": "#/components/schemas/warehouse.StockLocationCollectionEligibility" }, "type": "array", "uniqueItems": false }, "collection_mode": { "$ref": "#/components/schemas/warehouse_enums.StockLocationCollectionMode" }, "color": { "type": "string" }, "expected_revision": { "type": "integer" }, "handling_mode": { "$ref": "#/components/schemas/warehouse_enums.StockLocationHandlingMode" }, "is_active": { "type": "boolean" }, "layout_node_id": { "type": "string" }, "name": { "type": "string" }, "purpose": { "$ref": "#/components/schemas/warehouse_enums.StockLocationPurpose" }, "shape": { "$ref": "#/components/schemas/warehouse_enums.ShapeType" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "transform": { "$ref": "#/components/schemas/geometry.Transform" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_depots.UpdateRegionInput": { "properties": { "administrative_area_code": { "type": "string" }, "country_code": { "type": "string" }, "expected_revision": { "type": "integer" }, "is_active": { "type": "boolean" }, "name": { "type": "string" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_depots.resolveDepotAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_depots.ResolveResult" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_esl.Audit": { "properties": { "actor_id": { "type": "string" }, "at": { "format": "date-time", "type": "string" }, "previous_owner": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "actor_id", "reason", "at" ], "type": "object" }, "internal_modules_esl.BindInput": { "properties": { "binding": { "$ref": "#/components/schemas/internal_modules_esl.BindingInput" }, "reason": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "revision", "reason", "binding" ], "type": "object" }, "internal_modules_esl.BindingInput": { "properties": { "hardware_code": { "type": "string" }, "slots": { "items": { "$ref": "#/components/schemas/internal_modules_esl.Slot" }, "maxItems": 100, "minItems": 1, "type": "array" }, "store_code": { "type": "string" } }, "required": [ "store_code", "hardware_code", "slots" ], "type": "object" }, "internal_modules_esl.Command": { "properties": { "accepted": { "type": "boolean" }, "attempt": { "format": "int64", "type": "integer" }, "attempts": { "items": { "$ref": "#/components/schemas/internal_modules_esl.CommandAttempt" }, "type": "array" }, "claim_until": { "format": "date-time", "type": "string" }, "command_code": { "type": "string" }, "config_revision": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "due_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "failure_code": { "type": "string" }, "hardware_code": { "type": "string" }, "kind": { "type": "string" }, "light": { "$ref": "#/components/schemas/internal_modules_esl.LightIntent" }, "mac": { "type": "string" }, "operation_code": { "format": "int64", "type": "integer" }, "outcome": { "$ref": "#/components/schemas/internal_modules_esl.Observation" }, "render": { "$ref": "#/components/schemas/internal_modules_esl.RenderPlan" }, "revision": { "format": "int64", "type": "integer" }, "state": { "enum": [ "queued", "dispatching", "submitted", "uncertain", "confirmed", "failed", "superseded", "expired", "needs_operator", "operator_reconciled" ], "type": "string" }, "store_code": { "type": "string" }, "submitted_at": { "format": "date-time", "type": "string" }, "submitted_light": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" }, "target_revision": { "format": "int64", "type": "integer" } }, "required": [ "hardware_code", "command_code", "mac", "store_code", "kind", "target_revision", "config_revision", "state", "revision", "attempt", "operation_code", "created_at", "due_at", "expires_at", "claim_until", "accepted" ], "type": "object" }, "internal_modules_esl.CommandAttempt": { "properties": { "failure_code": { "type": "string" }, "operation_code": { "format": "int64", "type": "integer" }, "outcome": { "$ref": "#/components/schemas/internal_modules_esl.Observation" }, "submitted_at": { "format": "date-time", "type": "string" }, "submitted_light": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" } }, "required": [ "operation_code", "failure_code" ], "type": "object" }, "internal_modules_esl.ConfigurationInput": { "properties": { "active": { "type": "boolean" }, "cadence_seconds": { "format": "int64", "type": "integer" }, "code": { "type": "string" }, "depot_code": { "type": "string" }, "driver": { "type": "string" }, "hardware": { "additionalProperties": { "$ref": "#/components/schemas/internal_modules_esl.Hardware" }, "type": "object" }, "market_code": { "type": "string" }, "max_task_lease_seconds": { "format": "int64", "type": "integer" }, "retry": { "$ref": "#/components/schemas/internal_modules_esl.RetryPolicy" }, "rules": { "items": { "$ref": "#/components/schemas/internal_modules_esl.LightRule" }, "type": "array" }, "task_pattern": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" }, "templates": { "items": { "$ref": "#/components/schemas/internal_modules_esl.Template" }, "type": "array" }, "vendor_store_id": { "type": "string" }, "verification": { "$ref": "#/components/schemas/internal_modules_esl.Verification" } }, "required": [ "code", "depot_code", "market_code", "vendor_store_id", "driver", "active", "hardware", "templates", "rules", "task_pattern", "max_task_lease_seconds", "cadence_seconds", "retry", "verification" ], "type": "object" }, "internal_modules_esl.ConfigureInput": { "properties": { "configuration": { "$ref": "#/components/schemas/internal_modules_esl.ConfigurationInput" }, "reason": { "type": "string" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "revision", "reason", "configuration" ], "type": "object" }, "internal_modules_esl.FocusInput": { "properties": { "duration_seconds": { "maximum": 3600, "minimum": 1, "type": "integer" }, "override": { "type": "boolean" }, "reason": { "type": "string" } }, "required": [ "duration_seconds" ], "type": "object" }, "internal_modules_esl.FocusResult": { "properties": { "lease": { "$ref": "#/components/schemas/internal_modules_esl.TaskLease" }, "mac": { "type": "string" }, "state": { "type": "string" } }, "required": [ "mac", "state" ], "type": "object" }, "internal_modules_esl.Hardware": { "properties": { "barcode_formats": { "items": { "type": "string" }, "type": "array" }, "colors": { "items": { "format": "int64", "type": "integer" }, "type": "array" }, "flashing": { "type": "boolean" }, "max_products_per_side": { "format": "int64", "type": "integer" }, "sides": { "items": { "type": "string" }, "type": "array" } }, "required": [ "sides", "max_products_per_side", "barcode_formats", "colors", "flashing" ], "type": "object" }, "internal_modules_esl.Label": { "properties": { "audit": { "$ref": "#/components/schemas/internal_modules_esl.Audit" }, "config_revision": { "format": "int64", "type": "integer" }, "confirmed_revision": { "format": "int64", "type": "integer" }, "corrective_action": { "type": "string" }, "depot_code": { "type": "string" }, "desired": { "$ref": "#/components/schemas/internal_modules_esl.RenderPlan" }, "desired_revision": { "format": "int64", "type": "integer" }, "dispatch_command": { "type": "string" }, "display_state": { "type": "string" }, "hardware_code": { "type": "string" }, "lease": { "$ref": "#/components/schemas/internal_modules_esl.TaskLease" }, "light": { "$ref": "#/components/schemas/internal_modules_esl.LightIntent" }, "light_dispatch_command": { "type": "string" }, "light_revision": { "format": "int64", "type": "integer" }, "mac": { "type": "string" }, "next_reconcile_at": { "format": "date-time", "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "slots": { "items": { "$ref": "#/components/schemas/internal_modules_esl.Slot" }, "type": "array" }, "store_code": { "type": "string" } }, "required": [ "mac", "depot_code", "store_code", "hardware_code", "slots", "revision", "desired_revision", "confirmed_revision", "display_state", "config_revision", "next_reconcile_at", "light_revision", "audit" ], "type": "object" }, "internal_modules_esl.LightIntent": { "properties": { "condition": { "type": "string" }, "next_repeat_at": { "format": "date-time", "type": "string" }, "pattern": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" }, "repeat_seconds": { "format": "int64", "type": "integer" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "condition", "pattern", "repeat_seconds", "next_repeat_at", "valid_until" ], "type": "object" }, "internal_modules_esl.LightPattern": { "properties": { "brightness": { "format": "int64", "type": "integer" }, "color": { "format": "int64", "type": "integer" }, "duration_seconds": { "format": "int64", "type": "integer" }, "interval_ms": { "format": "int64", "type": "integer" }, "period_ms": { "format": "int64", "type": "integer" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "color", "total", "period_ms", "interval_ms", "brightness", "duration_seconds" ], "type": "object" }, "internal_modules_esl.LightRule": { "properties": { "condition": { "type": "string" }, "pattern": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" }, "priority": { "format": "int64", "type": "integer" }, "repeat_seconds": { "format": "int64", "type": "integer" }, "threshold": { "format": "int64", "type": "integer" } }, "required": [ "condition", "threshold", "priority", "pattern", "repeat_seconds" ], "type": "object" }, "internal_modules_esl.Observation": { "properties": { "correlated": { "type": "boolean" }, "failed": { "type": "boolean" }, "observed_at": { "format": "date-time", "type": "string" }, "result": { "type": "string" }, "succeeded": { "type": "boolean" }, "vendor_id": { "type": "string" } }, "required": [ "vendor_id", "result", "observed_at", "correlated", "succeeded", "failed" ], "type": "object" }, "internal_modules_esl.ReconcileInput": { "properties": { "command_id": { "type": "string" }, "evidence_reference": { "type": "string" }, "no_longer_in_flight": { "enum": [ true ], "type": "boolean" }, "revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "command_id", "revision", "evidence_reference", "no_longer_in_flight" ], "type": "object" }, "internal_modules_esl.RenderPlan": { "properties": { "generation": { "type": "string" }, "hash": { "type": "string" }, "rows": { "items": { "$ref": "#/components/schemas/internal_modules_esl.RenderRow" }, "type": "array" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "hash", "generation", "valid_until", "rows" ], "type": "object" }, "internal_modules_esl.RenderRow": { "properties": { "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "goods_id": { "type": "string" }, "position": { "format": "int64", "type": "integer" }, "side": { "type": "string" }, "template_id": { "type": "string" } }, "required": [ "side", "position", "goods_id", "template_id", "fields" ], "type": "object" }, "internal_modules_esl.RetryPolicy": { "properties": { "backoff_seconds": { "format": "int64", "type": "integer" }, "max_attempts": { "format": "int64", "type": "integer" }, "observation_seconds": { "format": "int64", "type": "integer" } }, "required": [ "max_attempts", "backoff_seconds", "observation_seconds" ], "type": "object" }, "internal_modules_esl.Slot": { "properties": { "barcode_assignment_code": { "type": "string" }, "custom_price_code": { "type": "string" }, "custom_price_revision": { "format": "int64", "type": "integer" }, "exclusive_path": { "type": "string" }, "expected_damage_tier": { "type": "string" }, "expiry_offer": { "type": "string" }, "location_code": { "type": "string" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "position": { "format": "int64", "type": "integer" }, "presentation_situation": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "side": { "type": "string" }, "sku_code": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "required": [ "side", "position", "sku_code", "package_option", "barcode_assignment_code", "location_code" ], "type": "object" }, "internal_modules_esl.StoreConfig": { "properties": { "active": { "type": "boolean" }, "audit": { "$ref": "#/components/schemas/internal_modules_esl.Audit" }, "cadence_seconds": { "format": "int64", "type": "integer" }, "code": { "type": "string" }, "depot_code": { "type": "string" }, "driver": { "type": "string" }, "hardware": { "additionalProperties": { "$ref": "#/components/schemas/internal_modules_esl.Hardware" }, "type": "object" }, "market_code": { "type": "string" }, "max_task_lease_seconds": { "format": "int64", "type": "integer" }, "retry": { "$ref": "#/components/schemas/internal_modules_esl.RetryPolicy" }, "revision": { "format": "int64", "type": "integer" }, "rules": { "items": { "$ref": "#/components/schemas/internal_modules_esl.LightRule" }, "type": "array" }, "task_pattern": { "$ref": "#/components/schemas/internal_modules_esl.LightPattern" }, "templates": { "items": { "$ref": "#/components/schemas/internal_modules_esl.Template" }, "type": "array" }, "vendor_store_id": { "type": "string" }, "verification": { "$ref": "#/components/schemas/internal_modules_esl.Verification" } }, "required": [ "code", "depot_code", "market_code", "vendor_store_id", "driver", "active", "hardware", "templates", "rules", "task_pattern", "max_task_lease_seconds", "cadence_seconds", "retry", "verification", "revision", "audit" ], "type": "object" }, "internal_modules_esl.TaskLease": { "properties": { "actor_id": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "task_id": { "type": "string" }, "task_revision": { "format": "int64", "type": "integer" }, "task_type": { "type": "string" }, "token": { "type": "string" } }, "required": [ "task_type", "task_id", "task_revision", "actor_id", "expires_at", "token" ], "type": "object" }, "internal_modules_esl.Template": { "properties": { "barcode_formats": { "items": { "type": "string" }, "type": "array" }, "code": { "type": "string" }, "fields": { "additionalProperties": { "type": "string" }, "type": "object" }, "hardware_code": { "type": "string" }, "products_per_side": { "format": "int64", "type": "integer" }, "situation": { "type": "string" }, "vendor_demo_id": { "type": "string" } }, "required": [ "code", "vendor_demo_id", "hardware_code", "situation", "products_per_side", "barcode_formats", "fields" ], "type": "object" }, "internal_modules_esl.Verification": { "properties": { "layouts": { "type": "boolean" }, "led_durations": { "items": { "$ref": "#/components/schemas/internal_modules_esl.VerifiedLEDDuration" }, "maxItems": 1000, "type": "array" }, "led_item_success_code": { "format": "int64", "type": "integer" }, "led_timing": { "type": "boolean" }, "log_timezone": { "type": "string" }, "reference": { "type": "string" }, "render_correlation": { "type": "boolean" } }, "required": [ "reference", "layouts", "led_timing", "render_correlation", "log_timezone" ], "type": "object" }, "internal_modules_esl.VerifiedLEDDuration": { "properties": { "duration_seconds": { "maximum": 3600, "minimum": 1, "type": "integer" }, "hardware_code": { "type": "string" }, "interval_ms": { "maximum": 65535, "minimum": 2, "type": "integer" }, "period_ms": { "maximum": 65535, "minimum": 2, "type": "integer" }, "total": { "maximum": 65535, "minimum": 2, "type": "integer" } }, "required": [ "hardware_code", "duration_seconds", "period_ms", "interval_ms", "total" ], "type": "object" }, "internal_modules_expiry.ExpiredLot": { "description": "One positive inventory bucket of an EXPIRY lot at or before the query instant. A lot in multiple locations has multiple rows.", "properties": { "available_base_units": { "description": "Unreserved quantity available for movement; a hold remains unavailable for sale.", "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "lot_id": { "type": "string" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reserved_base_units": { "format": "int64", "type": "integer" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "supplier_lot_code": { "type": "string" }, "unit_tracked": { "description": "Whether this bucket requires exact available labelled stock units for movement. Legacy buckets without persisted tracking evidence return false.", "type": "boolean" } }, "required": [ "lot_id", "sku_code", "date_mark", "bucket_id", "location", "package_option", "handling_unit", "unit_tracked", "package_composition", "condition", "disposition", "on_hand_base_units", "reserved_base_units", "available_base_units", "revision" ], "type": "object" }, "internal_modules_expiry.ExpiredLotPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_expiry.ExpiredLot" }, "type": "array" }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "internal_modules_expiry.RunResult": { "properties": { "critical": { "type": "integer" }, "expired": { "type": "integer" }, "ok": { "type": "integer" }, "total": { "type": "integer" }, "warning": { "type": "integer" } }, "type": "object" }, "internal_modules_favouritelists.CreateInput": { "properties": { "name": { "type": "string" } }, "type": "object" }, "internal_modules_favouritelists.UpdateInput": { "properties": { "name": { "type": "string" } }, "type": "object" }, "internal_modules_fieldextract.fieldsAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_fieldextract.response" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_fieldextract.response": { "properties": { "fields": { "additionalProperties": {}, "type": "object" }, "id": { "type": "string" }, "ref": { "type": "string" }, "resource": { "type": "string" } }, "type": "object" }, "internal_modules_forecasts.ProducerUpsertInput": { "properties": { "alert_level": { "$ref": "#/components/schemas/security_enums.AlertLevel" }, "algorithm": { "type": "string" }, "algorithm_params": { "$ref": "#/components/schemas/metadata.Metadata" }, "as_of": { "type": "string" }, "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "computed_at": { "type": "string" }, "days_until_stockout": { "type": "number" }, "depot_code": { "type": "string" }, "forecast_horizon_days": { "minimum": 0, "type": "integer" }, "history_days": { "minimum": 0, "type": "integer" }, "predicted_daily": { "items": { "$ref": "#/components/schemas/forecasting.DailyPrediction" }, "type": "array", "uniqueItems": false }, "predicted_demand_total": { "type": "number" }, "product_name": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "alert_level", "algorithm", "as_of", "channel", "depot_code", "timezone" ], "type": "object" }, "internal_modules_forecasts.UpsertInput": { "properties": { "alert_level": { "$ref": "#/components/schemas/security_enums.AlertLevel" }, "algorithm": { "type": "string" }, "algorithm_params": { "$ref": "#/components/schemas/metadata.Metadata" }, "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "computed_at": { "type": "string" }, "days_until_stockout": { "type": "number" }, "depot_code": { "type": "string" }, "forecast_horizon_days": { "minimum": 0, "type": "integer" }, "history_days": { "minimum": 0, "type": "integer" }, "predicted_daily": { "items": { "$ref": "#/components/schemas/forecasting.DailyPrediction" }, "type": "array", "uniqueItems": false }, "predicted_demand_total": { "type": "number" }, "product_name": { "type": "string" }, "timezone": { "type": "string" } }, "required": [ "alert_level", "algorithm", "channel", "depot_code", "timezone" ], "type": "object" }, "internal_modules_forecasts.producerForecastAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/forecasting.SKUDemandForecast" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_fulfillment.RecheckAbortOutcome": { "properties": { "aborted_at": { "format": "date-time", "type": "string" }, "order_number": { "type": "string" }, "receipt": { "$ref": "#/components/schemas/internal_modules_fulfillment.RecheckReceipt" }, "request": { "$ref": "#/components/schemas/internal_modules_fulfillment.RecheckInput" }, "state": { "enum": [ "aborted", "prepared", "finalized" ], "type": "string" } }, "required": [ "order_number", "request", "state" ], "type": "object" }, "internal_modules_fulfillment.RecheckFinalizeInput": { "additionalProperties": false, "properties": { "edit_id": { "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "edit_id", "fulfillment_generation" ], "type": "object" }, "internal_modules_fulfillment.RecheckInput": { "additionalProperties": false, "properties": { "edit_id": { "type": "string" }, "expected_order_updated_at": { "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "previous_fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "edit_id", "expected_order_updated_at", "previous_fulfillment_generation", "fulfillment_generation" ], "type": "object" }, "internal_modules_fulfillment.RecheckReceipt": { "properties": { "edit_id": { "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "order_number": { "type": "string" }, "prepared_at": { "format": "date-time", "type": "string" }, "previous_fulfillment_generation": { "format": "int64", "type": "integer" }, "state": { "enum": [ "prepared", "finalized" ], "type": "string" } }, "required": [ "edit_id", "order_number", "previous_fulfillment_generation", "fulfillment_generation", "state", "prepared_at" ], "type": "object" }, "internal_modules_fulfillment.RefundCleanupReceipt": { "additionalProperties": false, "description": "Exact immutable command identity. Completed means physical closure and stock compensation committed atomically. Prepared may replay as completed. completed_at is present only for completed_v2 and cannot precede prepared_at.", "properties": { "cleanup_key": { "description": "Exact order-refund-cleanup colon order number colon refund ID identity.", "type": "string" }, "completed_at": { "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" }, "order_number": { "maxLength": 128, "minLength": 1, "type": "string" }, "origin_fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" }, "prepared_at": { "format": "date-time", "type": "string" }, "proof_kind": { "enum": [ "native_full_refund", "physical_exhaustion" ], "type": "string" }, "refund_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "reset": { "$ref": "#/components/schemas/internal_modules_fulfillment.RefundCleanupReset" }, "schema_version": { "enum": [ 2 ], "type": "integer" }, "state": { "enum": [ "prepared_v2", "completed_v2" ], "type": "string" }, "stock_compensated": { "type": "boolean" } }, "required": [ "schema_version", "proof_kind", "cleanup_key", "refund_id", "origin_fulfillment_generation", "fulfillment_generation", "order_number", "state", "prepared_at", "stock_compensated" ], "type": "object" }, "internal_modules_fulfillment.RefundCleanupRequest": { "additionalProperties": false, "description": "Native schema-2 proof identity. No reset means target equals origin; a reset binds origin to its previous or target generation. Maximum request body is 8192 bytes. Unknown fields and missing or null required fields are refused.", "properties": { "cleanup_key": { "description": "Exact order-refund-cleanup colon order number colon refund ID identity.", "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" }, "origin_fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" }, "proof_kind": { "enum": [ "native_full_refund", "physical_exhaustion" ], "type": "string" }, "refund_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "reset": { "$ref": "#/components/schemas/internal_modules_fulfillment.RefundCleanupReset" }, "schema_version": { "enum": [ 2 ], "type": "integer" } }, "required": [ "schema_version", "proof_kind", "cleanup_key", "refund_id", "origin_fulfillment_generation", "fulfillment_generation" ], "type": "object" }, "internal_modules_fulfillment.RefundCleanupReset": { "additionalProperties": false, "description": "Exact transferred physical refund reset. Target is previous generation plus one.", "properties": { "edit_id": { "maxLength": 128, "minLength": 1, "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "previous_fulfillment_generation": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "edit_id", "previous_fulfillment_generation", "fulfillment_generation" ], "type": "object" }, "internal_modules_fulfillment.RefundCleanupResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_fulfillment.RefundCleanupReceipt" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_importcompliance.ActionInput": { "properties": { "reason": { "maxLength": 1000, "type": "string" } }, "type": "object" }, "internal_modules_importcompliance.AirCargoSettings": { "properties": { "australia_brokerage_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_document_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_quarantine_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_terminal_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_truck_cost": { "$ref": "#/components/schemas/money.Money" }, "reference_weight_grams": { "type": "integer" }, "storage_at_or_over_threshold_cost": { "$ref": "#/components/schemas/money.Money" }, "storage_threshold_grams": { "type": "integer" }, "storage_under_threshold_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_brokerage_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_freight_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_handling_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_inspection_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_transport_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_truck_cost": { "$ref": "#/components/schemas/money.Money" }, "volumetric_divisor_cubic_centimetres_per_kilogram": { "type": "integer" } }, "type": "object" }, "internal_modules_importcompliance.AmbientSeaSettings": { "properties": { "australia_brokerage_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_document_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_freight_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_quarantine_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_terminal_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_truck_cost": { "$ref": "#/components/schemas/money.Money" }, "reference_volume_cubic_centimetres": { "type": "integer" }, "taiwan_brokerage_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_consolidation_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_handling_cost": { "$ref": "#/components/schemas/money.Money" } }, "type": "object" }, "internal_modules_importcompliance.CreateJobInput": { "properties": { "base_revision": { "type": "integer" }, "catalogue_version_id": { "type": "string" }, "evidence_media_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "jurisdiction": { "$ref": "#/components/schemas/compliance_enums.Jurisdiction" }, "kind": { "$ref": "#/components/schemas/internal_modules_importcompliance.JobKind" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } }, "required": [ "kind" ], "type": "object" }, "internal_modules_importcompliance.FrozenSeaSettings": { "properties": { "australia_brokerage_cost": { "$ref": "#/components/schemas/money.Money" }, "australia_port_cost": { "$ref": "#/components/schemas/money.Money" }, "reference_volume_cubic_centimetres": { "type": "integer" }, "taiwan_freight_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_miscellaneous_cost": { "$ref": "#/components/schemas/money.Money" }, "taiwan_stuffing_cost": { "$ref": "#/components/schemas/money.Money" } }, "type": "object" }, "internal_modules_importcompliance.ImportSettings": { "properties": { "air_cargo": { "$ref": "#/components/schemas/internal_modules_importcompliance.AirCargoSettings" }, "ambient_sea": { "$ref": "#/components/schemas/internal_modules_importcompliance.AmbientSeaSettings" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "default_signatory_name": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "export_margin_basis_points": { "type": "integer" }, "frozen_sea": { "$ref": "#/components/schemas/internal_modules_importcompliance.FrozenSeaSettings" }, "id": { "type": "string" }, "ingredient_rules": { "items": { "$ref": "#/components/schemas/internal_modules_importcompliance.IngredientDeclarationRule" }, "type": "array", "uniqueItems": false }, "market_code": { "description": "MarketCode and CountryCode are the denormalized market and country the\nrecord belongs to, carried so a geographically scoped staff query is\na plain indexed match.", "type": "string" }, "next_invoice_number": { "type": "integer" }, "revision": { "$ref": "#/components/schemas/compliance.RevisionMetadata" }, "taiwan_tax_basis_points": { "type": "integer" }, "twd_per_aud_micros": { "type": "integer" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_importcompliance.IngredientDeclarationRule": { "properties": { "id": { "type": "string" }, "ingredients": { "type": "string" }, "statement": { "type": "string" } }, "type": "object" }, "internal_modules_importcompliance.JobKind": { "enum": [ "document_ocr", "structured_proposal", "tariff_catalogue_refresh", "trademark_search", "artifact_render" ], "type": "string", "x-enum-varnames": [ "JobDocumentOCR", "JobStructuredProposal", "JobTariffCatalogueRefresh", "JobTrademarkSearch", "JobArtifactRender" ] }, "internal_modules_importcompliance.ManufacturerDeclaration": { "properties": { "artifacts": { "items": { "$ref": "#/components/schemas/compliance.ArtifactReference" }, "type": "array", "uniqueItems": false }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "declaration_reference": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "evidence": { "items": { "$ref": "#/components/schemas/compliance.EvidenceReference" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/compliance.DeclarationLine" }, "type": "array", "uniqueItems": false }, "manufacturer": { "$ref": "#/components/schemas/compliance.ManufacturerDetails" }, "market_code": { "description": "MarketCode and CountryCode are the denormalized market and country the\nrecord belongs to, carried so a geographically scoped staff query is\na plain indexed match.", "type": "string" }, "purchase_order": { "$ref": "#/components/schemas/compliance.PurchaseOrderSnapshot" }, "revision": { "$ref": "#/components/schemas/compliance.RevisionMetadata" }, "settings_revision_number": { "type": "integer" }, "shipment": { "$ref": "#/components/schemas/compliance.DeclarationShipment" }, "signatory": { "$ref": "#/components/schemas/compliance.DeclarationSignatory" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_inbound.CreateInput": { "properties": { "depot_code": { "type": "string" }, "eta": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_inbound.ItemInput" }, "type": "array", "uniqueItems": false }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "purchase_receipt_id": { "type": "string" }, "reference": { "type": "string" }, "supplier_code": { "type": "string" } }, "required": [ "depot_code", "purchase_order_number", "purchase_receipt_id" ], "type": "object" }, "internal_modules_inbound.ItemInput": { "properties": { "destination_bucket_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "expected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_name": { "type": "string" }, "received_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "scanned_barcode": { "type": "string" }, "sku_code": { "type": "string" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" } }, "required": [ "destination_location", "expected_composition", "handling_unit", "package_option", "received_composition", "sku_code", "storage_type" ], "type": "object" }, "internal_modules_inbound.ReceiptWithItems": { "properties": { "confirmed_at": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "eta": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/warehouse.WarehouseReceiptItem" }, "type": "array", "uniqueItems": false }, "market_code": { "type": "string" }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "purchase_receipt_id": { "type": "string" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/warehouse_enums.InboundReceiptStatus" }, "supplier_code": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "internal_modules_inbound.TransitionInput": { "properties": { "status": { "$ref": "#/components/schemas/warehouse_enums.InboundReceiptStatus" } }, "required": [ "status" ], "type": "object" }, "internal_modules_inbound.UpdateItemsInput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_inbound.ItemInput" }, "type": "array", "uniqueItems": false } }, "required": [ "items" ], "type": "object" }, "internal_modules_layout.CreateLayoutInput": { "properties": { "background_color": { "type": "string" }, "cameras": { "items": { "$ref": "#/components/schemas/warehouse.CameraPreset" }, "type": "array", "uniqueItems": false }, "depot_code": { "type": "string" }, "floor_texture_url": { "type": "string" }, "grid_size_mm": { "type": "integer" }, "name": { "type": "string" }, "note": { "type": "string" }, "origin": { "$ref": "#/components/schemas/geometry.Vector3" }, "primary_model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "unit_scale": { "type": "number" }, "up_axis": { "type": "string" }, "version": { "minimum": 1, "type": "integer" }, "walls": { "items": { "$ref": "#/components/schemas/warehouse.LayoutWall" }, "type": "array", "uniqueItems": false } }, "required": [ "depot_code", "version" ], "type": "object" }, "internal_modules_layout.CreateNodeInput": { "properties": { "code": { "type": "string" }, "color": { "type": "string" }, "is_active": { "type": "boolean" }, "location_code": { "type": "string" }, "model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "name": { "type": "string" }, "parent_code": { "type": "string" }, "shape": { "$ref": "#/components/schemas/warehouse_enums.ShapeType" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "storage": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "transform": { "$ref": "#/components/schemas/geometry.Transform" }, "type": { "$ref": "#/components/schemas/warehouse_enums.LayoutNodeType" } }, "required": [ "code", "type" ], "type": "object" }, "internal_modules_layout.UpdateLayoutInput": { "properties": { "background_color": { "type": "string" }, "cameras": { "items": { "$ref": "#/components/schemas/warehouse.CameraPreset" }, "type": "array", "uniqueItems": false }, "floor_texture_url": { "type": "string" }, "grid_size_mm": { "type": "integer" }, "name": { "type": "string" }, "note": { "type": "string" }, "primary_model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "walls": { "items": { "$ref": "#/components/schemas/warehouse.LayoutWall" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_layout.UpdateNodeInput": { "properties": { "color": { "type": "string" }, "is_active": { "type": "boolean" }, "location_code": { "type": "string" }, "model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "name": { "type": "string" }, "shape": { "$ref": "#/components/schemas/warehouse_enums.ShapeType" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "storage": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "transform": { "$ref": "#/components/schemas/geometry.Transform" } }, "type": "object" }, "internal_modules_listings.BackorderEvidence": { "description": "Short-lived wholesale CASE evidence for zero or insufficient sellable stock. It is not a reservation or ETA.", "properties": { "allowed": { "enum": [ true ], "type": "boolean" }, "base_units": { "format": "int64", "minimum": 1, "type": "integer" }, "captured_at": { "format": "date-time", "type": "string" }, "evidence_token": { "type": "string" }, "handling_unit": { "enum": [ "CASE" ], "type": "string" }, "listing_revision": { "format": "int64", "type": "integer" }, "market_code": { "type": "string" }, "package_count": { "format": "int64", "minimum": 1, "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "units_per_package": { "format": "int64", "minimum": 1, "type": "integer" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "allowed", "sku_code", "market_code", "package_option", "handling_unit", "package_count", "units_per_package", "base_units", "listing_revision", "evidence_token", "valid_until", "captured_at" ], "type": "object" }, "internal_modules_listings.DepotMarketInput": { "properties": { "depot_code": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "is_active": { "type": "boolean" }, "market_code": { "type": "string" } }, "required": [ "depot_code", "market_code" ], "type": "object" }, "internal_modules_listings.EligibilityContext": { "properties": { "channel": { "type": "string" }, "depot_code": { "type": "string" }, "market_code": { "type": "string" } }, "required": [ "channel", "market_code" ], "type": "object" }, "internal_modules_listings.EligibilityItem": { "properties": { "base_units": { "type": "integer" }, "correlation_id": { "maxLength": 64, "type": "string" }, "location_code": { "maxLength": 128, "type": "string" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_exclusive_path": { "description": "RequestedExclusivePath mirrors quote.AppliedPriceRule.Kind and steers\nONLY which inventory is examined. Supply prices nothing, validates no\nfactor, and reports no winning rule. An unrecognised value selects\nstandard-sellable stock.", "type": "string" }, "sku_code": { "type": "string" }, "stock_unit_id": { "maxLength": 128, "type": "string" }, "validity_token": { "description": "ValidityToken is a previously issued snapshot token being revalidated.\nIt is NEVER trusted as evidence in its own right: Supply re-derives\neligibility from stored state every time and only reports whether the\npresented token still names the current revisions.", "type": "string" } }, "required": [ "base_units", "correlation_id", "sku_code", "package_option" ], "type": "object" }, "internal_modules_listings.EligibilityRequest": { "properties": { "context": { "$ref": "#/components/schemas/internal_modules_listings.EligibilityContext" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_listings.EligibilityItem" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "context", "items" ], "type": "object" }, "internal_modules_listings.EligibilityResponse": { "properties": { "market_code": { "type": "string" }, "resolved_at": { "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/internal_modules_listings.EligibilityResult" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_listings.EligibilityResult": { "properties": { "backorder": { "$ref": "#/components/schemas/internal_modules_listings.BackorderEvidence" }, "correlation_id": { "type": "string" }, "eligibility": { "$ref": "#/components/schemas/listing.SaleEligibilitySnapshot" }, "eligible": { "type": "boolean" }, "listing": { "$ref": "#/components/schemas/internal_modules_listings.ListingFacts" }, "non_stock": { "$ref": "#/components/schemas/internal_modules_listings.NonStockEvidence" }, "pos_deficit": { "$ref": "#/components/schemas/internal_modules_listings.POSDeficitEvidence" }, "presented_token_valid": { "type": "boolean" }, "reason": { "type": "string" }, "shortfall": { "$ref": "#/components/schemas/internal_modules_listings.ShortfallFacts" }, "sku": { "$ref": "#/components/schemas/internal_modules_listings.SKUFacts" }, "sku_code": { "type": "string" } }, "type": "object" }, "internal_modules_listings.ListingCatalogueFact": { "additionalProperties": false, "properties": { "found": { "type": "boolean" }, "has_net_content": { "description": "Both net quantity and standard measure pass Supply's net-content validation.", "type": "boolean" }, "product_revision": { "description": "Revision of the product master used to resolve the classification.", "format": "int64", "type": "integer" }, "purchase_classification": { "description": "Explicit Supply product classification; omission means unknown.", "enum": [ "merchandise", "stored_value" ], "type": "string" }, "sellable": { "description": "True only when the product lifecycle status is active.", "type": "boolean" }, "sku_code": { "minLength": 1, "type": "string" } }, "required": [ "sku_code", "found", "sellable", "has_net_content" ], "type": "object" }, "internal_modules_listings.ListingCatalogueFactsAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_listings.ListingCatalogueFactsResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_listings.ListingCatalogueFactsRequest": { "additionalProperties": false, "properties": { "sku_codes": { "description": "Unique nonblank SKU codes. Surrounding whitespace is trimmed before duplicate checks and lookup.", "items": { "minLength": 1, "pattern": "\\S", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "sku_codes" ], "type": "object" }, "internal_modules_listings.ListingCatalogueFactsResponse": { "additionalProperties": false, "properties": { "results": { "description": "One result per requested SKU in exactly request order. Missing SKUs have all three booleans false.", "items": { "$ref": "#/components/schemas/internal_modules_listings.ListingCatalogueFact" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "results" ], "type": "object" }, "internal_modules_listings.ListingFacts": { "properties": { "available_from": { "type": "string" }, "available_until": { "type": "string" }, "expiry_lead_days_override": { "type": "integer" }, "listing_id": { "type": "string" }, "listing_revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "market_code": { "type": "string" }, "policy_contract_version": { "enum": [ "v42.0.0" ], "type": "string" }, "policy_market": { "$ref": "#/components/schemas/internal_modules_listings.PolicyMarket" }, "policy_owner": { "enum": [ "pricing" ], "type": "string" }, "restrictions": { "items": { "$ref": "#/components/schemas/listing.SaleRestriction" }, "type": "array", "uniqueItems": false }, "status": { "$ref": "#/components/schemas/listing_enums.MarketListingStatus" }, "tax_category_code": { "type": "string" } }, "required": [ "listing_id", "market_code", "listing_revision", "policy_owner", "policy_contract_version" ], "type": "object" }, "internal_modules_listings.NonStockEvidence": { "description": "channel=pos only. Signed evidence that the SKU is non-stock (stock_tracked=false, or an OPEN0001..OPEN0020 open-price placeholder); no stock is examined, reserved or settled for it.", "properties": { "base_units": { "type": "integer" }, "captured_at": { "format": "date-time", "type": "string" }, "depot_code": { "type": "string" }, "evidence_token": { "type": "string" }, "listing_revision": { "type": "integer" }, "market_code": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "stock_tracked": { "enum": [ false ], "type": "boolean" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "stock_tracked", "sku_code", "market_code", "depot_code", "package_option", "base_units", "listing_revision", "evidence_token", "valid_until", "captured_at" ], "type": "object" }, "internal_modules_listings.POSDeficitEvidence": { "description": "channel=pos only. Signed evidence that the line may sell beyond sellable stock; settlement books the shortfall as a deficit at deficit_location_code. The evidence_token is not reservation evidence.", "properties": { "allowed": { "enum": [ true ], "type": "boolean" }, "available_base_units": { "type": "integer" }, "captured_at": { "format": "date-time", "type": "string" }, "deficit_location_code": { "type": "string" }, "depot_code": { "type": "string" }, "evidence_token": { "type": "string" }, "inventory_reason": { "enum": [ "NO_SELLABLE_INVENTORY", "INSUFFICIENT_BASE_UNITS" ], "type": "string" }, "listing_revision": { "type": "integer" }, "market_code": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "requested_base_units": { "type": "integer" }, "short_base_units": { "type": "integer" }, "sku_code": { "type": "string" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "allowed", "sku_code", "market_code", "depot_code", "deficit_location_code", "package_option", "requested_base_units", "available_base_units", "short_base_units", "inventory_reason", "listing_revision", "evidence_token", "valid_until", "captured_at" ], "type": "object" }, "internal_modules_listings.POSMerchandiseAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_listings.POSMerchandiseResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_listings.POSMerchandiseEvidence": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "captured_at": { "format": "date-time", "type": "string" }, "depot_code": { "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "listing_revision": { "format": "int64", "type": "integer" }, "market_code": { "type": "string" }, "market_revision": { "format": "int64", "type": "integer" }, "package_count": { "format": "int64", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_facts_digest": { "type": "string" }, "sku_code": { "type": "string" }, "tax_category_code": { "type": "string" }, "tax_category_revision": { "format": "int64", "type": "integer" }, "tax_rule_id": { "type": "string" }, "tax_rule_revision": { "format": "int64", "type": "integer" }, "token": { "type": "string" }, "units_per_package": { "format": "int64", "type": "integer" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "sku_code", "market_code", "depot_code", "package_option", "handling_unit", "package_count", "units_per_package", "base_units", "listing_revision", "market_revision", "tax_category_revision", "tax_category_code", "tax_rule_id", "product_facts_digest", "tax_rule_revision", "token", "captured_at", "valid_until" ], "type": "object" }, "internal_modules_listings.POSMerchandiseResponse": { "properties": { "market_code": { "type": "string" }, "resolved_at": { "format": "date-time", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/internal_modules_listings.POSMerchandiseResult" }, "type": "array" } }, "required": [ "results", "market_code", "resolved_at" ], "type": "object" }, "internal_modules_listings.POSMerchandiseResult": { "properties": { "correlation_id": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/internal_modules_listings.POSMerchandiseEvidence" }, "listing": { "$ref": "#/components/schemas/internal_modules_listings.ListingFacts" }, "merchandise_eligible": { "type": "boolean" }, "presented_token_valid": { "type": "boolean" }, "reason": { "type": "string" }, "sku": { "$ref": "#/components/schemas/internal_modules_listings.SKUFacts" }, "sku_code": { "type": "string" } }, "required": [ "correlation_id", "sku_code", "merchandise_eligible" ], "type": "object" }, "internal_modules_listings.PackageAuthoringComponent": { "additionalProperties": false, "properties": { "base_units": { "format": "int64", "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "package_count": { "const": 1, "format": "int64", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringExactRef" }, "units_per_package": { "format": "int64", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": [ "package_option", "handling_unit", "package_count", "units_per_package", "base_units" ], "type": "object" }, "internal_modules_listings.PackageAuthoringComposition": { "additionalProperties": false, "properties": { "components": { "items": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringComponent" }, "maxItems": 1, "minItems": 1, "type": "array" }, "total_base_units": { "format": "int64", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": [ "total_base_units", "components" ], "type": "object" }, "internal_modules_listings.PackageAuthoringEvidenceAPIResponse": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringEvidenceResponse" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_listings.PackageAuthoringEvidenceItem": { "additionalProperties": false, "properties": { "correlation_id": { "maxLength": 128, "minLength": 1, "pattern": "^[^\\s\\x00-\\x1F\\x7F-\\x9F]+$", "type": "string" }, "expected_catalogue_revision": { "anyOf": [ { "pattern": "^(|catalogue:v1:[0-9a-f]{64})$", "type": "string" }, { "type": "null" } ], "description": "Optional approved catalogue fingerprint; omitted, null or empty means no expected baseline. Any nonempty mismatch fails the entire request with 409." }, "expected_measurement_revision": { "anyOf": [ { "pattern": "^(|measurement:v1:[0-9a-f]{64})$", "type": "string" }, { "type": "null" } ], "description": "Optional approved measurement fingerprint; omitted, null or empty means no expected baseline. Any nonempty mismatch fails the entire request with 409." }, "package_option": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringExactRef" }, { "type": "null" } ], "description": "Omitted or null discovers this SKU's stored package versions. A present exact tuple must match the outer SKU and is revalidated without selecting another version." }, "sku_code": { "maxLength": 128, "minLength": 1, "pattern": "^[^\\s\\x00-\\x1F\\x7F-\\x9F]+$", "type": "string" } }, "required": [ "correlation_id", "sku_code" ], "type": "object" }, "internal_modules_listings.PackageAuthoringEvidenceRequest": { "additionalProperties": false, "properties": { "items": { "description": "Correlation IDs, discovery SKUs and exact package tuples are each unique. Discovery and distinct exact references for one SKU can coexist and share the same source fingerprints.", "items": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringEvidenceItem" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "items" ], "type": "object" }, "internal_modules_listings.PackageAuthoringEvidenceResponse": { "additionalProperties": false, "properties": { "evidence_schema_version": { "const": 1, "type": "integer" }, "observed_at": { "description": "One Supply UTC instant evaluated after the catalogue batch read. Qualification uses this actual instant, never a caller-supplied future listing date.", "format": "date-time", "type": "string" }, "results": { "items": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringEvidenceResult" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "evidence_schema_version", "observed_at", "results" ], "type": "object" }, "internal_modules_listings.PackageAuthoringEvidenceResult": { "additionalProperties": false, "properties": { "catalogue_revision": { "description": "Versioned semantic SHA256 over found/SKU/product lifecycle and all canonical-sorted full package master definitions, with UTC-normalized windows. Excludes measurement, unrelated display/audit/metrics and observation time. Discovery and exact modes return the same fingerprint.", "pattern": "^catalogue:v1:[0-9a-f]{64}$", "type": "string" }, "correlation_id": { "type": "string" }, "found": { "type": "boolean" }, "measurement_present": { "type": "boolean" }, "measurement_revision": { "description": "Versioned semantic SHA256 over found/SKU and exact native measurement presence/value, independently of package version or lifecycle. Explicit absence has its own fingerprint.", "pattern": "^measurement:v1:[0-9a-f]{64}$", "type": "string" }, "net_content": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredNetContent" }, { "type": "null" } ], "description": "Raw owner measurement or explicit null, never a default quantity or unit. Malformed declared measurement is present but unqualified." }, "packages": { "description": "All stored package versions in deterministic tuple/definition order for discovery; one matching option for exact mode, or empty if absent. Inactive, future, expired and invalid options remain visible with refusal reasons. Never truncated.", "items": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringPackageEvidence" }, "maxItems": 1000, "type": "array" }, "product_status": { "description": "Native product lifecycle status, omitted when the SKU is absent.", "type": "string" }, "qualified": { "description": "Exact mode requires that package to qualify. Discovery requires at least one qualified package. Product activity and valid declared measurement are required; absent measurement alone does not block manual selling prices.", "type": "boolean" }, "reason": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "correlation_id", "sku_code", "found", "qualified", "reason", "catalogue_revision", "measurement_revision", "measurement_present", "net_content", "packages" ], "type": "object" }, "internal_modules_listings.PackageAuthoringExactRef": { "additionalProperties": false, "properties": { "code": { "pattern": "^(EACH|CASE[1-9][0-9]*)$", "type": "string" }, "sku_code": { "maxLength": 128, "minLength": 1, "pattern": "^[^\\s\\x00-\\x1F\\x7F-\\x9F]+$", "type": "string" }, "version": { "format": "int64", "maximum": 9007199254740991, "minimum": 1, "type": "integer" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "internal_modules_listings.PackageAuthoringPackageEvidence": { "additionalProperties": false, "properties": { "composition": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringComposition" }, { "type": "null" } ], "description": "One native package only when its physical evidence is valid and unambiguous; otherwise null. A non-null composition alone does not imply lifecycle or measurement qualification." }, "package_option": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredRef", "description": "Exact stored tuple; an invalid stored tuple is exposed only as unqualified evidence, never repaired or inferred." }, "product_package_option": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredOption" }, "qualified": { "type": "boolean" }, "reason": { "description": "Supply-owned qualification reason. Consumers fail closed on unknown reasons and require qualified=true.", "type": "string" } }, "required": [ "package_option", "product_package_option", "composition", "qualified", "reason" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredDimensions": { "additionalProperties": false, "properties": { "height_mm": { "format": "int64", "type": "integer" }, "length_mm": { "format": "int64", "type": "integer" }, "width_mm": { "format": "int64", "type": "integer" } }, "required": [ "width_mm", "length_mm", "height_mm" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredMeasure": { "additionalProperties": false, "properties": { "amount": { "format": "int64", "type": "integer" }, "exponent": { "type": "integer" }, "unit": { "type": "string" } }, "required": [ "amount", "exponent", "unit" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredNetContent": { "additionalProperties": false, "description": "Raw native declared measurement, including malformed values in unqualified evidence. Absence is represented by null at the enclosing property.", "properties": { "net_quantity": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredMeasure" }, "standard_measure": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredMeasure" } }, "required": [ "net_quantity", "standard_measure" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredOption": { "additionalProperties": false, "description": "Exact native ProductPackageOption wire facts. This raw schema deliberately accepts malformed persisted values; qualified=false and reasons distinguish them from usable evidence.", "properties": { "code": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredDimensions" }, "effective_from": { "format": "date-time", "type": "string" }, "effective_to": { "format": "date-time", "type": "string" }, "handling_unit": { "type": "string" }, "is_active": { "type": "boolean" }, "is_canonical": { "type": "boolean" }, "sku_code": { "type": "string" }, "units_per_package": { "format": "int64", "type": "integer" }, "version": { "format": "int64", "type": "integer" }, "weight": { "$ref": "#/components/schemas/internal_modules_listings.PackageAuthoringStoredWeight" } }, "required": [ "sku_code", "code", "version", "handling_unit", "units_per_package", "is_active", "is_canonical", "effective_from" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredRef": { "additionalProperties": false, "description": "Raw stored identity, including malformed values only in unqualified evidence. Qualification never repairs these fields.", "properties": { "code": { "type": "string" }, "sku_code": { "type": "string" }, "version": { "format": "int64", "type": "integer" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "internal_modules_listings.PackageAuthoringStoredWeight": { "additionalProperties": false, "properties": { "grams": { "format": "int64", "type": "integer" } }, "required": [ "grams" ], "type": "object" }, "internal_modules_listings.PolicyMarket": { "additionalProperties": false, "properties": { "market_code": { "type": "string" }, "market_default_timezone": { "type": "string" }, "market_revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "status": { "enum": [ "draft", "active", "suspended", "retired" ], "type": "string" } }, "required": [ "market_code", "market_revision", "market_default_timezone", "status" ], "type": "object" }, "internal_modules_listings.PromotionCandidate": { "properties": { "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array" }, "collection_code": { "type": "string" }, "cover_media_code": { "type": "string" }, "cover_url": { "description": "Supply-origin-relative managed media content URL; omitted when no cover is configured.", "type": "string" }, "handling_unit": { "enum": [ "EACH", "CASE" ], "type": "string" }, "listing_revision": { "format": "int64", "type": "integer" }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_name": { "type": "string" }, "sku_code": { "type": "string" }, "tax_category_code": { "type": "string" }, "units_per_package": { "format": "int64", "type": "integer" } }, "required": [ "sku_code", "product_name", "package_option", "units_per_package", "handling_unit", "category_tags", "listing_revision", "tax_category_code" ], "type": "object" }, "internal_modules_listings.PromotionCandidateAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_listings.PromotionCandidateResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_listings.PromotionCandidateRequest": { "properties": { "after": { "maxLength": 2048, "type": "string" }, "channel": { "enum": [ "online", "pos", "b2b", "relay", "manual", "import" ], "type": "string" }, "limit": { "default": 100, "maximum": 200, "minimum": 1, "type": "integer" }, "market_code": { "maxLength": 128, "type": "string" }, "search": { "maxLength": 200, "type": "string" } }, "required": [ "market_code", "channel" ], "type": "object" }, "internal_modules_listings.PromotionCandidateResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_listings.PromotionCandidate" }, "type": "array" }, "next_after": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "internal_modules_listings.SKUFacts": { "properties": { "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array" }, "collection_code": { "type": "string" }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" }, "net_content_missing": { "description": "NetContentMissing states the absence rather than leaving it to be\ninferred from a missing key. A consumer that forgot to handle nil sees an\nexplicit true instead of silently pricing per-unit as if the fact existed.", "type": "boolean" }, "package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "description": "SKUCode is the human-readable code, and it is here because\norder.CartItem.SKUCode is frozen RECEIPT EVIDENCE with no omitempty: a\nreceipt has to state what was sold years after the fact, and this is the\ncall Orders makes at cart-add, when that evidence is captured.\n\nIt is an EXPLICIT projection of SKU.Code, never a copy of SKUCode. Supply\nstores the two as the same value today, but a consumer deriving the code\nfrom the id would bake a wrong code into permanent evidence the day that\nstops holding — and nothing downstream could tell it from a real one.", "type": "string" }, "status": { "type": "string" }, "storage_type": { "type": "string" } }, "type": "object" }, "internal_modules_listings.ShortfallFacts": { "description": "The known gap behind a channel=pos NO_SELLABLE_INVENTORY or INSUFFICIENT_BASE_UNITS refusal. available_base_units is the standard-sellable net stock at the depot, capped at the request.", "properties": { "available_base_units": { "type": "integer" }, "requested_base_units": { "type": "integer" }, "short_base_units": { "type": "integer" } }, "required": [ "requested_base_units", "available_base_units", "short_base_units" ], "type": "object" }, "internal_modules_listings.UpdateDepotMarketInput": { "properties": { "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "expected_revision": { "type": "integer" }, "is_active": { "type": "boolean" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_listings.internalSaleEligibilityAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_listings.EligibilityResponse" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_media.BrowsableObject": { "properties": { "content_type": { "type": "string" }, "media_code": { "type": "string" }, "name": { "type": "string" }, "size_bytes": { "type": "integer" }, "updated_at": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "internal_modules_media.BucketObjectList": { "properties": { "bucket": { "type": "string" }, "folders": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "objects": { "items": { "$ref": "#/components/schemas/internal_modules_media.BrowsableObject" }, "type": "array", "uniqueItems": false }, "prefix": { "type": "string" } }, "type": "object" }, "internal_modules_media.FinalizeRequest": { "properties": { "upload_id": { "type": "string" } }, "required": [ "upload_id" ], "type": "object" }, "internal_modules_media.Header": { "properties": { "name": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "internal_modules_media.UploadRequest": { "properties": { "filename": { "type": "string" }, "folder": { "description": "Upload destination from GET /media/folders. Brand logos use brand-logo (public image, at most 5 MiB, no SKU required). Product selection badge icons use selection-badge-icon (public image, at most 2 MiB) and selection covers use selection-cover (public image, at most 5 MiB); both require the selection code in sku_code.", "type": "string" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sku_code": { "description": "Owning entity code for entity-scoped folders. Required for product-cover, product-gallery and product-detail\n(the product SKU code) and for selection-badge-icon and selection-cover (the server-generated selection code, for example 7KQ2M9XA;\nobjects are stored under selection/\u003cCODE\u003e/badge-icon/ and selection/\u003cCODE\u003e/cover/).\nOmit for other folders, including brand-logo and collection-icon.", "type": "string" } }, "required": [ "filename", "folder", "mime_type", "size_bytes" ], "type": "object" }, "internal_modules_media.UploadResponse": { "properties": { "expires_at": { "type": "string" }, "headers": { "items": { "$ref": "#/components/schemas/internal_modules_media.Header" }, "type": "array", "uniqueItems": false }, "max_bytes": { "type": "integer" }, "method": { "type": "string" }, "upload_id": { "type": "string" }, "upload_url": { "type": "string" } }, "type": "object" }, "internal_modules_media.bucketListAPIResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_gcsstorage.BucketInfo" }, "type": "array", "uniqueItems": false }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_media.bucketObjectListAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_media.BucketObjectList" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_netgoods.Advice": { "description": "Private depot advice. Valued units include the provisional subset; unvalued units have no asserted cost. Average covers valued units only. Movements contains the latest 200 postings; physical/source history is immutable.", "properties": { "currency_exponent_available": { "type": "boolean" }, "movements": { "items": { "$ref": "#/components/schemas/procurement.NetGoodsValuationMovement" }, "type": "array" }, "snapshot": { "$ref": "#/components/schemas/procurement.NetGoodsValuationSnapshot" }, "sources": { "items": { "$ref": "#/components/schemas/internal_modules_netgoods.Source" }, "type": "array" }, "sources_truncated": { "description": "True when current source coverage exceeds the bounded advice response.", "type": "boolean" } }, "required": [ "currency_exponent_available", "sources_truncated", "snapshot", "sources", "movements" ], "type": "object" }, "internal_modules_netgoods.Contribution": { "properties": { "active": { "type": "boolean" }, "amount_minor": { "format": "int64", "type": "integer" }, "invoice_id": { "type": "string" }, "line_id": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "source": { "$ref": "#/components/schemas/procurement.NetGoodsCostSourceSnapshot" }, "units": { "format": "int64", "type": "integer" } }, "required": [ "invoice_id", "line_id", "revision", "units", "amount_minor", "active", "source" ], "type": "object" }, "internal_modules_netgoods.CostEvidence": { "description": "Explicit admin evidence for standalone intake or stock-count gain. A gain requires net_goods_amount; absent evidence is unavailable, never a free amount.", "properties": { "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "net_goods_amount": { "$ref": "#/components/schemas/money.Money" }, "reason": { "type": "string" } }, "required": [ "currency", "currency_exponent", "reason" ], "type": "object" }, "internal_modules_netgoods.FinancialAdjustment": { "properties": { "amount_minor": { "format": "int64", "type": "integer" }, "base_units": { "format": "int64", "type": "integer" }, "confirmed_at": { "format": "date-time", "type": "string" }, "credit_id": { "type": "string" }, "credit_line_id": { "type": "string" }, "invoice_id": { "type": "string" }, "invoice_line_id": { "type": "string" }, "kind": { "type": "string" }, "original_issue_movement_id": { "type": "string" }, "receipt_id": { "type": "string" }, "receipt_item_id": { "type": "string" }, "revision": { "format": "int64", "type": "integer" } }, "required": [ "credit_id", "credit_line_id", "invoice_id", "invoice_line_id", "receipt_id", "receipt_item_id", "kind", "base_units", "amount_minor", "revision", "confirmed_at" ], "type": "object" }, "internal_modules_netgoods.Source": { "properties": { "contributions": { "items": { "$ref": "#/components/schemas/internal_modules_netgoods.Contribution" }, "type": "array" }, "currency": { "type": "string" }, "evidence": { "$ref": "#/components/schemas/procurement.NetGoodsCostSourceSnapshot" }, "key": { "type": "string" }, "provisional_exact": { "type": "string" }, "units": { "format": "int64", "type": "integer" } }, "required": [ "key", "units", "evidence" ], "type": "object" }, "internal_modules_packing.CaseOption": { "properties": { "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "source": { "enum": [ "frozen", "catalogue" ], "type": "string" }, "units_per_package": { "format": "int64", "minimum": 2, "type": "integer" } }, "required": [ "package_option", "units_per_package", "source" ], "type": "object" }, "internal_modules_packing.CommandResponse": { "properties": { "packing_order": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "replayed": { "type": "boolean" } }, "required": [ "packing_order", "replayed" ], "type": "object" }, "internal_modules_packing.CreateInput": { "properties": { "lines": { "items": { "$ref": "#/components/schemas/fulfilment.PackingLine" }, "type": "array", "uniqueItems": false }, "operator": { "type": "string" }, "order_number": { "type": "string" } }, "required": [ "order_number" ], "type": "object" }, "internal_modules_packing.DamageInput": { "properties": { "affected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "allocation_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "evidence_media_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "expected_reservation_revision": { "type": "integer" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "expected_source_revision": { "type": "integer" }, "handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "idempotency_key": { "type": "string" }, "issue_movement_id": { "description": "Identifies the already packed stock being quarantined. Omit for unissued reserved stock.", "type": "string" }, "note": { "type": "string" }, "order_item_id": { "type": "string" }, "product_name": { "type": "string" }, "reason_code": { "type": "string" }, "reservation_id": { "type": "string" }, "sku_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "required": [ "expected_revision", "affected_composition", "allocation_id", "destination_location", "expected_reservation_revision", "expected_source_revision", "handling", "idempotency_key", "order_item_id", "reason_code", "reservation_id", "sku_code", "source_bucket_id" ], "type": "object" }, "internal_modules_packing.HistoryRow": { "allOf": [ { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, { "properties": { "has_damage": { "type": "boolean" }, "order_fulfillment_status": { "type": "string" }, "order_status": { "type": "string" }, "owner_observed_at": { "format": "date-time", "type": "string" }, "payment_status": { "type": "string" }, "refund_status": { "type": "string" }, "superseded": { "type": "boolean" } }, "required": [ "order_status", "payment_status", "order_fulfillment_status", "refund_status", "has_damage", "superseded", "owner_observed_at" ], "type": "object" } ] }, "internal_modules_packing.IntakeInput": { "properties": { "order_numbers": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "order_numbers" ], "type": "object" }, "internal_modules_packing.IntakeResult": { "properties": { "error": { "type": "string" }, "ok": { "type": "boolean" }, "order_number": { "type": "string" } }, "type": "object" }, "internal_modules_packing.LineMetadata": { "properties": { "barcodes": { "items": { "$ref": "#/components/schemas/internal_modules_packing.PackingBarcode" }, "type": "array" }, "case_options": { "items": { "$ref": "#/components/schemas/internal_modules_packing.CaseOption" }, "type": "array" }, "metadata_status": { "enum": [ "ready", "unavailable" ], "type": "string" }, "order_item_id": { "type": "string" }, "product_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "sku_code": { "type": "string" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" } }, "required": [ "order_item_id", "sku_code", "metadata_status", "product_names", "barcodes", "case_options" ], "type": "object" }, "internal_modules_packing.MarkPackedInput": { "additionalProperties": false, "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_packing.PackingBarcode": { "properties": { "handling_unit": { "enum": [ "EACH", "CASE" ], "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "units_per_package": { "format": "int64", "minimum": 1, "type": "integer" }, "value": { "type": "string" } }, "required": [ "value", "package_option", "handling_unit", "units_per_package" ], "type": "object" }, "internal_modules_packing.PackingDiscrepancyResponse": { "properties": { "customer_name": { "type": "string" }, "damage_handling": { "$ref": "#/components/schemas/warehouse_enums.PackingDamageHandling" }, "id": { "type": "string" }, "kind": { "$ref": "#/components/schemas/warehouse_enums.PackingDiscrepancyKind" }, "notified": { "type": "boolean" }, "observed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_date": { "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "product_name": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "recorded_at": { "type": "string" }, "recorded_by": { "type": "string" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "withdrawals": { "description": "Shortage units taken back or reinstated, oldest first. The remaining shortage is requested_composition.total_base_units - observed_composition.total_base_units - the withdrawn_base_units of command and scan entries + the withdrawn_base_units of reinstate entries; zero means the shortage was withdrawn in full and stays as audit evidence.", "items": { "$ref": "#/components/schemas/fulfilment.PackingDiscrepancyWithdrawal" }, "type": "array" } }, "type": "object" }, "internal_modules_packing.PackingEvidence": { "properties": { "packing": { "$ref": "#/components/schemas/fulfilment.PackingRecord" }, "settlement": { "anyOf": [ { "$ref": "#/components/schemas/internal_modules_stock.PackingSettlementEvidence" }, { "type": "null" } ] }, "shortages": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PickingShortageEvidence" }, "nullable": true, "type": "array" }, "stock_settled_at": { "format": "date-time", "nullable": true, "type": "string" } }, "required": [ "packing", "settlement", "shortages", "stock_settled_at" ], "type": "object" }, "internal_modules_packing.PackingIssuedSourcePage": { "properties": { "next_cursor": { "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "packing_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "sources": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingIssuedSource" }, "type": "array" } }, "required": [ "packing_revision", "order_number", "order_item_id", "sources" ], "type": "object" }, "internal_modules_packing.PackingStage": { "properties": { "box_count": { "description": "Box count of the latest print.", "maximum": 999, "minimum": 1, "type": "integer" }, "labels_printed_at": { "description": "First label print of the group in the current packing cycle.", "format": "date-time", "type": "string" }, "last_printed_at": { "description": "Latest reprint; omitted until the group is reprinted.", "format": "date-time", "type": "string" }, "packed_by": { "description": "Authenticated staff member whose print first recorded the group in the current packing cycle.", "type": "string" }, "storage_group": { "$ref": "#/components/schemas/internal_modules_packing.StorageGroup" } }, "required": [ "storage_group", "packed_by", "labels_printed_at", "box_count" ], "type": "object" }, "internal_modules_packing.ProgressInput": { "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "frozen_box_count": { "description": "Supply together with other_box_count; zero is explicit.", "format": "int64", "minimum": 0, "type": "integer" }, "idempotency_key": { "description": "Required for a packed quantity change; retry the exact request with the same key.", "maxLength": 128, "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/fulfilment.PackingLine" }, "type": "array", "uniqueItems": false }, "missing_order_item_ids": { "description": "Item IDs with a staff-recorded remaining missing quantity; previously recorded decisions are retained. A line with a recorded shortage keeps its observed packed quantity and may grow only by shortage units taken back; packing it past the requested quantity less the remaining shortage withdraws the excess with method scan.", "items": { "type": "string" }, "type": "array" }, "other_box_count": { "description": "Supply together with frozen_box_count; non-frozen boxes are chilled when the order contains chilled items.", "format": "int64", "minimum": 0, "type": "integer" }, "physical_return_confirmed": { "description": "Required to restore previously issued stock when reducing a packed quantity.", "type": "boolean" }, "reason": { "description": "Staff reason required for an audited physical return correction.", "type": "string" }, "return_selections": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingReturnSelection" }, "type": "array" }, "source_selections": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingSourceSelection" }, "type": "array" } }, "required": [ "lines", "expected_revision" ], "type": "object" }, "internal_modules_packing.RecordResponse": { "properties": { "closed_at": { "type": "string" }, "closed_reason": { "type": "string" }, "containers": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerPlan" }, "type": "array", "uniqueItems": false }, "created_at": { "type": "string" }, "customer_name": { "type": "string" }, "damages": { "items": { "$ref": "#/components/schemas/fulfilment.PackingDamage" }, "type": "array", "uniqueItems": false }, "discrepancies": { "items": { "$ref": "#/components/schemas/internal_modules_packing.PackingDiscrepancyResponse" }, "type": "array", "uniqueItems": false }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "line_metadata": { "description": "Present on single-order responses; current catalogue display facts and frozen case-size choices do not rewrite historical lines.", "items": { "$ref": "#/components/schemas/internal_modules_packing.LineMetadata" }, "type": "array" }, "lines": { "items": { "$ref": "#/components/schemas/fulfilment.PackingLine" }, "type": "array", "uniqueItems": false }, "next_container_code": { "description": "Last six order-number characters followed by a hyphen and the next sequence, padded to at least two digits.", "type": "string" }, "next_container_sequence": { "description": "Next order-scoped sequence from a persisted high-water mark; zero only when exhausted.", "format": "int64", "type": "integer" }, "operator": { "type": "string" }, "order_number": { "type": "string" }, "packed_at": { "type": "string" }, "packing_write_ready": { "description": "Optional positive, point-in-time readiness for the displayed packing revision after current refund and paid-remainder owner checks. Absence means unknown; writes independently recheck owners.", "properties": { "order_updated_at": { "format": "date-time", "type": "string" }, "packing_revision": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "packing_revision", "order_updated_at" ], "type": "object" }, "replacement_allocations": { "items": { "$ref": "#/components/schemas/inventory.StockReservationAllocation" }, "type": "array", "uniqueItems": false }, "revision": { "type": "integer" }, "stages": { "description": "Per storage group, who packed it and when its labels printed, ordered AMBIENT_CHILLED then FROZEN. A group without a printed label has no entry; omitted when no group has printed.", "items": { "$ref": "#/components/schemas/internal_modules_packing.PackingStage" }, "type": "array" }, "started_at": { "type": "string" }, "status": { "$ref": "#/components/schemas/order_enums.FulfillmentStatus" }, "stock_settled_at": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_packing.ScanInput": { "additionalProperties": false, "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "mode": { "enum": [ "each", "case" ], "type": "string" }, "order_item_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "source_selections": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingSourceSelection" }, "type": "array" } }, "required": [ "expected_revision", "idempotency_key", "order_item_id", "sku_code", "mode", "package_option" ], "type": "object" }, "internal_modules_packing.ShortageReinstatementInput": { "additionalProperties": false, "properties": { "base_units": { "description": "Withdrawn base units to record missing again; at most the withdrawn units not yet packed.", "format": "int64", "minimum": 1, "type": "integer" }, "discrepancy_id": { "description": "The item's shortage discrepancy.", "minLength": 1, "type": "string" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "description": "The same key and request replays the result; the same key with a different request answers 409 CONFLICT.", "maxLength": 128, "minLength": 1, "type": "string" }, "source_selections": { "items": { "$ref": "#/components/schemas/packing.ShortageAllocationSelection" }, "type": "array" }, "withdrawn_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "required": [ "discrepancy_id", "base_units", "expected_revision", "idempotency_key" ], "type": "object" }, "internal_modules_packing.ShortageWithdrawalInput": { "additionalProperties": false, "properties": { "base_units": { "description": "Shortage base units to take back; at most the remaining shortage. A partial withdrawal leaves the rest recorded missing.", "format": "int64", "minimum": 1, "type": "integer" }, "discrepancy_id": { "description": "The item's shortage discrepancy.", "minLength": 1, "type": "string" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "description": "The same key and request replays the result; the same key with a different request answers 409 CONFLICT.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "discrepancy_id", "base_units", "expected_revision", "idempotency_key" ], "type": "object" }, "internal_modules_packing.StageInput": { "additionalProperties": false, "properties": { "box_count": { "maximum": 999, "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "labels_printed_at": { "description": "When the labels printed; at most five minutes in the future.", "format": "date-time", "type": "string" }, "packing_id": { "description": "The order's current packing record ID.", "minLength": 1, "type": "string" }, "storage_group": { "$ref": "#/components/schemas/internal_modules_packing.StorageGroup" } }, "required": [ "packing_id", "storage_group", "box_count", "labels_printed_at", "idempotency_key" ], "type": "object" }, "internal_modules_packing.StorageGroup": { "description": "Packing stage storage group. Ambient and chilled boxes are packed together; frozen boxes separately.", "enum": [ "AMBIENT_CHILLED", "FROZEN" ], "type": "string" }, "internal_modules_purchasing.CancelSupplierInvoiceInput": { "properties": { "expected_revision": { "format": "int64", "type": "integer" }, "reason": { "type": "string" } }, "required": [ "expected_revision", "reason" ], "type": "object" }, "internal_modules_purchasing.ConfirmSupplierInvoiceInput": { "properties": { "accept_declared_tax": { "description": "AcceptDeclaredTax resolves a disagreement between the supplier's stated\ntax and the figure derived from the declared rate, by taking the\nsupplier's. It is an explicit human decision recorded on the invoice,\nnever an automatic tolerance: a silent tolerance is a rule nobody agreed.", "type": "boolean" }, "expected_revision": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "expected_revision" ], "type": "object" }, "internal_modules_purchasing.CreateInput": { "additionalProperties": false, "description": "Native package_items freeze exact active/effective SKU/package/version facts server-side; selected_package_cost is per selected package. Counts, amounts, base units and totals must fit JSON safe integers. Client snapshots and totals are forbidden. PATCH omission preserves lines; supplied null/empty package_items refuse. Internal replenishment base-unit accounting is not an HTTP input.", "properties": { "currency": { "type": "string" }, "currency_exponent": { "allOf": [ { "$ref": "#/components/schemas/money.CurrencyExponent" }, { "required": [ "currency", "exponent" ], "type": "object" } ], "description": "Explicit matching supported precision. Required for package_items; uses the same pinned ISO 4217 snapshot as GET /v1/purchase-orders/currencies. It does not imply an exchange rate or alter historical valuation." }, "expected_at": { "type": "string" }, "internal_note": { "type": "string" }, "note": { "type": "string" }, "order_number": { "type": "string" }, "package_items": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.PackageItemInput" }, "maxItems": 100, "minItems": 1, "type": "array" }, "reference": { "type": "string" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" } }, "required": [ "currency", "order_number", "currency_exponent", "package_items" ], "type": "object" }, "internal_modules_purchasing.CreditLifecycleInput": { "properties": { "expected_revision": { "format": "int64", "type": "integer" }, "reason": { "type": "string" } }, "required": [ "expected_revision", "reason" ], "type": "object" }, "internal_modules_purchasing.EditSupplierInvoiceInput": { "properties": { "expected_revision": { "format": "int64", "type": "integer" }, "invoice": { "$ref": "#/components/schemas/internal_modules_purchasing.RecordSupplierInvoiceInput" } }, "required": [ "expected_revision", "invoice" ], "type": "object" }, "internal_modules_purchasing.PackageItemInput": { "additionalProperties": false, "properties": { "note": { "type": "string" }, "package_count": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "selected_package_cost": { "$ref": "#/components/schemas/internal_modules_purchasing.SelectedPackageCostInput" } }, "required": [ "package_option", "package_count", "selected_package_cost" ], "type": "object" }, "internal_modules_purchasing.RecordSupplierCreditInput": { "properties": { "credit_number": { "type": "string" }, "currency": { "type": "string" }, "document_reference": { "type": "string" }, "document_sha256": { "type": "string" }, "issue_date": { "type": "string" }, "kind": { "enum": [ "price_correction", "returned_goods", "non_goods_compensation" ], "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCreditLine" }, "type": "array" }, "reason": { "type": "string" } }, "required": [ "credit_number", "kind", "currency", "issue_date", "lines", "document_reference", "document_sha256", "reason" ], "type": "object" }, "internal_modules_purchasing.RecordSupplierInvoiceInput": { "properties": { "business_number": { "type": "string" }, "business_number_scheme": { "description": "BusinessNumberScheme names the register, for example \"abn\". The number\nalone is meaningless without it: an eleven-digit string is an ABN in\nAustralia and something else elsewhere.", "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "declared_tax_total_minor": { "type": "integer" }, "document_reference": { "description": "DocumentReference and DocumentSHA256 are the immutable pointer to the\nartefact. The hash makes it tamper-evident: an invoice claimed against\nhas to be producible later, and producible AND unchanged are different\nguarantees.", "type": "string" }, "document_sha256": { "type": "string" }, "invoice_number": { "type": "string" }, "issue_date": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierInvoiceLineInput" }, "maxItems": 250, "minItems": 1, "type": "array", "uniqueItems": false }, "media_code": { "type": "string" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" }, "tax_registered": { "type": "boolean" }, "tax_registered_from": { "type": "string" } }, "required": [ "currency", "document_reference", "document_sha256", "invoice_number", "issue_date", "lines", "supplier_code", "supplier_name" ], "type": "object" }, "internal_modules_purchasing.SelectedPackageCostInput": { "additionalProperties": false, "properties": { "amount_minor": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "currency": { "pattern": "^[A-Z]{3}$", "type": "string" } }, "required": [ "amount_minor", "currency" ], "type": "object" }, "internal_modules_purchasing.SupplierCredit": { "properties": { "cancellation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "confirmation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "credit_number": { "type": "string" }, "currency": { "type": "string" }, "document": { "$ref": "#/components/schemas/procurement.SupplierInvoiceDocument" }, "id": { "type": "string" }, "invoice_id": { "type": "string" }, "issue_date": { "type": "string" }, "kind": { "enum": [ "price_correction", "returned_goods", "non_goods_compensation" ], "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCreditLine" }, "type": "array" }, "recorded": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "revision": { "format": "int64", "type": "integer" }, "status": { "enum": [ "draft", "confirmed", "cancelled" ], "type": "string" } }, "required": [ "id", "invoice_id", "credit_number", "kind", "currency", "issue_date", "lines", "document", "revision", "status", "recorded" ], "type": "object" }, "internal_modules_purchasing.SupplierCreditLine": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "invoice_line_id": { "type": "string" }, "net_goods_amount_minor": { "format": "int64", "type": "integer" }, "original_issue_movement_id": { "type": "string" }, "receipt_id": { "type": "string" }, "receipt_item_id": { "type": "string" } }, "required": [ "id", "invoice_line_id", "base_units", "net_goods_amount_minor" ], "type": "object" }, "internal_modules_purchasing.SupplierInvoiceLineInput": { "properties": { "base_units": { "description": "Invoiced quantity in base units; must be an exact multiple of units_per_package.", "minimum": 1, "type": "integer" }, "declared_tax_minor": { "description": "DeclaredTaxMinor is the supplier's own stated figure for this line, or\nnil when they stated none. It is recorded as given and never rewritten.", "type": "integer" }, "description": { "type": "string" }, "duty_minor": { "type": "integer" }, "freight_minor": { "type": "integer" }, "handling_unit": { "type": "string" }, "id": { "description": "Stable line identity for revisioned draft edits.", "type": "string" }, "line_amount_minor": { "description": "Goods after all discounts, using the explicit tax basis. Freight and duty are separate; confirmation freezes the amount excluding all tax.", "type": "integer" }, "note": { "type": "string" }, "package_option": { "allOf": [ { "$ref": "#/components/schemas/packaging.PackageOptionRef" } ], "description": "Required full package reference (sku_code, code, version) for the line. Its sku_code must equal the line sku_code and its code must be the canonical code for units_per_package (EACH for 1, CASE\u003cn\u003e otherwise). Supply does not default or infer a package version." }, "price_basis": { "$ref": "#/components/schemas/purchase_enums.TaxPriceBasis" }, "purchase_order_number": { "type": "string" }, "receipt_allocations": { "items": { "$ref": "#/components/schemas/procurement.SupplierInvoiceReceiptAllocation" }, "maxItems": 250, "type": "array" }, "receipt_id": { "type": "string" }, "sku_code": { "type": "string" }, "tax_rate_basis_points": { "description": "TaxRateBasisPoints lets Supply derive tax for an explicitly taxable line\nwith no supplier figure. 1000 is 10 percent. It is DECLARED rather than\nlooked up: purchase tax is a fact about the transaction, and inventing a\nrate from a product's sale-side category is how the wrong one gets used.", "type": "integer" }, "tax_treatment": { "$ref": "#/components/schemas/purchase_enums.LineTaxTreatment" }, "unit_price_minor": { "type": "integer" }, "units_per_package": { "description": "Required whole number of base units in one package of package_option. base_units must be an exact positive multiple of this size; a line that does not reconcile exactly is rejected with 400.", "minimum": 1, "type": "integer" } }, "required": [ "base_units", "package_option", "sku_code", "units_per_package" ], "type": "object" }, "internal_modules_purchasing.SupplierInvoiceRecord": { "properties": { "calculated_tax_total": { "$ref": "#/components/schemas/money.Money" }, "cancellation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "declared_tax_total": { "$ref": "#/components/schemas/money.Money" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "document": { "$ref": "#/components/schemas/procurement.SupplierInvoiceDocument" }, "duplicate_key": { "type": "string" }, "duty_total": { "$ref": "#/components/schemas/money.Money" }, "freight_total": { "$ref": "#/components/schemas/money.Money" }, "id": { "type": "string" }, "input_tax_claim": { "type": "string" }, "invoice_number": { "type": "string" }, "issue_date": { "type": "string" }, "lines": { "items": { "$ref": "#/components/schemas/procurement.SupplierInvoiceLine" }, "type": "array" }, "purchase_order_numbers": { "items": { "type": "string" }, "type": "array" }, "qualifying_tax_invoice": { "type": "boolean" }, "receipt_ids": { "items": { "type": "string" }, "type": "array" }, "reconciliation": { "$ref": "#/components/schemas/audit.LifecycleAction" }, "revision": { "format": "int64", "type": "integer" }, "status": { "type": "string" }, "subtotal": { "$ref": "#/components/schemas/money.Money" }, "supplier": { "$ref": "#/components/schemas/procurement.SupplierTaxIdentity" }, "tax_source": { "type": "string" }, "total": { "$ref": "#/components/schemas/money.Money" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "invoice_number", "supplier", "issue_date", "currency", "currency_exponent", "lines", "subtotal", "calculated_tax_total", "total", "tax_source", "input_tax_claim", "qualifying_tax_invoice", "document", "duplicate_key", "status", "revision", "created_at", "updated_at" ], "type": "object" }, "internal_modules_purchasing.UpdateInput": { "additionalProperties": false, "allOf": [ { "if": { "required": [ "package_items" ] }, "then": { "required": [ "currency_exponent" ] } } ], "description": "Native package_items freeze exact active/effective SKU/package/version facts server-side; selected_package_cost is per selected package. Counts, amounts, base units and totals must fit JSON safe integers. Client snapshots and totals are forbidden. PATCH omission preserves lines; supplied null/empty package_items refuse. Internal replenishment base-unit accounting is not an HTTP input.", "properties": { "currency_exponent": { "allOf": [ { "$ref": "#/components/schemas/money.CurrencyExponent" }, { "required": [ "currency", "exponent" ], "type": "object" } ], "description": "Explicit matching supported precision. Required for package_items; uses the same pinned ISO 4217 snapshot as GET /v1/purchase-orders/currencies. It does not imply an exchange rate or alter historical valuation." }, "expected_at": { "type": "string" }, "internal_note": { "type": "string" }, "note": { "type": "string" }, "package_items": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.PackageItemInput" }, "maxItems": 100, "minItems": 1, "type": "array" }, "reference": { "type": "string" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" } }, "required": [], "type": "object" }, "internal_modules_purchasing.transitionReq": { "properties": { "status": { "$ref": "#/components/schemas/purchase_enums.PurchaseOrderStatus" } }, "required": [ "status" ], "type": "object" }, "internal_modules_receipts.CreateInput": { "properties": { "depot_code": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/procurement.PurchaseReceiptItem" }, "type": "array", "uniqueItems": false }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "reference": { "type": "string" }, "supplier_code": { "type": "string" } }, "required": [ "depot_code", "items", "purchase_order_number" ], "type": "object" }, "internal_modules_receipts.UpdateDraftInput": { "properties": { "expected_updated_at": { "description": "Exact updated_at from the preceding receipt read. Stale edits return conflict.", "format": "date-time", "type": "string" }, "items": { "description": "Full draft line replacement. Date marks remain optional; supplied past marks require direct receipt into an active, storage-compatible expiry hold.", "items": { "$ref": "#/components/schemas/procurement.PurchaseReceiptItem" }, "type": "array" } }, "required": [ "expected_updated_at", "items" ], "type": "object" }, "internal_modules_replenishment.CampaignPredictionRequest": { "properties": { "as_of": { "type": "string" }, "comparable_events_by_sku": { "additionalProperties": { "items": { "$ref": "#/components/schemas/forecasting.CampaignComparableEvent" }, "type": "array" }, "type": "object" }, "draft": { "$ref": "#/components/schemas/campaign.Campaign" }, "resolved_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_replenishment.CampaignTargetResolutionRequest": { "properties": { "targets": { "$ref": "#/components/schemas/campaign.CampaignTarget" } }, "type": "object" }, "internal_modules_replenishment.CreatePOLine": { "properties": { "cartons": { "type": "integer" }, "note": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "cartons", "sku_code" ], "type": "object" }, "internal_modules_replenishment.CreatePORequest": { "properties": { "currency": { "type": "string" }, "expected_at": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.CreatePOLine" }, "type": "array", "uniqueItems": false }, "occurrence_key": { "maxLength": 200, "type": "string" }, "supplier_code": { "type": "string" } }, "required": [ "items", "occurrence_key", "supplier_code" ], "type": "object" }, "internal_modules_replenishment.CreatePOResponse": { "properties": { "existing": { "type": "boolean" }, "order": { "$ref": "#/components/schemas/procurement.PurchaseOrder" } }, "type": "object" }, "internal_modules_replenishment.ProductSetting": { "properties": { "carton_size": { "type": "integer" }, "cost_price_minor": { "type": "integer" }, "currency": { "type": "string" }, "do_not_buy": { "type": "boolean" }, "do_not_buy_reason": { "type": "string" }, "id": { "type": "string" }, "minimum_order_quantity": { "type": "integer" }, "pinned": { "type": "boolean" }, "product": { "$ref": "#/components/schemas/product.Product" }, "second_delivery_days": { "type": "integer" }, "sku_code": { "type": "string" }, "supplier_code": { "type": "string" }, "target_days": { "type": "integer" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.ProductSettingInput": { "properties": { "carton_size": { "type": "integer" }, "cost_price_minor": { "type": "integer" }, "currency": { "type": "string" }, "do_not_buy": { "type": "boolean" }, "do_not_buy_reason": { "type": "string" }, "minimum_order_quantity": { "type": "integer" }, "pinned": { "type": "boolean" }, "second_delivery_days": { "type": "integer" }, "supplier_code": { "type": "string" }, "target_days": { "type": "integer" } }, "type": "object" }, "internal_modules_replenishment.SalesVelocity30Days": { "properties": { "as_of": { "type": "string" }, "average_daily_units": { "type": "number" }, "net_units": { "type": "integer" }, "timezone": { "type": "string" }, "window_days": { "type": "integer" } }, "type": "object" }, "internal_modules_replenishment.Settings": { "properties": { "default_second_delivery_days": { "type": "integer" }, "default_target_days": { "type": "integer" }, "id": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.SmartBundleItem": { "properties": { "available_base_units": { "minimum": 0, "type": "integer" }, "brand": { "type": "string" }, "case_units_per_package": { "minimum": 0, "type": "integer" }, "cost_price_minor": { "minimum": 0, "type": "integer" }, "minimum_order_case_count": { "minimum": 0, "type": "integer" }, "post_order_days_of_stock": { "type": "number" }, "sales_velocity": { "$ref": "#/components/schemas/internal_modules_replenishment.SalesVelocity30Days" }, "sku_code": { "type": "string" }, "smart_bundle_adjustment_case_count": { "type": "integer" }, "suggested_case_count": { "minimum": 0, "type": "integer" } }, "required": [ "sku_code" ], "type": "object" }, "internal_modules_replenishment.SmartBundleRequest": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SmartBundleItem" }, "minItems": 1, "type": "array", "uniqueItems": false } }, "required": [ "items" ], "type": "object" }, "internal_modules_replenishment.SmartBundleResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SmartBundleItem" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_replenishment.StockListParseRequest": { "properties": { "rows": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierStockRow" }, "type": "array", "uniqueItems": false }, "supplier_code": { "type": "string" }, "text": { "type": "string" } }, "required": [ "supplier_code" ], "type": "object" }, "internal_modules_replenishment.StockListParseResponse": { "properties": { "matched": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierStockMatch" }, "type": "array", "uniqueItems": false }, "new": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierStockRow" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_replenishment.SuggestionItem": { "properties": { "available_base_units": { "type": "integer" }, "brand": { "type": "string" }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "days_of_stock": { "type": "number" }, "occurrence_key": { "type": "string" }, "open_demand_base_units": { "type": "integer" }, "post_order_available_base_units": { "type": "integer" }, "post_order_days_of_stock": { "type": "number" }, "product": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.Snapshot" }, "product_name": { "type": "string" }, "sales_velocity": { "$ref": "#/components/schemas/internal_modules_replenishment.SalesVelocity30Days" }, "sku_code": { "type": "string" }, "suggested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "target_days": { "type": "integer" }, "unit_cost": { "$ref": "#/components/schemas/money.Money" }, "warnings": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_replenishment.SuggestionResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_replenishment.SuggestionItem" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_replenishment.SupplierMapping": { "properties": { "barcode": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "sku_code": { "type": "string" }, "supplier_code": { "type": "string" }, "supplier_sku": { "type": "string" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.SupplierMappingInput": { "properties": { "barcode": { "type": "string" }, "name": { "type": "string" }, "supplier_sku": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.SupplierSetting": { "properties": { "completed": { "type": "boolean" }, "completed_at": { "type": "string" }, "delivery_days": { "type": "integer" }, "id": { "type": "string" }, "import_mode": { "type": "string" }, "pinned": { "type": "boolean" }, "supplier_code": { "type": "string" }, "target_days": { "type": "integer" }, "updated_at": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.SupplierSettingInput": { "properties": { "completed": { "type": "boolean" }, "completed_at": { "type": "string" }, "delivery_days": { "type": "integer" }, "import_mode": { "type": "string" }, "pinned": { "type": "boolean" }, "target_days": { "type": "integer" } }, "type": "object" }, "internal_modules_replenishment.SupplierStockMatch": { "properties": { "do_not_buy": { "type": "boolean" }, "row": { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierStockRow" }, "sku_code": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.SupplierStockRow": { "anyOf": [ { "required": [ "sku_code" ] }, { "required": [ "name" ] } ], "description": "Supply canonical sku_code selects an existing product associated with supplier_code. Without sku_code, name is required and supplier-SKU/barcode/name mappings are used.", "properties": { "barcode": { "type": "string" }, "in_stock": { "type": "boolean" }, "name": { "type": "string" }, "raw": { "type": "string" }, "sku_code": { "type": "string" }, "supplier_sku": { "type": "string" } }, "type": "object" }, "internal_modules_replenishment.campaignPredictionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/forecasting.CampaignPrediction" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_replenishment.campaignTargetResolutionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_replenishment.campaignTargetResolutionResult" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_replenishment.campaignTargetResolutionResult": { "properties": { "resolved_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "unknown_category_targets": { "items": { "$ref": "#/components/schemas/campaign.CampaignCategoryTarget" }, "type": "array", "uniqueItems": false }, "unknown_sku_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_restockalerts.AlertList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_restockalerts.AlertView" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "internal_modules_restockalerts.AlertView": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "market_code": { "type": "string" }, "sku_code": { "type": "string" }, "stock_state": { "enum": [ "in_stock", "out_of_stock", "unknown" ], "type": "string" } }, "required": [ "sku_code", "market_code", "created_at", "expires_at", "stock_state" ], "type": "object" }, "internal_modules_restockalerts.SubscribeInput": { "properties": { "market_code": { "type": "string" } }, "required": [ "market_code" ], "type": "object" }, "internal_modules_restocking.Allocation": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "movement_id": { "type": "string" } }, "required": [ "movement_id", "base_units" ], "type": "object" }, "internal_modules_restocking.Change": { "properties": { "movements": { "items": { "$ref": "#/components/schemas/internal_modules_restocking.Allocation" }, "type": "array" }, "reason": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "status": { "type": "string" } }, "required": [ "revision", "status", "reason" ], "type": "object" }, "internal_modules_restocking.CreateInput": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "reason": { "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "depot_code", "sku_code", "location_code", "base_units", "reason" ], "type": "object" }, "internal_modules_restocking.Request": { "properties": { "actor_id": { "type": "string" }, "base_units": { "format": "int64", "type": "integer" }, "created_at": { "format": "date-time", "type": "string" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "location_code": { "type": "string" }, "movements": { "items": { "$ref": "#/components/schemas/internal_modules_restocking.Allocation" }, "type": "array" }, "reason": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "status": { "enum": [ "pending", "in_progress", "completed", "cancelled" ], "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "depot_code", "sku_code", "location_code", "base_units", "status", "revision", "reason", "actor_id", "created_at", "updated_at" ], "type": "object" }, "internal_modules_reviews.ModerationInput": { "properties": { "action": { "type": "string" }, "moderation_note": { "type": "string" }, "rejection_reason": { "$ref": "#/components/schemas/review_enums.ReviewRejectionReason" } }, "type": "object" }, "internal_modules_reviews.PutInput": { "properties": { "body": { "type": "string" }, "locale": { "type": "string" }, "score": { "type": "integer" } }, "type": "object" }, "internal_modules_shipments.CarrierBookingInput": { "properties": { "delivery_company_code": { "description": "Defaults to the shipments' carrier, then the order's delivery company. A different company requires override.", "type": "string" }, "edits": { "$ref": "#/components/schemas/courier.CarrierBookingEdits" }, "override": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierOverride" }, "production_date": { "description": "Depot intake date. Precedence is edits.intake_date, then this field, then the order's production_date. Required only when the delivery company's booking request carries the intake date (sent_values.intake_date or a required production_date input); then missing all three is 400. Ignored by companies that never send it.", "format": "date", "type": "string" } }, "type": "object" }, "internal_modules_shipments.CarrierBookingResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierBookingResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_shipments.CarrierBookingResult": { "properties": { "attempt": { "$ref": "#/components/schemas/courier.CarrierBookingAttempt" }, "shipments": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundShipment" }, "type": "array" } }, "required": [ "attempt", "shipments" ], "type": "object" }, "internal_modules_shipments.CarrierOverride": { "properties": { "reason": { "maxLength": 500, "minLength": 1, "type": "string" } }, "required": [ "reason" ], "type": "object" }, "internal_modules_shipments.CarrierPushSummary": { "description": "Counts orders, not shipments, for one delivery company and day. Pending orders still have a packed shipment of the company whose latest booking is not rejected or unreachable; failed orders still have one whose latest booking was rejected or unreachable; pushed orders have the company's shipments dispatched or delivered with the latest booking sent on the day and no shipment of the order still packed. Undated counts open orders whose date on the basis is unknown.", "properties": { "basis": { "enum": [ "intake_date", "delivery_date" ], "type": "string" }, "carrier": { "description": "Delivery company code (lower case)", "type": "string" }, "date": { "format": "date", "type": "string" }, "failed": { "minimum": 0, "type": "integer" }, "pending": { "minimum": 0, "type": "integer" }, "pushed": { "minimum": 0, "type": "integer" }, "undated": { "minimum": 0, "type": "integer" } }, "required": [ "carrier", "date", "basis", "pending", "pushed", "failed", "undated" ], "type": "object" }, "internal_modules_shipments.CarrierPushSummaryResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierPushSummary" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_shipments.CreateInput": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "carrier": { "description": "Defaults to the order's delivery company. A different carrier requires override, recorded as a carrier_override history entry.", "type": "string" }, "containers": { "items": { "$ref": "#/components/schemas/fulfilment.OutboundContainerPlan" }, "minItems": 1, "type": "array", "uniqueItems": false }, "customer_name": { "type": "string" }, "depot_code": { "type": "string" }, "note": { "type": "string" }, "order_number": { "type": "string" }, "override": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierOverride" } }, "required": [ "containers", "depot_code", "order_number" ], "type": "object" }, "internal_modules_shipments.ShipmentEvidence": { "properties": { "carrier": { "type": "string" }, "container_ids": { "items": { "type": "string" }, "type": "array" }, "delivered_at": { "format": "date-time", "type": "string" }, "dispatched_at": { "format": "date-time", "type": "string" }, "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/warehouse_enums.OutboundShipmentStatus" }, "tracking_number": { "type": "string" } }, "required": [ "id", "status", "container_ids" ], "type": "object" }, "internal_modules_shipments.ShipmentEvidenceSummary": { "properties": { "complete_coverage": { "type": "boolean" }, "completed": { "type": "boolean" }, "completed_at": { "format": "date-time", "type": "string" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "order_number": { "type": "string" }, "packing_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "shipments": { "items": { "$ref": "#/components/schemas/internal_modules_shipments.ShipmentEvidence" }, "type": "array" } }, "required": [ "order_number", "fulfillment_generation", "packing_revision", "complete_coverage", "completed", "shipments" ], "type": "object" }, "internal_modules_shipments.dispatchReq": { "properties": { "carrier": { "type": "string" }, "tracking_number": { "type": "string" } }, "required": [ "tracking_number" ], "type": "object" }, "internal_modules_stock.AdjustInput": { "properties": { "base_units_delta": { "type": "integer" }, "bucket_id": { "type": "string" }, "cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "expected_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "net_goods_cost": { "$ref": "#/components/schemas/internal_modules_netgoods.CostEvidence" }, "note": { "type": "string" }, "reason_code": { "type": "string" } }, "required": [ "base_units_delta", "bucket_id", "cause", "composition", "expected_revision", "idempotency_key", "reason_code" ], "type": "object" }, "internal_modules_stock.ApproveReducedSaleInput": { "properties": { "expected_revision": { "description": "ExpectedRevision is the assessment revision the approver read, so two\noperators cannot both believe they set the band.", "type": "integer" }, "reason_code": { "type": "string" }, "tier": { "$ref": "#/components/schemas/warehouse_enums.DamageSaleTier" } }, "required": [ "expected_revision", "tier" ], "type": "object" }, "internal_modules_stock.ConversionRecord": { "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "destination_bucket_id": { "type": "string" }, "destination_package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "id": { "type": "string" }, "idempotency_key": { "type": "string" }, "lot_id": { "type": "string" }, "movement_id": { "type": "string" }, "request_hash": { "type": "string" }, "sku_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "source_package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "type": "object" }, "internal_modules_stock.ConvertInput": { "properties": { "cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "destination_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "destination_handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "destination_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "expected_destination_revision": { "type": "integer" }, "expected_source_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "source_bucket_id": { "type": "string" }, "source_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "required": [ "cause", "destination_composition", "destination_handling_unit", "destination_package_option", "expected_source_revision", "idempotency_key", "source_bucket_id", "source_composition" ], "type": "object" }, "internal_modules_stock.ConvertResult": { "properties": { "conversion": { "$ref": "#/components/schemas/internal_modules_stock.ConversionRecord" }, "movement": { "$ref": "#/components/schemas/inventory.StockMovement" }, "replayed": { "type": "boolean" } }, "type": "object" }, "internal_modules_stock.LotDateMarkInput": { "additionalProperties": false, "description": "The date_mark key is required. An object sets the lot's date mark; an\nexplicit null clears it. A body without the key is rejected with 400\nVALIDATION_ERROR rather than read as a clear, so a client that forgets the\nfield cannot erase a date mark. Unknown fields are rejected.", "properties": { "date_mark": { "anyOf": [ { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, { "type": "null" } ], "description": "New date mark for the lot, or null to clear it." } }, "required": [ "date_mark" ], "type": "object" }, "internal_modules_stock.LotDateMarkResponse": { "properties": { "data": { "$ref": "#/components/schemas/warehouse.InventoryLot" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.LotReassignment": { "properties": { "base_units": { "type": "integer" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "destination_bucket_created": { "type": "boolean" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "from_balance_after_base_units": { "type": "integer" }, "from_balance_before_base_units": { "type": "integer" }, "from_bucket_id": { "type": "string" }, "from_lot_id": { "type": "string" }, "from_revision": { "description": "Source bucket revision after the reassignment.", "type": "integer" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "id": { "description": "Reassignment id; also the movement's cause.id.", "type": "string" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "movement_id": { "type": "string" }, "note": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "performed_by": { "type": "string" }, "reason_code": { "type": "string" }, "requested_cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "sku_code": { "type": "string" }, "to_balance_after_base_units": { "type": "integer" }, "to_balance_before_base_units": { "type": "integer" }, "to_bucket_id": { "type": "string" }, "to_lot_id": { "type": "string" }, "to_revision": { "description": "Destination bucket revision after the reassignment.", "type": "integer" } }, "required": [ "id", "sku_code", "location", "from_lot_id", "to_lot_id", "from_bucket_id", "to_bucket_id", "destination_bucket_created", "package_option", "handling_unit", "condition", "disposition", "base_units", "composition", "from_balance_before_base_units", "from_balance_after_base_units", "to_balance_before_base_units", "to_balance_after_base_units", "from_revision", "to_revision", "movement_id", "reason_code", "performed_by", "occurred_at" ], "type": "object" }, "internal_modules_stock.LotReassignmentInput": { "description": "Moves base units booked against from_lot_id to to_lot_id at one\nlocation. The source bucket is the exact grain (location, sku_code,\nfrom_lot_id, package_option, handling_unit, condition, disposition); the\ndestination is the same grain with to_lot_id and is created when it does\nnot exist yet.", "properties": { "cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "expected_from_revision": { "description": "Revision of the source bucket the caller observed.", "minimum": 1, "type": "integer" }, "expected_to_revision": { "description": "Revision of the destination bucket the caller observed; omit when the destination bucket does not exist yet.", "minimum": 0, "type": "integer" }, "from_lot_id": { "description": "The lot the books currently show.", "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "idempotency_key": { "maxLength": 128, "type": "string" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "note": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reason_code": { "description": "Defaults to LOT_CORRECTION.", "type": "string" }, "sku_code": { "type": "string" }, "to_lot_id": { "description": "The lot physically present. Must belong to the same SKU and differ from from_lot_id.", "type": "string" } }, "required": [ "sku_code", "location", "from_lot_id", "to_lot_id", "package_option", "handling_unit", "condition", "disposition", "composition", "expected_from_revision", "idempotency_key" ], "type": "object" }, "internal_modules_stock.LotReassignmentResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_stock.LotReassignmentResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.LotReassignmentResult": { "properties": { "movement": { "$ref": "#/components/schemas/inventory.StockMovement" }, "reassignment": { "$ref": "#/components/schemas/internal_modules_stock.LotReassignment" }, "replayed": { "type": "boolean" } }, "required": [ "reassignment", "movement" ], "type": "object" }, "internal_modules_stock.OrderAllocationEvidence": { "properties": { "allocation": { "$ref": "#/components/schemas/inventory.StockReservationAllocation" }, "integrity_valid": { "type": "boolean" }, "order_item_id": { "type": "string" }, "reservation": { "$ref": "#/components/schemas/inventory.StockReservation" }, "source_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "staging": { "$ref": "#/components/schemas/inventory.StockStagingRecord" }, "staging_verified": { "type": "boolean" }, "substitution_id": { "type": "string" }, "substitutions": { "items": { "$ref": "#/components/schemas/fulfilment.PackageSubstitutionSnapshot" }, "type": "array" } }, "required": [ "order_item_id", "reservation", "allocation", "source_location", "integrity_valid", "staging_verified" ], "type": "object" }, "internal_modules_stock.POSAddBackInput": { "properties": { "idempotency_key": { "description": "Same key and request replays the original result with replayed true; same key with a different request answers 409 CONFLICT.", "maxLength": 128, "minLength": 1, "type": "string" }, "location_code": { "description": "Active standard stock location of the store's depot.", "maxLength": 128, "minLength": 1, "type": "string" }, "lot_id": { "description": "A lot from lot_candidates of GET /stock/pos-item-locations to use at a location holding no lot. A lot_id that is not one of the store's candidates is refused with NO_LOT_AT_LOCATION. Mutually exclusive with new_lot.", "maxLength": 128, "minLength": 1, "type": "string" }, "market_code": { "description": "Market the register sells in; the store must serve it.", "maxLength": 128, "minLength": 1, "type": "string" }, "new_lot": { "$ref": "#/components/schemas/internal_modules_stock.POSAddBackNewLot" }, "package_code": { "description": "Code of one of the product's effective package options. Omitted, the product's smallest package (an each before an equally sized package) is used.", "maxLength": 128, "minLength": 1, "type": "string" }, "product_code": { "description": "Active product (SKU) code.", "maxLength": 128, "minLength": 1, "type": "string" }, "quantity": { "description": "Number of packages of package_code counted back. Base units = quantity x the package's units_per_package.", "minimum": 1, "type": "integer" }, "store_code": { "description": "Physical depot code of the register.", "maxLength": 128, "minLength": 1, "type": "string" }, "unit_cost": { "$ref": "#/components/schemas/internal_modules_stock.POSAddBackUnitCost" } }, "required": [ "store_code", "market_code", "product_code", "location_code", "quantity", "idempotency_key" ], "type": "object" }, "internal_modules_stock.POSAddBackNewLot": { "description": "Creates the lot the add-back raises when the location holds none, like an opening receipt does. Mutually exclusive with lot_id.", "properties": { "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" } }, "type": "object" }, "internal_modules_stock.POSAddBackResult": { "properties": { "add_back_id": { "description": "Stable id of the add-back, derived from the idempotency key; the cause id of its movements.", "type": "string" }, "base_units": { "description": "Base units added back.", "type": "integer" }, "cost_source": { "description": "last_acquisition_cost when the product's current acquisition cost in the market's currency valued the add-back; request when unit_cost did.", "enum": [ "last_acquisition_cost", "request" ], "type": "string" }, "location_code": { "type": "string" }, "locations": { "description": "On-hand per location of the product at the store after the add-back, as GET /stock/pos-item-locations reports it.", "items": { "$ref": "#/components/schemas/internal_modules_stock.POSItemLocation" }, "type": "array" }, "lot_created": { "description": "The lot was created from new_lot.", "type": "boolean" }, "lot_id": { "description": "Lot raised by the remainder. Omitted when the whole add-back settled shortfall.", "type": "string" }, "market_code": { "type": "string" }, "movement_ids": { "description": "Stock movements written, shortfall settlement receipts first, then lot gains.", "items": { "type": "string" }, "type": "array" }, "occurred_at": { "format": "date-time", "type": "string" }, "on_hand_total": { "description": "New on-hand total of the product at the store, in base units.", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "performed_by": { "type": "string" }, "product_code": { "type": "string" }, "quantity": { "type": "integer" }, "replayed": { "type": "boolean" }, "shortfall_settled_base_units": { "description": "Base units that settled open POS shortfall at the depot's POS deficit location before any lot stock was raised.", "type": "integer" }, "store_code": { "type": "string" } }, "required": [ "add_back_id", "store_code", "market_code", "product_code", "location_code", "package_option", "quantity", "base_units", "shortfall_settled_base_units", "lot_created", "cost_source", "locations", "on_hand_total", "movement_ids", "performed_by", "occurred_at" ], "type": "object" }, "internal_modules_stock.POSAddBackUnitCost": { "description": "Used, and recorded as the product's current acquisition cost (source_type pos_add_back, source_id the add_back_id), only when the product has no current acquisition cost in the market's currency. Ignored otherwise.", "properties": { "amount_minor": { "description": "Tax-exclusive cost of one base unit in minor units of currency, the same per-base-unit convention as the acquisition cost.", "minimum": 1, "type": "integer" }, "currency": { "description": "Must be the market's currency (Pricing's market default currency); any other currency answers 400.", "maxLength": 3, "minLength": 3, "type": "string" } }, "required": [ "currency", "amount_minor" ], "type": "object" }, "internal_modules_stock.POSConvertInput": { "properties": { "destination_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "destination_handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "destination_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "expected_destination_revision": { "type": "integer" }, "expected_source_revision": { "minimum": 1, "type": "integer" }, "idempotency_key": { "description": "Same key and request replays the original conversion; same key with a different request answers 409 CONFLICT.", "maxLength": 128, "minLength": 1, "type": "string" }, "market_code": { "description": "Market the register sells in; the store must serve it.", "maxLength": 128, "minLength": 1, "type": "string" }, "source_bucket_id": { "description": "Bucket counted at the till. It must belong to the store's depot and hold an existing lot.", "type": "string" }, "source_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "store_code": { "description": "Physical depot code of the register.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "store_code", "market_code", "source_bucket_id", "expected_source_revision", "destination_package_option", "destination_handling_unit", "source_composition", "destination_composition", "idempotency_key" ], "type": "object" }, "internal_modules_stock.POSCountCorrectionInput": { "properties": { "counted_quantity": { "description": "Packages of package_code staff counted on the shelf at location_code. Base units = counted_quantity x the package's units_per_package, so a CASE package counts whole cases only. Must be below the location's current stock of that package.", "minimum": 0, "type": "integer" }, "idempotency_key": { "description": "Same key, till (token subject), store and request replays the original result with replayed true; the same key with a different request, store or till answers 409 CONFLICT.", "maxLength": 128, "minLength": 1, "type": "string" }, "location_code": { "description": "Active standard stock location of the store's depot that was counted.", "maxLength": 128, "minLength": 1, "type": "string" }, "market_code": { "description": "Market the register sells in; the store must serve it.", "maxLength": 128, "minLength": 1, "type": "string" }, "note": { "description": "Optional free text recorded on every loss movement; surrounding whitespace is trimmed and at most 1000 bytes are accepted.", "maxLength": 1000, "type": "string" }, "package_code": { "description": "Code of one of the product's effective package options that was counted. Omitted, the product's smallest package (an each before an equally sized package) is used, as for add-backs.", "maxLength": 128, "minLength": 1, "type": "string" }, "product_code": { "description": "Active product (SKU) code.", "maxLength": 128, "minLength": 1, "type": "string" }, "reason_code": { "description": "Why the stock is lower than the books; recorded on every loss movement.", "enum": [ "COUNT_CORRECTION", "DAMAGED", "MISSING", "EXPIRED", "OTHER" ], "type": "string" }, "store_code": { "description": "Physical depot code of the register.", "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "store_code", "market_code", "product_code", "location_code", "counted_quantity", "reason_code", "idempotency_key" ], "type": "object" }, "internal_modules_stock.POSCountCorrectionResult": { "properties": { "before_base_units": { "description": "On-hand base units of the package at the location before the correction (good, standard-sellable, non-negative buckets; POS shortfall excluded).", "type": "integer" }, "correction_id": { "description": "Stable id of the correction, derived from the idempotency key; the cause id (cause type pos_count_correction) of its movements.", "type": "string" }, "counted_base_units": { "description": "On-hand base units of the package at the location after the correction.", "type": "integer" }, "counted_quantity": { "description": "Packages of package_code counted.", "type": "integer" }, "location_code": { "type": "string" }, "market_code": { "type": "string" }, "movement_ids": { "description": "Loss ADJUSTMENT movements written, one per bucket, earliest date mark first.", "items": { "type": "string" }, "type": "array" }, "note": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "package_code": { "description": "Package the count was made in.", "type": "string" }, "performed_by": { "description": "Token subject of the till operator.", "type": "string" }, "reason_code": { "type": "string" }, "removed_base_units": { "description": "Base units written off, before_base_units minus counted_base_units.", "type": "integer" }, "replayed": { "description": "True when the idempotency key replayed an earlier correction.", "type": "boolean" }, "sku_code": { "type": "string" }, "store_code": { "type": "string" } }, "required": [ "correction_id", "store_code", "market_code", "sku_code", "location_code", "package_code", "counted_quantity", "before_base_units", "counted_base_units", "removed_base_units", "movement_ids", "reason_code", "performed_by", "occurred_at", "replayed" ], "type": "object" }, "internal_modules_stock.POSItemLocation": { "properties": { "has_lot": { "description": "The location has an untracked lot bucket of good, standard-sellable stock (not itself in deficit) that an add-back can raise without naming a lot.", "type": "boolean" }, "location_code": { "type": "string" }, "on_hand": { "description": "On-hand base units at the location.", "type": "integer" } }, "required": [ "location_code", "on_hand", "has_lot" ], "type": "object" }, "internal_modules_stock.POSItemLocations": { "properties": { "locations": { "items": { "$ref": "#/components/schemas/internal_modules_stock.POSItemLocation" }, "type": "array" }, "lot_candidates": { "description": "Lots of the product holding positive on-hand stock anywhere in the store's depot, newest first. A till offers one when the chosen location has no lot (has_lot false).", "items": { "$ref": "#/components/schemas/internal_modules_stock.POSLotCandidate" }, "type": "array" }, "market_code": { "type": "string" }, "open_shortfall_base_units": { "description": "Base units sold below zero and still open at the POS deficit location.", "type": "integer" }, "pos_deficit_location_code": { "description": "The depot's POS deficit location; omitted when none is configured.", "type": "string" }, "product": { "$ref": "#/components/schemas/internal_modules_stock.POSStockProduct" }, "store_code": { "type": "string" } }, "required": [ "store_code", "market_code", "product", "locations", "lot_candidates", "open_shortfall_base_units" ], "type": "object" }, "internal_modules_stock.POSLotCandidate": { "properties": { "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "lot_id": { "type": "string" }, "received_at": { "description": "When the lot was created; candidates are ordered newest first.", "format": "date-time", "type": "string" } }, "required": [ "lot_id", "received_at" ], "type": "object" }, "internal_modules_stock.POSStockBrand": { "properties": { "code": { "description": "Brand code.", "type": "string" }, "name": { "description": "Localized brand names; empty when the brand master has none.", "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" } }, "required": [ "code", "name" ], "type": "object" }, "internal_modules_stock.POSStockPackage": { "properties": { "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "units_per_package": { "type": "integer" } }, "required": [ "package_option", "handling_unit", "units_per_package" ], "type": "object" }, "internal_modules_stock.POSStockProduct": { "properties": { "brand": { "$ref": "#/components/schemas/internal_modules_stock.POSStockBrand" }, "image_media_path": { "description": "Public media path of the cover image.", "type": "string" }, "name": { "type": "string" }, "package": { "$ref": "#/components/schemas/internal_modules_stock.POSStockPackage" }, "product_code": { "description": "Product (SKU) code.", "type": "string" }, "units_per_case": { "description": "Base units in the product's effective CASE package. Omitted when it has none, or more than one case size.", "type": "integer" } }, "required": [ "product_code", "name", "package" ], "type": "object" }, "internal_modules_stock.PackingCarriedHoldEvidence": { "description": "Original held stock and receipt retained across a reopen; a later refund is not assigned to a particular allocation.", "properties": { "allocation_id": { "type": "string" }, "conservative_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "hold_reconciled_at": { "format": "date-time", "type": "string" }, "hold_settlement_key": { "type": "string" }, "hold_settlement_receipt_id": { "type": "string" }, "missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_item_id": { "type": "string" }, "reconciliation_receipt_id": { "type": "string" }, "reservation_id": { "type": "string" }, "source_bucket_id": { "type": "string" } }, "required": [ "order_item_id", "reservation_id", "allocation_id", "source_bucket_id", "missing_composition", "hold_settlement_key", "hold_settlement_receipt_id" ], "type": "object" }, "internal_modules_stock.PackingConservativeHoldEvidence": { "description": "A physical hold on original tracked stock; it does not identify which unit was missing or assert a sale source.", "properties": { "allocation_id": { "type": "string" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "hold_reconciled_at": { "format": "date-time", "type": "string" }, "hold_settlement_receipt_id": { "type": "string" }, "order_item_id": { "type": "string" }, "reconciliation_receipt_id": { "type": "string" }, "reservation_id": { "type": "string" }, "source_bucket_id": { "type": "string" } }, "required": [ "order_item_id", "reservation_id", "allocation_id", "source_bucket_id", "composition", "hold_settlement_receipt_id" ], "type": "object" }, "internal_modules_stock.PackingIssuedSource": { "properties": { "allocation_id": { "type": "string" }, "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "lot_id": { "type": "string" }, "movement_id": { "type": "string" }, "order_item_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "remaining_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reservation_id": { "type": "string" }, "reservation_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "sku_code": { "type": "string" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "reservation_id", "reservation_revision", "bucket_revision", "movement_id", "order_item_id", "sku_code", "allocation_id", "bucket_id", "location", "package_option", "remaining_composition" ], "type": "object" }, "internal_modules_stock.PackingReturnSelection": { "additionalProperties": false, "properties": { "movement_id": { "type": "string" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "movement_id", "returned_composition" ], "type": "object" }, "internal_modules_stock.PackingSettlementEvidence": { "properties": { "carried_holds": { "description": "Previously verified holds retained independently across a packing reopen.", "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingCarriedHoldEvidence" }, "type": "array" }, "conservative_holds": { "description": "Additional verified original stock retained separately from logical missing quantities.", "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingConservativeHoldEvidence" }, "type": "array" }, "direct": { "type": "boolean" }, "fulfillment_generation": { "format": "int64", "minimum": 1, "type": "integer" }, "movement_ids": { "items": { "type": "string" }, "type": "array" }, "order_number": { "type": "string" }, "reservation_ids": { "items": { "type": "string" }, "type": "array" }, "settlement_key": { "type": "string" }, "settlement_receipt_id": { "description": "Owner-verified existing settlement receipt identity.", "type": "string" }, "shortage_events": { "description": "Verified shortage event balances before refund attribution.", "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingShortageEventSummary" }, "type": "array" }, "tracked_hold_progress": { "description": "Receipt-verified progress of each tracked allocation's original physical hold. Original quantity equals counted loss plus released present quantity plus remaining held quantity.", "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingTrackedHoldProgress" }, "type": "array" } }, "required": [ "order_number", "fulfillment_generation", "settlement_key", "settlement_receipt_id", "reservation_ids", "movement_ids", "tracked_hold_progress" ], "type": "object" }, "internal_modules_stock.PackingShortageEventOriginHold": { "properties": { "allocation_id": { "type": "string" }, "hold_settlement_key": { "type": "string" }, "hold_settlement_receipt_id": { "type": "string" }, "missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reservation_id": { "type": "string" }, "source_bucket_id": { "type": "string" } }, "required": [ "reservation_id", "allocation_id", "source_bucket_id", "missing_composition", "hold_settlement_key", "hold_settlement_receipt_id" ], "type": "object" }, "internal_modules_stock.PackingShortageEventSummary": { "properties": { "discrepancy_id": { "type": "string" }, "order_item_id": { "type": "string" }, "origin_holds": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PackingShortageEventOriginHold" }, "type": "array" }, "origin_settlement_key": { "type": "string" }, "origin_settlement_receipt_id": { "type": "string" }, "original_missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "original_unreserved_missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "remaining_before_refund_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" } }, "required": [ "discrepancy_id", "order_item_id", "sku_code", "origin_settlement_key", "origin_settlement_receipt_id", "original_missing_composition", "original_unreserved_missing_composition", "remaining_before_refund_composition", "origin_holds" ], "type": "object" }, "internal_modules_stock.PackingSourceSelection": { "additionalProperties": false, "properties": { "allocation_id": { "type": "string" }, "bucket_id": { "type": "string" }, "expected_bucket_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "order_item_id": { "type": "string" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "stock_unit_ids": { "description": "Physical units identified by staff at the selected source.", "items": { "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [ "order_item_id", "allocation_id", "bucket_id", "expected_bucket_revision", "packed_composition" ], "type": "object" }, "internal_modules_stock.PackingTrackedHoldProgress": { "properties": { "allocation_id": { "type": "string" }, "count_receipt_ids": { "items": { "type": "string" }, "type": "array" }, "counted_loss_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "hold_settlement_receipt_id": { "type": "string" }, "order_item_id": { "type": "string" }, "original_held_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reconciled_at": { "format": "date-time", "type": "string" }, "reconciliation_receipt_id": { "type": "string" }, "released_present_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "remaining_held_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reservation_id": { "type": "string" }, "source_bucket_id": { "type": "string" } }, "required": [ "order_item_id", "reservation_id", "allocation_id", "source_bucket_id", "hold_settlement_receipt_id", "original_held_composition", "counted_loss_composition", "released_present_composition", "remaining_held_composition", "count_receipt_ids" ], "type": "object" }, "internal_modules_stock.PickingShortageAllocationEvidence": { "properties": { "allocation_id": { "type": "string" }, "held_missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "hold_reconciled_at": { "format": "date-time", "type": "string" }, "hold_settlement_receipt_id": { "type": "string" }, "reconciliation_receipt_id": { "type": "string" }, "reservation_id": { "type": "string" }, "source_bucket_id": { "type": "string" } }, "required": [ "reservation_id", "allocation_id", "source_bucket_id", "held_missing_composition", "hold_settlement_receipt_id" ], "type": "object" }, "internal_modules_stock.PickingShortageEvidence": { "properties": { "allocations": { "items": { "$ref": "#/components/schemas/internal_modules_stock.PickingShortageAllocationEvidence" }, "type": "array" }, "carried_shortage_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_item_id": { "type": "string" }, "packed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "type": "string" }, "unreserved_missing_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "required": [ "order_item_id", "sku_code", "requested_composition", "packed_composition", "missing_composition", "unreserved_missing_composition", "allocations" ], "type": "object" }, "internal_modules_stock.QualityInput": { "properties": { "assessed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "evidence_media_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "expected_source_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "note": { "type": "string" }, "reason_code": { "type": "string" }, "result_condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "result_disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "source_bucket_id": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "required": [ "assessed_composition", "destination_location", "expected_source_revision", "idempotency_key", "reason_code", "result_condition", "result_disposition", "source_bucket_id" ], "type": "object" }, "internal_modules_stock.QualityResult": { "properties": { "assessment": { "$ref": "#/components/schemas/warehouse.QualityAssessment" }, "movement": { "$ref": "#/components/schemas/inventory.StockMovement" }, "replayed": { "type": "boolean" } }, "type": "object" }, "internal_modules_stock.ReturnInput": { "properties": { "damaged": { "type": "boolean" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "idempotency_key": { "type": "string" }, "order_number": { "type": "string" }, "original_issue_movement_id": { "description": "Original same-SKU, same-order sale issue. Required by automatic valuation to restore original cost.", "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "return_line_id": { "type": "string" }, "returned_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sealed": { "type": "boolean" }, "sku_code": { "type": "string" }, "supplier_lot_code": { "type": "string" } }, "required": [ "destination_location", "handling_unit", "idempotency_key", "order_number", "package_option", "return_line_id", "returned_composition", "sku_code", "original_issue_movement_id" ], "type": "object" }, "internal_modules_stock.StageInput": { "properties": { "allocation_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "expected_reservation_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "reservation_id": { "type": "string" } }, "required": [ "allocation_id", "destination_location", "expected_reservation_revision", "idempotency_key", "reservation_id" ], "type": "object" }, "internal_modules_stock.StageResult": { "properties": { "movement": { "$ref": "#/components/schemas/inventory.StockMovement" }, "record": { "$ref": "#/components/schemas/inventory.StockStagingRecord" }, "replayed": { "type": "boolean" } }, "type": "object" }, "internal_modules_stock.StockUnit": { "properties": { "base_units": { "type": "integer" }, "bucket_id": { "type": "string" }, "clearance_label_code": { "type": "string" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "evidence_media_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "unit_label_code": { "type": "string" } }, "type": "object" }, "internal_modules_stock.TransferInput": { "properties": { "cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "expected_destination_revision": { "type": "integer" }, "expected_source_revision": { "type": "integer" }, "idempotency_key": { "type": "string" }, "note": { "type": "string" }, "reason_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "required": [ "cause", "composition", "destination_location", "expected_source_revision", "idempotency_key", "source_bucket_id" ], "type": "object" }, "internal_modules_stock.posAddBackAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_stock.POSAddBackResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.posConvertAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_stock.ConvertResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.posCountCorrectionAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_stock.POSCountCorrectionResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.posItemLocationsAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_stock.POSItemLocations" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "internal_modules_stock.reservationAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationResult" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_stock.stockUnitListAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_stock.StockUnit" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_storefrontcapabilities.Capabilities": { "properties": { "brands": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" }, "product_origin": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" }, "product_story": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" }, "restock_alerts": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" }, "reviews": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" }, "wishes": { "$ref": "#/components/schemas/internal_modules_storefrontcapabilities.Capability" } }, "type": "object" }, "internal_modules_storefrontcapabilities.Capability": { "properties": { "available": { "type": "boolean" }, "reason": { "type": "string" } }, "type": "object" }, "internal_modules_suppliers.CreateInput": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "available_market_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "available_products": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailableProduct" }, "type": "array", "uniqueItems": false }, "available_promotions": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailablePromotion" }, "type": "array", "uniqueItems": false }, "code": { "type": "string" }, "contact_person": { "type": "string" }, "email": { "type": "string" }, "geographic_location": { "$ref": "#/components/schemas/geography.Address" }, "name": { "type": "string" }, "note": { "type": "string" }, "payment_terms": { "type": "string" }, "phone": { "type": "string" }, "tax_registration_id": { "type": "string" } }, "required": [ "code", "name" ], "type": "object" }, "internal_modules_suppliers.UpdateInput": { "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "available_market_codes": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "available_products": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailableProduct" }, "type": "array", "uniqueItems": false }, "available_promotions": { "items": { "$ref": "#/components/schemas/classification.SupplierAvailablePromotion" }, "type": "array", "uniqueItems": false }, "contact_person": { "type": "string" }, "email": { "type": "string" }, "geographic_location": { "$ref": "#/components/schemas/geography.Address" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "note": { "type": "string" }, "payment_terms": { "type": "string" }, "phone": { "type": "string" }, "tax_registration_id": { "type": "string" } }, "type": "object" }, "internal_modules_suppliers.supplierAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/classification.Supplier" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_suppliers.supplierListAPIResponse": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/classification.Supplier" }, "type": "array", "uniqueItems": false }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "type": "object" }, "success": { "type": "boolean" } }, "type": "object" }, "internal_modules_wishes.CreateBallotInput": { "properties": { "candidate_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "closes_at": { "type": "string" }, "opens_at": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.CreateCandidateInput": { "properties": { "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "image_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_wishes.CreateProposalInput": { "properties": { "description": { "type": "string" }, "product_name": { "type": "string" }, "reference_url": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.LinkProductInput": { "properties": { "sku_code": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.PatchBallotInput": { "properties": { "candidate_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "closes_at": { "type": "string" }, "opens_at": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.PatchCandidateInput": { "properties": { "description": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "image_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_wishes.RefreshBallotInput": { "properties": { "closes_at": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.RejectProposalInput": { "properties": { "reason": { "type": "string" } }, "type": "object" }, "internal_modules_wishes.ReplaceVotesInput": { "properties": { "candidate_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "internal_modules_wishes.ScheduleBallotInput": { "properties": { "candidate_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "closes_at": { "type": "string" }, "opens_at": { "type": "string" } }, "type": "object" }, "internal_modules_wmsdraft.CreateInput": { "properties": { "depot_code": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/warehouse.WMSDraftItem" }, "type": "array", "uniqueItems": false }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "purchase_receipt_id": { "type": "string" }, "type": { "$ref": "#/components/schemas/warehouse_enums.WMSDraftType" } }, "required": [ "operator", "type" ], "type": "object" }, "internal_modules_wmsdraft.UpdateInput": { "properties": { "items": { "items": { "$ref": "#/components/schemas/warehouse.WMSDraftItem" }, "type": "array", "uniqueItems": false }, "note": { "type": "string" } }, "type": "object" }, "internal_platform_historyquery.PackingPage": { "properties": { "expires_at": { "format": "date-time", "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/internal_modules_packing.HistoryRow" }, "type": "array" }, "limit": { "format": "int64", "type": "integer" }, "next_offset": { "format": "int64", "type": "integer" }, "observed_at": { "format": "date-time", "type": "string" }, "offset": { "format": "int64", "type": "integer" }, "snapshot_id": { "type": "string" }, "total": { "format": "int64", "type": "integer" } }, "required": [ "snapshot_id", "observed_at", "expires_at", "total", "offset", "limit", "items" ], "type": "object" }, "internal_procurementcurrency.Catalogue": { "additionalProperties": false, "properties": { "currencies": { "items": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "type": "array" }, "dataset_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "published_at": { "format": "date", "type": "string" }, "source": { "type": "string" }, "source_sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" }, "source_url": { "format": "uri", "type": "string" } }, "required": [ "source", "source_url", "published_at", "source_sha256", "dataset_sha256", "currencies" ], "type": "object" }, "inventory.ChannelProductStockSnapshot": { "properties": { "channel": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "quantities": { "$ref": "#/components/schemas/inventory.ProductStockQuantitySnapshot" } }, "type": "object" }, "inventory.DepotProductStockSnapshot": { "properties": { "depot_code": { "type": "string" }, "quantities": { "$ref": "#/components/schemas/inventory.ProductStockQuantitySnapshot" } }, "type": "object" }, "inventory.InventoryCauseRef": { "properties": { "id": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "inventory.KnownLotPhysicalEvidence": { "properties": { "lot_id": { "type": "string" }, "stock_unit_ids": { "items": { "type": "string" }, "type": "array" } }, "required": [ "lot_id" ], "type": "object" }, "inventory.LocationProductStockSnapshot": { "properties": { "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "quantities": { "$ref": "#/components/schemas/inventory.ProductStockQuantitySnapshot" } }, "type": "object" }, "inventory.PackageOptionProductStockSnapshot": { "properties": { "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "quantities": { "$ref": "#/components/schemas/inventory.ProductStockQuantitySnapshot" } }, "type": "object" }, "inventory.ProductStockQuantitySnapshot": { "properties": { "available_base_units": { "type": "integer" }, "on_hand_base_units": { "type": "integer" }, "quality_hold_base_units": { "type": "integer" }, "reduced_base_units": { "type": "integer" }, "reserved_base_units": { "type": "integer" }, "sellable_base_units": { "type": "integer" }, "staged_base_units": { "type": "integer" } }, "type": "object" }, "inventory.ProductStockSummary": { "properties": { "all_depots": { "$ref": "#/components/schemas/inventory.ProductStockQuantitySnapshot" }, "as_of": { "type": "string" }, "channels": { "items": { "$ref": "#/components/schemas/inventory.ChannelProductStockSnapshot" }, "type": "array", "uniqueItems": false }, "depots": { "items": { "$ref": "#/components/schemas/inventory.DepotProductStockSnapshot" }, "type": "array", "uniqueItems": false }, "is_out_of_stock": { "type": "boolean" }, "locations": { "items": { "$ref": "#/components/schemas/inventory.LocationProductStockSnapshot" }, "type": "array", "uniqueItems": false }, "package_options": { "items": { "$ref": "#/components/schemas/inventory.PackageOptionProductStockSnapshot" }, "type": "array", "uniqueItems": false }, "revision": { "type": "integer" }, "sku_code": { "type": "string" }, "timezone": { "type": "string" } }, "type": "object" }, "inventory.StockMovement": { "properties": { "allocation_id": { "type": "string" }, "base_units": { "type": "integer" }, "cause": { "$ref": "#/components/schemas/inventory.InventoryCauseRef" }, "classification": { "$ref": "#/components/schemas/security_enums.DataClassification" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "damage_report_id": { "type": "string" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "type": "string" }, "deletion_requested_at": { "type": "string" }, "destination_balance_after_base_units": { "type": "integer" }, "destination_bucket_id": { "type": "string" }, "destination_package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "destination_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "lot_id": { "type": "string" }, "note": { "type": "string" }, "occurred_at": { "type": "string" }, "order_number": { "type": "string" }, "performed_by": { "type": "string" }, "protection_basis": { "$ref": "#/components/schemas/security_enums.DataProtectionBasis" }, "purchase_order_number": { "type": "string" }, "purchase_receipt_id": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "reason_code": { "type": "string" }, "reservation_id": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "type": "string" }, "sku_code": { "type": "string" }, "source_balance_after_base_units": { "type": "integer" }, "source_bucket_id": { "type": "string" }, "source_package_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "source_package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "staging_record_id": { "type": "string" }, "type": { "$ref": "#/components/schemas/warehouse_enums.StockMovementType" } }, "type": "object" }, "inventory.StockReservation": { "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "format": "date-time", "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "eligibility_token": { "type": "string" }, "expires_at": { "format": "date-time", "type": "string" }, "group_order_code": { "type": "string" }, "id": { "type": "string" }, "listing_revision": { "format": "int64", "type": "integer" }, "market_code": { "type": "string" }, "order_number": { "type": "string" }, "requested_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "reserved_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "status": { "enum": [ "RESERVED", "PARTIALLY_STAGED", "STAGED", "COMMITTED", "RELEASED", "EXPIRED", "CANCELLED" ], "type": "string" }, "timezone": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "sku_code", "depot_code", "market_code", "eligibility_token", "timezone", "listing_revision", "revision", "requested_composition", "reserved_composition", "status", "created_at", "updated_at" ], "type": "object" }, "inventory.StockReservationAllocation": { "description": "Exactly one physical evidence variant must be supplied.", "oneOf": [ { "required": [ "known_lot_physical" ] }, { "required": [ "unknown_identity_physical" ] }, { "required": [ "unallocated_no_lot_physical" ] } ], "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "bucket_id": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "id": { "type": "string" }, "known_lot_physical": { "$ref": "#/components/schemas/inventory.KnownLotPhysicalEvidence" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reservation_id": { "type": "string" }, "revision": { "type": "integer" }, "unallocated_no_lot_physical": { "$ref": "#/components/schemas/inventory.UnallocatedNoLotPhysicalEvidence" }, "unknown_identity_physical": { "$ref": "#/components/schemas/inventory.UnknownReturnPhysicalEvidence" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "inventory.StockStagingRecord": { "properties": { "allocation_id": { "type": "string" }, "destination_bucket_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "movement_id": { "type": "string" }, "order_number": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reservation_id": { "type": "string" }, "sku_code": { "type": "string" }, "source_bucket_id": { "type": "string" }, "source_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "staged_at": { "type": "string" }, "staged_by": { "type": "string" }, "staged_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "type": "object" }, "inventory.StorefrontPlaceAvailability": { "description": "Retail detail availability for the displayed commercial package_option in an active public depot serving the request market_code. Uses the same inventory safety filters as commercial availability and does not reserve stock.", "properties": { "administrative_area_code": { "type": "string" }, "as_of": { "type": "string" }, "available_base_units": { "type": "integer" }, "country_code": { "type": "string" }, "depot_code": { "type": "string" }, "depot_name": { "type": "string" }, "locality": { "type": "string" }, "region_code": { "type": "string" }, "region_name": { "type": "string" }, "stock_state": { "$ref": "#/components/schemas/product_enums.StorefrontStockState" } }, "type": "object" }, "inventory.UnallocatedNoLotPhysicalEvidence": { "properties": { "source_bucket_id": { "type": "string" } }, "required": [ "source_bucket_id" ], "type": "object" }, "inventory.UnknownReturnPhysicalEvidence": { "properties": { "return_sources": { "items": { "$ref": "#/components/schemas/inventory.UnknownReturnSource" }, "minItems": 1, "type": "array" } }, "required": [ "return_sources" ], "type": "object" }, "inventory.UnknownReturnSource": { "properties": { "base_units": { "format": "int64", "minimum": 1, "type": "integer" }, "receiving_id": { "type": "string" } }, "required": [ "receiving_id", "base_units" ], "type": "object" }, "listing.DamageSaleApproval": { "properties": { "approved_at": { "type": "string" }, "approved_by": { "type": "string" }, "quality_assessment_id": { "type": "string" }, "reason_code": { "type": "string" }, "tier": { "$ref": "#/components/schemas/warehouse_enums.DamageSaleTier" } }, "type": "object" }, "listing.SaleEligibilitySnapshot": { "description": "Eligibility is the FULL contract listing.SaleEligibilitySnapshot,\nserialised by the contract model and never re-declared, trimmed, or\nreordered here. Pricing embeds this value verbatim into\nquote.PriceSnapshot.Eligibility.", "properties": { "available_base_units": { "type": "integer" }, "bucket_id": { "type": "string" }, "captured_at": { "type": "string" }, "condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "damage_approval": { "$ref": "#/components/schemas/listing.DamageSaleApproval" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "depot_code": { "type": "string" }, "disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "expiry_lead_days": { "description": "ExpiryLeadDays is the soon-expiry lead time that was in force, after\nany listing override.", "type": "integer" }, "inventory_revision": { "type": "integer" }, "listing_revision": { "type": "integer" }, "lot_id": { "type": "string" }, "market_code": { "type": "string" }, "sku_code": { "type": "string" }, "stock_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "stock_unit_id": { "type": "string" }, "tax_category_code": { "type": "string" }, "valid_until": { "type": "string" }, "validity_token": { "type": "string" } }, "type": "object" }, "listing.SaleRestriction": { "additionalProperties": false, "description": "Canonical v42 policy. Below allows completed age \u003c threshold; above allows \u003e= threshold. Age applies to retail buyers independent of channel; wholesale bypasses age. Viewing remains allowed. Exactly one restriction per kind; age forbids channels/value/delivery fields, non-age forbids age fields, delivery exclusions require distinct canonical methods, quantity_limit requires positive value. Present restriction fields cannot be null.", "properties": { "age_comparison": { "enum": [ "below", "above" ], "type": "string" }, "age_years": { "maximum": 2147483647, "minimum": 0, "type": "integer" }, "channels": { "items": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "type": "array", "uniqueItems": true }, "excluded_delivery_methods": { "items": { "enum": [ "delivery", "pickup", "outsourced" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "$ref": "#/components/schemas/listing_enums.SaleRestrictionKind" }, "note": { "type": "string" }, "value": { "maximum": 9223372036854776000, "minimum": 0, "type": "integer" } }, "required": [ "kind" ], "type": "object" }, "listing_enums.MarketListingStatus": { "enum": [ "draft", "coming_soon", "active", "suspended", "unavailable", "delisted" ], "type": "string", "x-enum-varnames": [ "MarketListingStatusDraft", "MarketListingStatusComingSoon", "MarketListingStatusActive", "MarketListingStatusSuspended", "MarketListingStatusUnavailable", "MarketListingStatusDelisted" ] }, "listing_enums.SaleRestrictionKind": { "enum": [ "age", "quantity_limit", "channel_excluded", "delivery_excluded", "prescription" ], "type": "string", "x-enum-varnames": [ "SaleRestrictionKindAge", "SaleRestrictionKindQuantityLimit", "SaleRestrictionKindChannelExcluded", "SaleRestrictionKindDeliveryExcluded", "SaleRestrictionKindPrescription" ] }, "listings.BulkDepotMarketRequest": { "additionalProperties": false, "properties": { "ids": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed Mongo ObjectId, returned as lowercase hex.", "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "patch": { "$ref": "#/components/schemas/bulk.ActivePatch" } }, "required": [ "ids", "patch" ], "type": "object" }, "listings.BulkDepotMarketResult": { "additionalProperties": false, "properties": { "ids": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed Mongo ObjectId, returned as lowercase hex.", "pattern": "^[0-9a-fA-F]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "ids", "updated_count" ], "type": "object" }, "localization.LocalizedDescription": { "properties": { "description": { "type": "string" }, "language": { "type": "string" } }, "type": "object" }, "localization.LocalizedName": { "properties": { "language": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "localization.LocalizedText": { "properties": { "language": { "type": "string" }, "text": { "type": "string" } }, "type": "object" }, "market_enums.PriceAudience": { "enum": [ "retail", "wholesale" ], "type": "string", "x-enum-varnames": [ "PriceAudienceRetail", "PriceAudienceWholesale" ] }, "marketing_enums.CampaignPredictionSource": { "enum": [ "same_series", "similar_event", "last_14_days_doubled" ], "type": "string", "x-enum-varnames": [ "CampaignPredictionSourceSameSeries", "CampaignPredictionSourceSimilarEvent", "CampaignPredictionSourceLast14DaysDoubled" ] }, "marketing_enums.CampaignPredictionStatus": { "enum": [ "not_applicable", "ready", "warning" ], "type": "string", "x-enum-varnames": [ "CampaignPredictionStatusNotApplicable", "CampaignPredictionStatusReady", "CampaignPredictionStatusWarning" ] }, "measurement.Dimensions": { "properties": { "height_mm": { "type": "integer" }, "length_mm": { "type": "integer" }, "width_mm": { "type": "integer" } }, "type": "object" }, "measurement.Measure": { "properties": { "amount": { "type": "integer" }, "exponent": { "type": "integer" }, "unit": { "type": "string" } }, "type": "object" }, "measurement.NetContent": { "description": "NetContent is the FULL contract measurement.NetContent. It is the only\nsource of unit-price evidence on the platform: catalog.listing_changed\ncarries no measurement facts, so if this is absent Pricing cannot compute\na comparison price at all. Absent means the SKU declares none — which is\nexactly the case that blocks activation of a unit-pricing-required\nlisting — and it is never fabricated or defaulted to \"1 each\".", "properties": { "net_quantity": { "$ref": "#/components/schemas/measurement.Measure" }, "standard_measure": { "$ref": "#/components/schemas/measurement.Measure" } }, "type": "object" }, "measurement.Weight": { "properties": { "grams": { "type": "integer" } }, "type": "object" }, "metadata.Metadata": { "additionalProperties": {}, "type": "object" }, "money.CurrencyExponent": { "description": "CurrencyExponent is minor units per major unit as a power of ten. It is\ncarried because no service may assume every currency has two decimals.", "properties": { "currency": { "type": "string" }, "exponent": { "type": "integer" } }, "type": "object" }, "money.Money": { "properties": { "amount_minor": { "type": "integer" }, "currency": { "type": "string" } }, "type": "object" }, "order_enums.FulfillmentStatus": { "enum": [ "unfulfilled", "picking_in_progress", "packing", "packed", "fulfilled", "cancelled" ], "type": "string", "x-enum-varnames": [ "FulfillmentStatusUnfulfilled", "FulfillmentStatusPickingInProgress", "FulfillmentStatusPacking", "FulfillmentStatusPacked", "FulfillmentStatusFulfilled", "FulfillmentStatusCancelled" ] }, "packaging.PackageComponentSnapshot": { "properties": { "base_units": { "type": "integer" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "package_count": { "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "units_per_package": { "type": "integer" } }, "type": "object" }, "packaging.PackageCompositionSnapshot": { "properties": { "components": { "items": { "$ref": "#/components/schemas/packaging.PackageComponentSnapshot" }, "type": "array", "uniqueItems": false }, "total_base_units": { "type": "integer" } }, "type": "object" }, "packaging.PackageOptionRef": { "additionalProperties": false, "properties": { "code": { "pattern": "^(EACH|CASE[1-9][0-9]*)$", "type": "string" }, "sku_code": { "minLength": 1, "type": "string" }, "version": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "packaging_enums.PackageHandlingUnit": { "enum": [ "EACH", "CASE" ], "type": "string", "x-enum-varnames": [ "PackageHandlingUnitEach", "PackageHandlingUnitCase" ] }, "packing.FinishAbort": { "properties": { "intent": { "$ref": "#/components/schemas/packing.FinishIntent" }, "requested_at": { "format": "date-time", "type": "string" }, "schema": { "enum": [ "orders-packing-finish-abort/1" ], "type": "string" } }, "required": [ "schema", "intent", "requested_at" ], "type": "object" }, "packing.FinishCompletion": { "properties": { "completed_at": { "format": "date-time", "type": "string" }, "hold_fingerprint": { "type": "string" }, "intent": { "$ref": "#/components/schemas/packing.FinishIntent" }, "schema": { "enum": [ "orders-packing-finish-completion/1" ], "type": "string" } }, "required": [ "schema", "intent", "hold_fingerprint", "completed_at" ], "type": "object" }, "packing.FinishHold": { "properties": { "fingerprint": { "type": "string" }, "held_at": { "format": "date-time", "type": "string" }, "intent": { "$ref": "#/components/schemas/packing.FinishIntent" }, "schema": { "enum": [ "supply-packing-finish-hold/1" ], "type": "string" } }, "required": [ "schema", "intent", "fingerprint", "held_at" ], "type": "object" }, "packing.FinishIntent": { "properties": { "fulfillment_generation": { "format": "int64", "type": "integer" }, "intent_id": { "type": "string" }, "order_number": { "type": "string" }, "packing_id": { "type": "string" }, "packing_revision": { "format": "int64", "type": "integer" }, "schema": { "enum": [ "orders-packing-finish-intent/1" ], "type": "string" } }, "required": [ "schema", "order_number", "fulfillment_generation", "packing_id", "packing_revision", "intent_id" ], "type": "object" }, "packing.FinishOutcome": { "description": "A held result contains hold; a released result contains hold, completion, released_at and fingerprint; an aborted result contains intent, abort, aborted_at and fingerprint. Missing or failed reads are not evidence of an abort.", "properties": { "abort": { "$ref": "#/components/schemas/packing.FinishAbort" }, "aborted_at": { "format": "date-time", "type": "string" }, "completion": { "$ref": "#/components/schemas/packing.FinishCompletion" }, "fingerprint": { "type": "string" }, "hold": { "$ref": "#/components/schemas/packing.FinishHold" }, "intent": { "$ref": "#/components/schemas/packing.FinishIntent" }, "released_at": { "format": "date-time", "type": "string" }, "state": { "enum": [ "held", "released", "aborted" ], "type": "string" } }, "required": [ "state" ], "type": "object" }, "packing.FinishOutcomeResponse": { "properties": { "data": { "$ref": "#/components/schemas/packing.FinishOutcome" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "packing.FinishRequest": { "additionalProperties": false, "properties": { "intent_id": { "type": "string" }, "order_number": { "type": "string" } }, "required": [ "order_number", "intent_id" ], "type": "object" }, "packing.ShortageAllocationSelection": { "properties": { "allocation_id": { "type": "string" }, "allocation_revision": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "unit_ids": { "items": { "type": "string" }, "type": "array" } }, "required": [ "allocation_id", "allocation_revision", "bucket_id", "bucket_revision", "composition" ], "type": "object" }, "packing.ShortageReleaseCandidate": { "properties": { "allocation_id": { "type": "string" }, "allocation_revision": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "lot_id": { "type": "string" }, "unit_tracked": { "type": "boolean" } }, "required": [ "allocation_id", "allocation_revision", "bucket_id", "bucket_revision", "composition", "unit_tracked", "location" ], "type": "object" }, "packing.ShortageReleaseCursor": { "properties": { "after_id": { "type": "string" }, "query_hash": { "type": "string" } }, "required": [ "after_id", "query_hash" ], "type": "object" }, "packing.ShortageReleasePage": { "properties": { "candidates": { "items": { "$ref": "#/components/schemas/packing.ShortageReleaseCandidate" }, "type": "array" }, "discrepancy_id": { "type": "string" }, "next": { "$ref": "#/components/schemas/packing.ShortageReleaseCursor" }, "packing_revision": { "format": "int64", "type": "integer" }, "stock_fence": { "format": "int64", "type": "integer" } }, "required": [ "packing_revision", "discrepancy_id", "stock_fence", "candidates" ], "type": "object" }, "packing.ShortageReleaseUnit": { "properties": { "clearance_label_code": { "type": "string" }, "id": { "type": "string" }, "unit_label_code": { "type": "string" } }, "required": [ "id" ], "type": "object" }, "packing.ShortageReleaseUnitPage": { "properties": { "allocation_id": { "type": "string" }, "allocation_revision": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "discrepancy_id": { "type": "string" }, "next": { "$ref": "#/components/schemas/packing.ShortageReleaseCursor" }, "packing_revision": { "format": "int64", "type": "integer" }, "stock_fence": { "format": "int64", "type": "integer" }, "units": { "items": { "$ref": "#/components/schemas/packing.ShortageReleaseUnit" }, "type": "array" } }, "required": [ "packing_revision", "discrepancy_id", "stock_fence", "allocation_id", "allocation_revision", "bucket_id", "bucket_revision", "units" ], "type": "object" }, "packing.SourceAllocation": { "properties": { "allocated_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "allocation_id": { "type": "string" }, "handling_unit": { "type": "string" }, "lot_id": { "type": "string" }, "original_bucket_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reservation_id": { "type": "string" }, "reservation_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "unit_tracked": { "type": "boolean" } }, "required": [ "reservation_id", "reservation_revision", "allocation_id", "original_bucket_id", "package_option", "handling_unit", "allocated_composition", "unit_tracked" ], "type": "object" }, "packing.SourceAllocationPage": { "properties": { "allocations": { "items": { "$ref": "#/components/schemas/packing.SourceAllocation" }, "type": "array" }, "depot_code": { "type": "string" }, "next_cursor": { "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "packing_revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "stock_fence": { "format": "int64", "type": "integer" } }, "required": [ "packing_revision", "order_number", "order_item_id", "sku_code", "depot_code", "stock_fence", "allocations" ], "type": "object" }, "packing.SourceOption": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "handling_unit": { "type": "string" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "physical_base_units": { "format": "int64", "type": "integer" }, "reserved_allocation_ids": { "items": { "type": "string" }, "type": "array" }, "unit_tracked": { "type": "boolean" } }, "required": [ "bucket_id", "reserved_allocation_ids", "bucket_revision", "location", "package_option", "handling_unit", "physical_base_units", "unit_tracked" ], "type": "object" }, "packing.SourcePage": { "properties": { "depot_code": { "type": "string" }, "next_cursor": { "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "packing_revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/packing.SourceOption" }, "type": "array" }, "stock_fence": { "format": "int64", "type": "integer" } }, "required": [ "packing_revision", "order_number", "order_item_id", "sku_code", "depot_code", "stock_fence", "sources" ], "type": "object" }, "packing.SourceUnit": { "properties": { "allocation_id": { "type": "string" }, "base_units": { "format": "int64", "type": "integer" }, "requires_reassignment": { "type": "boolean" }, "revision": { "format": "int64", "type": "integer" }, "unit_id": { "type": "string" }, "unit_label_code": { "type": "string" } }, "required": [ "unit_id", "base_units", "revision" ], "type": "object" }, "packing.SourceUnitPage": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "next_cursor": { "type": "string" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "packing_revision": { "format": "int64", "type": "integer" }, "stock_fence": { "format": "int64", "type": "integer" }, "units": { "items": { "$ref": "#/components/schemas/packing.SourceUnit" }, "type": "array" } }, "required": [ "packing_revision", "order_number", "order_item_id", "bucket_id", "bucket_revision", "stock_fence", "units" ], "type": "object" }, "party.ContactAddress": { "description": "Addresses.", "properties": { "address": { "$ref": "#/components/schemas/geography.Address" }, "contact": { "$ref": "#/components/schemas/party.Recipient" }, "id": { "description": "ID is populated for persisted address-book entries. Inline checkout,\norder, billing, and fulfilment snapshots may leave it empty.", "type": "string" } }, "type": "object" }, "party.Recipient": { "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "type": "object" }, "pricebook.SellingPrice": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "audience": { "type": "string" }, "channel": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "display": { "$ref": "#/components/schemas/pricebook.SellingPriceDisplay" }, "market_code": { "type": "string" }, "price_visibility": { "type": "string" }, "tax_inclusion": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/money.Money" }, "valid_from": { "format": "date-time", "type": "string" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "unit_price", "currency_exponent", "market_code", "channel", "audience", "price_visibility", "tax_inclusion", "valid_from", "as_of" ], "type": "object" }, "pricebook.SellingPriceDisplay": { "properties": { "compare_at_unit_price": { "$ref": "#/components/schemas/money.Money" }, "effective_unit_price": { "$ref": "#/components/schemas/money.Money" }, "offers": { "items": { "$ref": "#/components/schemas/pricebook.SellingPriceOffer" }, "type": "array" }, "promotions": { "items": { "$ref": "#/components/schemas/pricebook.SellingPromotionDisplay" }, "type": "array" }, "regular_unit_price": { "$ref": "#/components/schemas/money.Money" }, "unit_price_per_measure": { "$ref": "#/components/schemas/pricebook.SellingUnitPriceDisplay" } }, "required": [ "regular_unit_price", "effective_unit_price" ], "type": "object" }, "pricebook.SellingPriceOffer": { "description": "Pricing-owned conditional or alternative presentation; offers do not replace the enclosing guest effective price.", "properties": { "base_units": { "format": "int64", "type": "integer" }, "compare_at_amount": { "$ref": "#/components/schemas/money.Money" }, "conditional": { "type": "boolean" }, "conditions": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array" }, "effective_amount": { "$ref": "#/components/schemas/money.Money" }, "membership_tier_key": { "type": "string" }, "messages": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "promotions": { "items": { "$ref": "#/components/schemas/pricebook.SellingPromotionDisplay" }, "type": "array" }, "regular_amount": { "$ref": "#/components/schemas/money.Money" }, "valid_from": { "format": "date-time", "type": "string" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "base_units", "regular_amount", "effective_amount", "conditional", "valid_from" ], "type": "object" }, "pricebook.SellingPromotionDiscountValue": { "description": "Authored customer-visible discount. Percent discounts use basis_points; monetary discounts and fixed prices use amount.", "properties": { "amount": { "$ref": "#/components/schemas/money.Money" }, "basis_points": { "format": "int64", "type": "integer" } }, "type": "object" }, "pricebook.SellingPromotionDisplay": { "properties": { "applied_to_effective_price": { "type": "boolean" }, "conditional": { "type": "boolean" }, "conditions": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array" }, "discount_type": { "enum": [ "percent_off", "amount_off", "fixed_price" ], "type": "string" }, "discount_value": { "$ref": "#/components/schemas/pricebook.SellingPromotionDiscountValue" }, "kind": { "type": "string" }, "member_series_keys": { "description": "Display fact from Pricing (Shared Contract v53.10.0) - SKU series keys whose units count toward a conditional promotion. Omitted when it does not apply.", "items": { "type": "string" }, "type": "array" }, "member_sku_codes": { "description": "Display fact from Pricing (Shared Contract v53.10.0) - SKU codes whose units count toward a conditional promotion. Omitted when it does not apply.", "items": { "type": "string" }, "type": "array" }, "messages": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array" }, "promotion_id": { "description": "Corresponding customer-visible storefront promotion ID, when applicable.", "type": "string" }, "required_quantity": { "description": "Display fact from Pricing (Shared Contract v53.10.0) - the unit count that qualifies a conditional promotion. Not an executable rule. Omitted when it does not apply.", "format": "int64", "type": "integer" }, "terms": { "allOf": [ { "$ref": "#/components/schemas/pricebook.SellingPromotionTerms" } ], "description": "Display fact from Pricing (Shared Contract v53.15.0) - the customer-safe deal terms. Omitted when the promotion has none." }, "valid_from": { "format": "date-time", "type": "string" }, "valid_until": { "format": "date-time", "type": "string" } }, "required": [ "kind", "conditional", "applied_to_effective_price" ], "type": "object" }, "pricebook.SellingPromotionGiftTerms": { "description": "One tier of a multi-tier gift deal, passed through from Pricing (Shared Contract v53.15.0). Display facts, never executable rules.", "properties": { "gift_base_units": { "description": "Free units this tier gives.", "format": "int64", "type": "integer" }, "minimum_order_amount": { "$ref": "#/components/schemas/money.Money" }, "qualifier_base_units": { "description": "Paid units that qualify this tier; the free units are extra.", "format": "int64", "type": "integer" } }, "type": "object" }, "pricebook.SellingPromotionTerms": { "description": "Customer-safe deal terms of a promotion, passed through from Pricing (Shared Contract v53.15.0). Display facts, never executable rules; every term is omitted, not zeroed, when the deal has none.", "properties": { "addon_package_price": { "$ref": "#/components/schemas/money.Money" }, "base_units_per_award": { "description": "Units the cart needs to earn one award (same-SKU BOGO is qualifier plus gift; cross-SKU BOGO is the qualifier alone). Clients use this value rather than deriving it.", "format": "int64", "type": "integer" }, "bundle_package_price": { "$ref": "#/components/schemas/money.Money" }, "discount_amount": { "$ref": "#/components/schemas/money.Money" }, "discount_basis_points": { "description": "Offer value of a percent discount deal.", "format": "int64", "type": "integer" }, "fixed_package_price": { "$ref": "#/components/schemas/money.Money" }, "gift_base_units": { "description": "Free units one award gives.", "format": "int64", "type": "integer" }, "gift_tiers": { "description": "Each tier of a multi-tier gift deal.", "items": { "$ref": "#/components/schemas/pricebook.SellingPromotionGiftTerms" }, "type": "array" }, "group_package_count": { "format": "int64", "type": "integer" }, "maximum_applications_per_customer": { "description": "Per-customer limit, when one is set; never how much of it has been used.", "format": "int64", "type": "integer" }, "minimum_order_amount": { "$ref": "#/components/schemas/money.Money" }, "qualifier_base_units": { "description": "Paid units that qualify one award; the free units are extra (same-SKU Buy 1 get 1 is qualifier 1, gift 1).", "format": "int64", "type": "integer" } }, "type": "object" }, "pricebook.SellingUnitPriceDisplay": { "properties": { "comparison_amount": { "$ref": "#/components/schemas/money.Money" }, "exempt": { "type": "boolean" }, "exemption_reason": { "type": "string" }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" } }, "required": [ "net_content", "exempt" ], "type": "object" }, "procurement.NetGoodsCostSourceSnapshot": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "confirmed_at": { "format": "date-time", "type": "string" }, "issue_date": { "type": "string" }, "net_goods_amount": { "$ref": "#/components/schemas/money.Money" }, "provisional": { "type": "boolean" }, "receipt_id": { "type": "string" }, "receipt_item_id": { "type": "string" }, "source_id": { "type": "string" }, "source_line_id": { "type": "string" }, "source_revision": { "format": "int64", "type": "integer" }, "source_type": { "type": "string" } }, "required": [ "source_type", "source_id", "source_revision", "base_units", "provisional" ], "type": "object" }, "procurement.NetGoodsValuationMovement": { "properties": { "actor": { "$ref": "#/components/schemas/security.ActorRef" }, "balance_consumed_cost_variance_minor_after": { "format": "int64", "type": "integer" }, "balance_net_goods_cost_minor_after": { "format": "int64", "type": "integer" }, "balance_provisional_base_units_after": { "format": "int64", "type": "integer" }, "balance_rounding_variance_minor_after": { "format": "int64", "type": "integer" }, "balance_unvalued_base_units_after": { "format": "int64", "type": "integer" }, "balance_valued_base_units_after": { "format": "int64", "type": "integer" }, "classification": { "type": "string" }, "consumed_cost_variance_minor_delta": { "format": "int64", "type": "integer" }, "contains_pii": { "type": "boolean" }, "contains_sensitive_pii": { "type": "boolean" }, "correlation_id": { "type": "string" }, "currency": { "type": "string" }, "data_owner_id": { "type": "string" }, "deletion_completed_at": { "format": "date-time", "type": "string" }, "deletion_requested_at": { "format": "date-time", "type": "string" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "legal_hold": { "type": "boolean" }, "occurred_at": { "format": "date-time", "type": "string" }, "on_hand_cost_minor_delta": { "format": "int64", "type": "integer" }, "protection_basis": { "type": "string" }, "provisional_base_unit_delta": { "format": "int64", "type": "integer" }, "reference_id": { "type": "string" }, "reference_line_id": { "type": "string" }, "reference_type": { "type": "string" }, "request_id": { "type": "string" }, "retention_policy_key": { "type": "string" }, "retention_until": { "format": "date-time", "type": "string" }, "reverses_movement_id": { "type": "string" }, "revision": { "format": "int64", "type": "integer" }, "rounding_variance_minor_delta": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "source_correction_amount": { "$ref": "#/components/schemas/money.Money" }, "source_movement_ids": { "items": { "type": "string" }, "type": "array" }, "sources": { "items": { "$ref": "#/components/schemas/procurement.NetGoodsCostSourceSnapshot" }, "type": "array" }, "unvalued_base_unit_delta": { "format": "int64", "type": "integer" }, "valued_base_unit_delta": { "format": "int64", "type": "integer" } }, "required": [ "id", "sku_code", "depot_code", "currency", "reference_type", "reference_id", "valued_base_unit_delta", "provisional_base_unit_delta", "unvalued_base_unit_delta", "on_hand_cost_minor_delta", "consumed_cost_variance_minor_delta", "rounding_variance_minor_delta", "balance_valued_base_units_after", "balance_provisional_base_units_after", "balance_unvalued_base_units_after", "balance_net_goods_cost_minor_after", "balance_consumed_cost_variance_minor_after", "balance_rounding_variance_minor_after", "revision", "occurred_at", "actor" ], "type": "object" }, "procurement.NetGoodsValuationSnapshot": { "properties": { "as_of": { "format": "date-time", "type": "string" }, "average_valued_unit_cost": { "$ref": "#/components/schemas/money.Money" }, "consumed_cost_variance_minor": { "format": "int64", "type": "integer" }, "currency": { "type": "string" }, "currency_exponent": { "$ref": "#/components/schemas/money.CurrencyExponent" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "net_goods_cost_minor": { "format": "int64", "type": "integer" }, "provisional_base_units": { "format": "int64", "type": "integer" }, "revision": { "format": "int64", "type": "integer" }, "rounding_variance_minor": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "unvalued_base_units": { "format": "int64", "type": "integer" }, "valued_base_units": { "format": "int64", "type": "integer" } }, "required": [ "id", "sku_code", "depot_code", "currency", "currency_exponent", "valued_base_units", "provisional_base_units", "unvalued_base_units", "net_goods_cost_minor", "consumed_cost_variance_minor", "rounding_variance_minor", "revision", "as_of" ], "type": "object" }, "procurement.PurchaseOrder": { "properties": { "cancelled_at": { "type": "string" }, "completed_at": { "type": "string" }, "confirmed_at": { "type": "string" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "currency": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "description": "DepotCode, MarketCode, and CountryCode are the denormalized receiving\nsite, market, and country, carried so a geographically scoped staff\nquery is a plain indexed match.", "type": "string" }, "expected_at": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "internal_note": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/procurement.PurchaseOrderItem" }, "type": "array", "uniqueItems": false }, "market_code": { "type": "string" }, "note": { "type": "string" }, "order_number": { "type": "string" }, "reference": { "type": "string" }, "shipping_cost": { "$ref": "#/components/schemas/money.Money" }, "status": { "$ref": "#/components/schemas/purchase_enums.PurchaseOrderStatus" }, "submitted_at": { "type": "string" }, "subtotal": { "$ref": "#/components/schemas/money.Money" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" }, "tax_amount": { "$ref": "#/components/schemas/money.Money" }, "total": { "$ref": "#/components/schemas/money.Money" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "procurement.PurchaseOrderItem": { "properties": { "captured_at": { "type": "string" }, "id": { "type": "string" }, "line_total": { "$ref": "#/components/schemas/money.Money" }, "net_goods_amount": { "$ref": "#/components/schemas/money.Money", "description": "Frozen goods amount after all discounts and excluding every tax, freight and duty; matched to ordered_composition.total_base_units." }, "note": { "type": "string" }, "ordered_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_image": { "$ref": "#/components/schemas/security.ObjectMedia" }, "product_name": { "type": "string" }, "product_package_option": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "received_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "rejected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "selected_package_cost": { "$ref": "#/components/schemas/money.Money", "description": "Frozen cost of exactly one selected package, mutually exclusive with unit_cost. Absent is distinct from known zero; line_total = selected_package_cost * package_count." }, "sku_code": { "description": "SKUCode is the frozen SKU code captured when the purchase line was raised.", "type": "string" }, "unit_cost": { "$ref": "#/components/schemas/money.Money", "description": "Optional frozen per-base-unit cost for legacy and replenishment lines. Never reinterpret or derive by rounded division of a package price." } }, "type": "object" }, "procurement.PurchaseReceipt": { "properties": { "confirmed_at": { "type": "string" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "items": { "items": { "$ref": "#/components/schemas/procurement.PurchaseReceiptItem" }, "type": "array", "uniqueItems": false }, "market_code": { "type": "string" }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "received_at": { "type": "string" }, "reference": { "type": "string" }, "status": { "$ref": "#/components/schemas/purchase_enums.PurchaseReceiptStatus" }, "supplier_code": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "procurement.PurchaseReceiptItem": { "properties": { "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "destination_bucket_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "manufacturer_lot_code": { "type": "string" }, "note": { "type": "string" }, "ordered_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_name": { "type": "string" }, "purchase_order_item_id": { "description": "Exact purchase-order line supplying provisional net-goods cost evidence.", "type": "string" }, "received_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "rejected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "sku_code": { "description": "SKUCode is the frozen SKU code captured when the receipt line was recorded.", "type": "string" }, "supplier_lot_code": { "type": "string" } }, "type": "object" }, "procurement.SupplierInvoiceDocument": { "properties": { "content_sha256": { "type": "string" }, "media_code": { "type": "string" }, "received_at": { "format": "date-time", "type": "string" }, "reference": { "type": "string" } }, "required": [ "reference", "content_sha256", "received_at" ], "type": "object" }, "procurement.SupplierInvoiceLine": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "calculated_tax": { "$ref": "#/components/schemas/money.Money" }, "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "declared_tax": { "$ref": "#/components/schemas/money.Money" }, "description": { "type": "string" }, "duty_amount": { "$ref": "#/components/schemas/money.Money" }, "freight_amount": { "$ref": "#/components/schemas/money.Money" }, "id": { "type": "string" }, "input_tax_claim": { "type": "string" }, "line_amount": { "$ref": "#/components/schemas/money.Money" }, "net_goods_amount": { "$ref": "#/components/schemas/money.Money" }, "note": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "price_basis": { "type": "string" }, "purchase_order_number": { "type": "string" }, "receipt_allocations": { "items": { "$ref": "#/components/schemas/procurement.SupplierInvoiceReceiptAllocation" }, "type": "array" }, "receipt_id": { "type": "string" }, "recoverable_tax": { "$ref": "#/components/schemas/money.Money" }, "sku_code": { "type": "string" }, "tax_source": { "type": "string" }, "tax_treatment": { "type": "string" }, "unit_price": { "$ref": "#/components/schemas/money.Money" } }, "required": [ "id", "sku_code", "composition", "base_units", "unit_price", "line_amount", "tax_treatment", "price_basis", "tax_source", "input_tax_claim" ], "type": "object" }, "procurement.SupplierInvoiceReceiptAllocation": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "net_goods_amount": { "$ref": "#/components/schemas/money.Money" }, "receipt_id": { "type": "string" }, "receipt_item_id": { "type": "string" } }, "required": [ "receipt_id", "receipt_item_id", "base_units" ], "type": "object" }, "procurement.SupplierTaxIdentity": { "properties": { "business_number": { "type": "string" }, "business_number_scheme": { "type": "string" }, "supplier_code": { "type": "string" }, "supplier_name": { "type": "string" }, "tax_registered": { "type": "boolean" }, "tax_registered_from": { "type": "string" } }, "required": [ "supplier_code", "supplier_name", "tax_registered" ], "type": "object" }, "product.CategorySalesRank": { "properties": { "category_tag_code": { "type": "string" }, "category_tag_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "net_units": { "type": "integer" }, "population": { "type": "integer" }, "rank": { "type": "integer" }, "window_days": { "type": "integer" } }, "type": "object" }, "product.Images": { "properties": { "cover": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "details": { "items": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "type": "array", "uniqueItems": false }, "gallery": { "items": { "$ref": "#/components/schemas/classification.ObjectMediaRef" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "product.Product": { "properties": { "administration": { "$ref": "#/components/schemas/product.ProductAdministration" }, "barcode_assignments": { "items": { "$ref": "#/components/schemas/product.ProductBarcodeAssignment" }, "type": "array", "uniqueItems": false }, "classification": { "$ref": "#/components/schemas/product.ProductClassification" }, "content": { "$ref": "#/components/schemas/product.ProductContent" }, "id": { "type": "string" }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" }, "package_options": { "items": { "$ref": "#/components/schemas/product.ProductPackageOption" }, "type": "array", "uniqueItems": false }, "revision": { "description": "Write counter advanced by every write to the stored product\n(Shared Contract v53.1.0 product.Product.revision). Admin clients\necho it back as expected_revision on PATCH /products/{skuCode},\nPATCH /products/{skuCode}/lifecycle-tag-overrides and PUT\n/products/{skuCode}/images. 0 only appears on documents written\nbefore the revision backfill ran.", "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "status": { "$ref": "#/components/schemas/product_enums.ProductStatus" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "supply": { "$ref": "#/components/schemas/classification.ProductSupply" } }, "type": "object" }, "product.ProductAdministration": { "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "product.ProductBarcodeAssignment": { "properties": { "code": { "type": "string" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "format": { "$ref": "#/components/schemas/product_enums.BarcodeFormat" }, "is_primary": { "type": "boolean" }, "manufacturer_code": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "product.ProductClassification": { "properties": { "brands": { "items": { "$ref": "#/components/schemas/classification.BrandRef" }, "type": "array", "uniqueItems": false }, "category_tags": { "items": { "$ref": "#/components/schemas/classification.CategoryTagRef" }, "type": "array", "uniqueItems": false }, "collection_ref": { "$ref": "#/components/schemas/classification.CollectionRef" }, "sku_series_code": { "type": "string" } }, "type": "object" }, "product.ProductContent": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array", "uniqueItems": false }, "images": { "$ref": "#/components/schemas/product.Images" }, "localization": { "$ref": "#/components/schemas/product.ProductLocalization" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "origin": { "$ref": "#/components/schemas/product.ProductOrigin" } }, "type": "object" }, "product.ProductLocalization": { "properties": { "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "product.ProductOrigin": { "properties": { "country_code": { "type": "string" }, "label": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false }, "statement": { "items": { "$ref": "#/components/schemas/localization.LocalizedText" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "product.ProductPackageOption": { "properties": { "code": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "effective_from": { "type": "string" }, "effective_to": { "type": "string" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "is_active": { "type": "boolean" }, "is_canonical": { "type": "boolean" }, "sku_code": { "minLength": 1, "type": "string" }, "units_per_package": { "type": "integer" }, "version": { "format": "int64", "minimum": 1, "type": "integer" }, "weight": { "$ref": "#/components/schemas/measurement.Weight" } }, "required": [ "sku_code", "code", "version" ], "type": "object" }, "product.SalesPerformanceStats": { "properties": { "as_of": { "type": "string" }, "category_ranks": { "items": { "$ref": "#/components/schemas/product.CategorySalesRank" }, "type": "array", "uniqueItems": false }, "last_30_days": { "$ref": "#/components/schemas/product.SalesWindowStats" }, "last_7_days": { "$ref": "#/components/schemas/product.SalesWindowStats" }, "last_90_days": { "$ref": "#/components/schemas/product.SalesWindowStats" }, "last_sold_at": { "type": "string" }, "lifetime": { "$ref": "#/components/schemas/product.SalesTotals" }, "timezone": { "type": "string" } }, "type": "object" }, "product.SalesTotals": { "properties": { "gross_units": { "type": "integer" }, "net_units": { "type": "integer" }, "paid_order_count": { "type": "integer" }, "refunded_units": { "type": "integer" } }, "type": "object" }, "product.SalesWindowStats": { "properties": { "gross_units": { "type": "integer" }, "net_units": { "type": "integer" }, "paid_order_count": { "type": "integer" }, "refunded_units": { "type": "integer" }, "window_days": { "type": "integer" } }, "type": "object" }, "product.SellingProduct": { "properties": { "barcode_assignments": { "items": { "$ref": "#/components/schemas/product.SellingProductBarcode" }, "type": "array" }, "classification": { "$ref": "#/components/schemas/product.SellingProductClassification" }, "content": { "$ref": "#/components/schemas/product.SellingProductContent" }, "expiry_date": { "anyOf": [ { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, { "type": "null" } ], "description": "Optional, display-only date of the product's earliest-dated sellable lot. kind BEST_BEFORE is a best-before (quality) date; kind EXPIRY is an expiry (use-by, safety) date. date_mark_at is the instant and timezone is the IANA zone the date was printed for. Staff set it on the lot with PATCH /v1/stock/lots/{lotId}/date-mark. Only sellable stock counts (good, standard-sellable, not staged, not in an expiry-hold location, positive balance, not yet past its date), across every package form of the product, in the depots behind the read: the market's serving depots for storefront and approved wholesale reads, the selected store's depot for POS reads. There is no window here; retail storefront_display.expiry windows this same date by the effective soon-expiry lead days. The field is omitted when no sellable lot has a date mark or stock evidence is unavailable. It is not stock or sale-eligibility evidence." }, "net_content": { "$ref": "#/components/schemas/measurement.NetContent" }, "package_options": { "items": { "$ref": "#/components/schemas/product.SellingProductPackageOption" }, "type": "array" }, "price": { "$ref": "#/components/schemas/pricebook.SellingPrice" }, "sku_code": { "type": "string" }, "sku_series_code": { "type": "string" }, "storage_type": { "type": "string" } }, "required": [ "sku_code", "sku_series_code", "storage_type", "content", "classification", "package_options", "price" ], "type": "object" }, "product.SellingProductBarcode": { "properties": { "format": { "type": "string" }, "is_primary": { "type": "boolean" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "value": { "type": "string" } }, "required": [ "package_option", "value", "format", "is_primary" ], "type": "object" }, "product.SellingProductClassification": { "properties": { "brands": { "items": { "$ref": "#/components/schemas/product.SellingProductClassificationRef" }, "type": "array" }, "category_tags": { "items": { "$ref": "#/components/schemas/product.SellingProductClassificationRef" }, "type": "array" }, "collection": { "$ref": "#/components/schemas/product.SellingProductClassificationRef" } }, "required": [], "type": "object" }, "product.SellingProductClassificationRef": { "properties": { "code": { "type": "string" }, "media": { "$ref": "#/components/schemas/security.ObjectMedia" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" }, "slug": { "type": "string" } }, "required": [ "code", "name", "slug" ], "type": "object" }, "product.SellingProductContent": { "properties": { "descriptions": { "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array" }, "images": { "$ref": "#/components/schemas/product.SellingProductImages" }, "name": { "$ref": "#/components/schemas/localization.LocalizedName" }, "origin": { "$ref": "#/components/schemas/product.ProductOrigin" }, "other_names": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array" } }, "required": [ "name" ], "type": "object" }, "product.SellingProductImages": { "properties": { "cover": { "$ref": "#/components/schemas/security.ObjectMedia" }, "details": { "items": { "$ref": "#/components/schemas/security.ObjectMedia" }, "type": "array" }, "gallery": { "items": { "$ref": "#/components/schemas/security.ObjectMedia" }, "type": "array" } }, "required": [], "type": "object" }, "product.SellingProductPackageOption": { "properties": { "code": { "type": "string" }, "dimensions": { "$ref": "#/components/schemas/measurement.Dimensions" }, "handling_unit": { "type": "string" }, "is_canonical": { "type": "boolean" }, "sku_code": { "minLength": 1, "type": "string" }, "units_per_package": { "format": "int64", "type": "integer" }, "version": { "format": "int64", "minimum": 1, "type": "integer" }, "weight": { "$ref": "#/components/schemas/measurement.Weight" } }, "required": [ "code", "handling_unit", "units_per_package", "is_canonical", "sku_code", "version" ], "type": "object" }, "product_enums.BarcodeFormat": { "enum": [ "CODE_128" ], "type": "string" }, "product_enums.ProductStatus": { "enum": [ "draft", "active", "archived", "discontinued" ], "type": "string", "x-enum-varnames": [ "ProductStatusDraft", "ProductStatusActive", "ProductStatusArchived", "ProductStatusDiscontinued" ] }, "product_enums.StorefrontStockState": { "enum": [ "unknown", "in_stock", "out_of_stock" ], "type": "string", "x-enum-varnames": [ "StorefrontStockStateUnknown", "StorefrontStockStateInStock", "StorefrontStockStateOutOfStock" ] }, "productmodel.ListingPolicy": { "additionalProperties": false, "properties": { "listing_id": { "type": "string" }, "listing_revision": { "maximum": 9007199254740991, "minimum": 1, "type": "integer" }, "market_code": { "type": "string" }, "policy_contract_version": { "enum": [ "v42.0.0" ], "type": "string" }, "policy_owner": { "enum": [ "pricing" ], "type": "string" }, "restrictions": { "items": { "$ref": "#/components/schemas/productmodel.PublicSaleRestriction" }, "type": "array" } }, "required": [ "listing_id", "listing_revision", "market_code", "policy_owner", "policy_contract_version", "restrictions" ], "type": "object" }, "productmodel.POSDepotAvailability": { "description": "Current unreserved standard-sellable inventory at the configured depot, independent of price availability. Top-level state and quantity refer exclusively to the active canonical single-unit EACH package; no canonical EACH or failed evidence is unknown, never an aggregate across packages or depots. This display does not reserve stock.", "properties": { "as_of": { "description": "Original stock observation time. Consumers treat observations older than 30 seconds as unknown while refreshing; pagination does not renew this timestamp.", "format": "date-time", "type": "string" }, "available_base_units": { "description": "Omitted when unknown. Zero is confirmed no available canonical EACH inventory at the selected depot.", "format": "int64", "minimum": 0, "type": "integer" }, "depot_code": { "type": "string" }, "packages": { "items": { "$ref": "#/components/schemas/productmodel.POSPackageAvailability" }, "type": "array" }, "state": { "enum": [ "unknown", "out_of_stock", "in_stock" ], "type": "string" } }, "required": [ "depot_code", "state", "as_of", "packages" ], "type": "object" }, "productmodel.POSPackageAvailability": { "description": "Exact active package/version inventory at the selected depot. Unknown evidence omits both quantity fields; a successful empty inventory read returns zero. Whole package count is available base units divided by units_per_package, rounded down; it never treats a sealed case as loose EACH stock.", "properties": { "available_base_units": { "format": "int64", "minimum": 0, "type": "integer" }, "available_packages": { "format": "int64", "minimum": 0, "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "units_per_package": { "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "package_option", "units_per_package" ], "type": "object" }, "productmodel.PriceAvailability": { "properties": { "evaluated_at": { "format": "date-time", "type": "string" }, "generation": { "type": "string" }, "next_boundary_at": { "format": "date-time", "type": "string" }, "reason": { "type": "string" }, "status": { "enum": [ "available", "unavailable" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "productmodel.PublicSaleRestriction": { "additionalProperties": false, "description": "Canonical v42 policy. Below allows completed age \u003c threshold; above allows \u003e= threshold. Age applies to retail buyers independent of channel; wholesale bypasses age. Viewing remains allowed. Exactly one restriction per kind; age forbids channels/value/delivery fields, non-age forbids age fields, delivery exclusions require distinct canonical methods, quantity_limit requires positive value. Present restriction fields cannot be null.", "properties": { "age_comparison": { "enum": [ "below", "above" ], "type": "string" }, "age_years": { "maximum": 2147483647, "minimum": 0, "type": "integer" }, "channels": { "items": { "$ref": "#/components/schemas/commerce_enums.OrderType" }, "type": "array", "uniqueItems": true }, "excluded_delivery_methods": { "items": { "enum": [ "delivery", "pickup", "outsourced" ], "type": "string" }, "minItems": 1, "type": "array", "uniqueItems": true }, "kind": { "$ref": "#/components/schemas/listing_enums.SaleRestrictionKind" }, "value": { "maximum": 9223372036854776000, "minimum": 0, "type": "integer" } }, "required": [ "kind" ], "type": "object" }, "purchase_enums.LineTaxTreatment": { "enum": [ "taxable", "gst_free", "input_taxed", "out_of_scope", "unknown" ], "type": "string", "x-enum-varnames": [ "LineTaxTreatmentTaxable", "LineTaxTreatmentGSTFree", "LineTaxTreatmentInputTaxed", "LineTaxTreatmentOutOfScope", "LineTaxTreatmentUnknown" ] }, "purchase_enums.PurchaseOrderStatus": { "enum": [ "DRAFT", "SUBMITTED", "CONFIRMED", "PARTIALLY_RECEIVED", "RECEIVED", "CANCELLED", "REFUNDED" ], "type": "string", "x-enum-varnames": [ "PurchaseOrderStatusDraft", "PurchaseOrderStatusSubmitted", "PurchaseOrderStatusConfirmed", "PurchaseOrderStatusPartiallyReceived", "PurchaseOrderStatusReceived", "PurchaseOrderStatusCancelled", "PurchaseOrderStatusRefunded" ] }, "purchase_enums.PurchaseReceiptStatus": { "enum": [ "DRAFT", "CONFIRMED" ], "type": "string", "x-enum-varnames": [ "PurchaseReceiptStatusDraft", "PurchaseReceiptStatusConfirmed" ] }, "purchase_enums.TaxPriceBasis": { "enum": [ "inclusive", "exclusive", "unknown" ], "type": "string", "x-enum-varnames": [ "TaxPriceBasisInclusive", "TaxPriceBasisExclusive", "TaxPriceBasisUnknown" ] }, "review.PublishedReviewSubject": { "properties": { "display_name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "type": "array", "uniqueItems": false }, "reference": { "type": "string" }, "type": { "$ref": "#/components/schemas/review_enums.ReviewType" } }, "type": "object" }, "review.RatingSummary": { "properties": { "average_score": { "type": "number" }, "rating_count": { "type": "integer" }, "score_counts": { "items": { "type": "integer" }, "type": "array", "uniqueItems": false }, "subject": { "$ref": "#/components/schemas/review.PublishedReviewSubject" } }, "type": "object" }, "review_enums.ReviewRejectionReason": { "enum": [ "spam", "off_topic", "inappropriate", "personal_information", "unsupported_language", "other" ], "type": "string", "x-enum-varnames": [ "ReviewRejectionReasonSpam", "ReviewRejectionReasonOffTopic", "ReviewRejectionReasonInappropriate", "ReviewRejectionReasonPersonalInformation", "ReviewRejectionReasonUnsupportedLanguage", "ReviewRejectionReasonOther" ] }, "review_enums.ReviewType": { "enum": [ "order", "product", "campaign", "app_feedback" ], "type": "string", "x-enum-varnames": [ "ReviewTypeOrder", "ReviewTypeProduct", "ReviewTypeCampaign", "ReviewTypeAppFeedback" ] }, "security.ActorRef": { "properties": { "actor_domain": { "type": "string" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" } }, "type": "object" }, "security.HistoryChange": { "properties": { "field": { "type": "string" }, "from_value": { "type": "string" }, "to_value": { "type": "string" } }, "type": "object" }, "security.HistoryEntry": { "properties": { "actor_domain": { "$ref": "#/components/schemas/security_enums.IdentityDomain" }, "actor_email": { "type": "string" }, "actor_id": { "type": "string" }, "actor_role": { "type": "string" }, "changes": { "items": { "$ref": "#/components/schemas/security.HistoryChange" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "note": { "type": "string" }, "occurred_at": { "type": "string" }, "reason_code": { "type": "string" }, "related_resource": { "type": "string" }, "related_resource_id": { "type": "string" }, "risk_flags": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "risk_level": { "$ref": "#/components/schemas/security_enums.SecurityRiskLevel" }, "sequence": { "type": "integer" }, "source": { "type": "string" }, "summary": { "type": "string" }, "type": { "type": "string" } }, "type": "object" }, "security.ObjectMedia": { "description": "Branding and public references.", "properties": { "code": { "type": "string" }, "url": { "type": "string" } }, "type": "object" }, "security_enums.AlertLevel": { "enum": [ "OK", "WARNING", "CRITICAL", "EXPIRED" ], "type": "string", "x-enum-varnames": [ "AlertLevelOK", "AlertLevelWarning", "AlertLevelCritical", "AlertLevelExpired" ] }, "security_enums.DataClassification": { "enum": [ "public", "internal", "confidential", "restricted" ], "type": "string", "x-enum-varnames": [ "DataClassificationPublic", "DataClassificationInternal", "DataClassificationConfidential", "DataClassificationRestricted" ] }, "security_enums.DataProtectionBasis": { "enum": [ "not_applicable", "consent", "contract", "legal_obligation", "legitimate_interest" ], "type": "string", "x-enum-varnames": [ "DataProtectionBasisNotApplicable", "DataProtectionBasisConsent", "DataProtectionBasisContract", "DataProtectionBasisLegalObligation", "DataProtectionBasisLegitimateInterest" ] }, "security_enums.IdentityDomain": { "enum": [ "customer", "workforce", "service" ], "type": "string", "x-enum-varnames": [ "IdentityDomainCustomer", "IdentityDomainWorkforce", "IdentityDomainService" ] }, "security_enums.SecurityRiskLevel": { "enum": [ "low", "medium", "high", "critical" ], "type": "string", "x-enum-varnames": [ "SecurityRiskLevelLow", "SecurityRiskLevelMedium", "SecurityRiskLevelHigh", "SecurityRiskLevelCritical" ] }, "selection.ProductSelection": { "description": "Staff view of a curated, ordered product selection (Shared Contract v53.1.0 selection.ProductSelection). Media fields carry managed media codes only. Soft-deleted selections are never returned (they answer 404).", "properties": { "code": { "description": "Immutable server-generated business code (eight characters, A-Z and 0-9) assigned on create. Stays reserved after soft delete.", "example": "7KQ2M9XA", "pattern": "^[A-Z0-9]{8}$", "type": "string" }, "cover": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Managed media code from folder selection-cover. Omitted when unset. Required to publish and while published." }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "description": "Never present on API reads; soft-deleted selections answer 404.", "format": "date-time", "type": "string" }, "deleted_by": { "description": "Never present on API reads; soft-deleted selections answer 404.", "type": "string" }, "description": { "description": "Omitted when empty.", "items": { "$ref": "#/components/schemas/localization.LocalizedDescription" }, "type": "array" }, "display_order": { "description": "Ascending admin-set order; ties break by name, then code. Unique among published, non-deleted selections of one kind.", "minimum": 0, "type": "integer" }, "icon": { "$ref": "#/components/schemas/classification.ObjectMediaRef", "description": "Managed media code from folder selection-badge-icon. Omitted when unset. Required to publish (and while published) when kind is badge." }, "id": { "description": "Mongo ObjectId (hex).", "type": "string" }, "kind": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" }, "name": { "items": { "$ref": "#/components/schemas/localization.LocalizedName" }, "minItems": 1, "type": "array" }, "revision": { "description": "Optimistic-concurrency revision. Starts at 1 and increases on every successful PATCH, PUT /products and DELETE.", "format": "int64", "minimum": 1, "type": "integer" }, "slug": { "description": "Public storefront address segment (lowercase a-z, 0-9 and hyphens). Editable only while status is draft. Stays reserved after soft delete.", "example": "staff-picks", "type": "string" }, "status": { "$ref": "#/components/schemas/selection_enums.ProductSelectionStatus" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "code", "slug", "kind", "status", "name", "display_order", "revision", "created_at", "updated_at" ], "type": "object" }, "selection.ProductSelectionItem": { "description": "One ordered selection member (Shared Contract selection.ProductSelectionItem).", "properties": { "position": { "description": "Zero-based curated position.", "minimum": 0, "type": "integer" }, "selection_code": { "example": "7KQ2M9XA", "pattern": "^[A-Z0-9]{8}$", "type": "string" }, "sku_code": { "type": "string" } }, "required": [ "selection_code", "sku_code", "position" ], "type": "object" }, "selection_enums.ProductSelectionKind": { "description": "badge selections render as icon tiles (icon required to publish); section selections render as product rails.", "enum": [ "badge", "section" ], "type": "string", "x-enum-varnames": [ "ProductSelectionKindBadge", "ProductSelectionKindSection" ] }, "selection_enums.ProductSelectionStatus": { "description": "Only published selections are visible on the storefront. Transitions between the three states are otherwise free.", "enum": [ "draft", "published", "archived" ], "type": "string", "x-enum-varnames": [ "ProductSelectionStatusDraft", "ProductSelectionStatusPublished", "ProductSelectionStatusArchived" ] }, "shipping.DeliverySelection": { "properties": { "date": { "format": "date", "type": "string" }, "delivery_company": { "$ref": "#/components/schemas/courier.DeliveryCompanyRef" }, "end_at": { "format": "date-time", "type": "string" }, "schedule_code": { "type": "string" }, "schedule_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "slot_id": { "type": "string" }, "source": { "enum": [ "none", "configured_schedule", "provider" ], "type": "string" }, "start_at": { "format": "date-time", "type": "string" }, "timezone": { "type": "string" } }, "required": [ "delivery_company", "schedule_code", "schedule_revision", "slot_id", "date", "start_at", "end_at", "timezone", "source" ], "type": "object" }, "shipping.Zone": { "properties": { "administrative_area_codes": { "items": { "type": "string" }, "type": "array" }, "country_code": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "postal_codes": { "items": { "type": "string" }, "type": "array" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "type": "string" } }, "required": [ "id", "name", "country_code", "is_active" ], "type": "object" }, "shipping_enums.FulfilmentIntent": { "enum": [ "delivery", "pickup", "in_store_carry", "digital" ], "type": "string", "x-enum-varnames": [ "FulfilmentIntentDelivery", "FulfilmentIntentPickup", "FulfilmentIntentInStoreCarry", "FulfilmentIntentDigital" ] }, "stock.LocationOverwriteChange": { "properties": { "after_base_units": { "format": "int64", "type": "integer" }, "before_base_units": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "cost_status": { "description": "Overall valuation of the adjustments; unresolved if either movement remains unresolved and does not imply zero cost.", "enum": [ "valued", "unresolved" ], "type": "string" }, "counted_revision": { "description": "Bucket revision at the pending count, before any subsequent hold release.", "format": "int64", "type": "integer" }, "deficit_correction_id": { "type": "string" }, "delta_base_units": { "format": "int64", "type": "integer" }, "gain_movement_id": { "description": "Actual physical gain adjustment; present whenever new units were added", "even when losses make the net change zero or negative.": null, "type": "string" }, "loss_movement_id": { "description": "Actual physical loss adjustment; present whenever existing units were absent", "even when gains make the net change zero or positive.": null, "type": "string" }, "pending_reservation_ids": { "description": "Holds for which this bucket count is recorded but release may still require other locations.", "items": { "type": "string" }, "type": "array" }, "reconciled_reservation_ids": { "items": { "type": "string" }, "type": "array" }, "return_count_loss_sources": { "description": "Actual selected receiving IDs and count-loss quantities recorded on the existing adjustment movement.", "items": { "$ref": "#/components/schemas/inventory.UnknownReturnSource" }, "type": "array" }, "tracked_absent_unit_ids": { "description": "Existing tracked units absent from that complete count; loss_movement_id identifies their count discrepancy, not a sale.", "items": { "type": "string" }, "type": "array" }, "tracked_added_unit_ids": { "description": "Stock-unit records created for the staff-identified gain and referenced by gain_movement_id.", "items": { "type": "string" }, "type": "array" }, "tracked_counted_unit_ids": { "description": "The final observed tracked unit identities for this bucket, including newly created IDs from tracked_added_unit_ids.", "items": { "type": "string" }, "type": "array" } }, "required": [ "bucket_id", "before_base_units", "after_base_units", "delta_base_units" ], "type": "object" }, "stock.LocationOverwriteHistoryPage": { "properties": { "items": { "items": { "properties": { "receipt_id": { "type": "string" }, "result": { "$ref": "#/components/schemas/stock.LocationOverwriteResult" } }, "required": [ "receipt_id", "result" ], "type": "object" }, "type": "array" }, "next_cursor": { "type": "string" } }, "required": [ "items" ], "type": "object" }, "stock.LocationOverwriteInput": { "properties": { "depot_code": { "type": "string" }, "expected_balance_revision": { "description": "Use 0 only when the snapshot balance is null; otherwise use the observed positive revision.", "format": "int64", "minimum": 0, "type": "integer" }, "expected_stock_fence": { "description": "Required when a target supplies counted unit IDs or return count loss sources; use the stock_fence returned by the same snapshot.", "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "type": "string" }, "location_code": { "type": "string" }, "new_bucket_gains": { "description": "Optional gains for grains absent at the destination; the combined number of targets and gains cannot exceed 200.", "items": { "$ref": "#/components/schemas/stock.LocationOverwriteNewBucketGain" }, "maxItems": 200, "type": "array" }, "note": { "type": "string" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "reason_code": { "type": "string" }, "sku_code": { "type": "string" }, "targets": { "items": { "$ref": "#/components/schemas/stock.LocationOverwriteTarget" }, "maxItems": 200, "type": "array" } }, "required": [ "sku_code", "depot_code", "location_code", "expected_balance_revision", "on_hand_base_units", "targets", "reason_code", "idempotency_key" ], "type": "object" }, "stock.LocationOverwriteNewBucketGain": { "description": "Create a positive destination grain using a revision-fenced existing non-unit-tracked source bucket for the same SKU and lot. A valid lot/package without a source bucket is not supported.", "properties": { "expected_source_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "net_goods_cost": { "$ref": "#/components/schemas/internal_modules_netgoods.CostEvidence" }, "on_hand_base_units": { "format": "int64", "minimum": 1, "type": "integer" }, "source_bucket_id": { "type": "string" } }, "required": [ "source_bucket_id", "expected_source_revision", "on_hand_base_units", "net_goods_cost" ], "type": "object" }, "stock.LocationOverwriteResult": { "properties": { "actor": { "type": "string" }, "after_base_units": { "format": "int64", "type": "integer" }, "balance_revision": { "format": "int64", "type": "integer" }, "before_base_units": { "format": "int64", "type": "integer" }, "changes": { "items": { "$ref": "#/components/schemas/stock.LocationOverwriteChange" }, "type": "array" }, "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "note": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "reason_code": { "type": "string" }, "reconciled_count_references": { "description": "Existing count receipts used to reconcile a hold spanning locations.", "items": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "counted_at": { "format": "date-time", "type": "string" }, "counted_base_units": { "format": "int64", "type": "integer" }, "counted_by": { "type": "string" }, "receipt_key": { "type": "string" }, "released_base_units": { "description": "This reservation's released claim on the counted bucket; present with both reserved balance fields.", "format": "int64", "minimum": 0, "type": "integer" }, "reservation_id": { "type": "string" }, "reserved_after_base_units": { "description": "Bucket reserved balance after the atomic release of all named claims.", "format": "int64", "minimum": 0, "type": "integer" }, "reserved_before_base_units": { "description": "Bucket reserved balance before the atomic release of all named claims.", "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "reservation_id", "bucket_id", "bucket_revision", "counted_base_units", "receipt_key", "counted_at", "counted_by" ], "type": "object" }, "type": "array" }, "sku_code": { "type": "string" } }, "required": [ "sku_code", "depot_code", "location_code", "before_base_units", "after_base_units", "balance_revision", "actor", "reason_code", "occurred_at", "changes" ], "type": "object" }, "stock.LocationOverwriteSnapshot": { "properties": { "balance": { "anyOf": [ { "properties": { "assignment_id": { "type": "string" }, "available_base_units": { "format": "int64", "type": "integer" }, "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "reserved_base_units": { "format": "int64", "type": "integer" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" } }, "required": [ "assignment_id", "sku_code", "depot_code", "location_code", "on_hand_base_units", "reserved_base_units", "available_base_units", "revision" ], "type": "object" }, { "type": "null" } ], "description": "Null means no balance or buckets exist for the requested product and location at snapshot time." }, "buckets": { "items": { "properties": { "handling_unit": { "type": "string" }, "id": { "type": "string" }, "identity_status": { "description": "Present only for the unknown-identity physical return grain.", "enum": [ "unknown" ], "type": "string" }, "location": { "type": "object" }, "lot_id": { "type": "string" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "reserved_base_units": { "format": "int64", "type": "integer" }, "revision": { "format": "int64", "type": "integer" }, "sku_code": { "type": "string" }, "unit_tracked": { "description": "Actual owner tracking mode for this bucket.", "type": "boolean" } }, "required": [ "id", "sku_code", "location", "package_option", "handling_unit", "on_hand_base_units", "reserved_base_units", "revision", "unit_tracked" ], "type": "object" }, "type": "array" }, "stock_fence": { "description": "Revision of the SKU/depot candidate set; use it for every tracked-unit page and the count write.", "format": "int64", "minimum": 1, "type": "integer" } }, "required": [ "balance", "buckets", "stock_fence" ], "type": "object" }, "stock.LocationOverwriteTarget": { "properties": { "bucket_id": { "type": "string" }, "counted_unit_ids": { "description": "For a tracked bucket, provide every existing unit ID physically observed, including an explicit empty array when no existing units are present. Missing existing units and new labels may be recorded together; on_hand_base_units must equal observed existing units plus newly identified units in the package grain.", "items": { "type": "string" }, "type": "array" }, "deficit_selections": { "description": "Required when correcting a negative bucket to counted zero; use the current deficit-correction snapshot evidence.", "items": { "$ref": "#/components/schemas/stock.POSDeficitCorrectionSelection" }, "type": "array" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "net_goods_cost": { "$ref": "#/components/schemas/internal_modules_netgoods.CostEvidence", "description": "Optional evidence for the gross quantity added by new tracked unit labels; value the added units independently of the net count difference. Required for ordinary untracked gains." }, "new_unit_labels": { "description": "Physically observed distinct new unit labels in this existing lot and package grain; each creates one stock unit. Optional cost evidence may be supplied; otherwise the gain cost is unresolved.", "items": { "type": "string" }, "type": "array" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "return_count_loss_sources": { "description": "For a loss in an unknown-identity bucket, staff select genuine receiving IDs and positive quantities totaling the count loss. A sole remaining source can be inferred; multiple sources require selections and the snapshot stock fence.", "items": { "$ref": "#/components/schemas/inventory.UnknownReturnSource" }, "type": "array" } }, "required": [ "bucket_id", "expected_revision", "on_hand_base_units" ], "type": "object" }, "stock.POSDeficitCorrectionResult": { "properties": { "actor_id": { "type": "string" }, "after_revision": { "format": "int64", "type": "integer" }, "before_base_units": { "format": "int64", "type": "integer" }, "before_revision": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "cost_status": { "enum": [ "unresolved" ], "type": "string" }, "counted_base_units": { "enum": [ 0 ], "format": "int64", "type": "integer" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "occurred_at": { "format": "date-time", "type": "string" }, "reason": { "type": "string" }, "selections": { "items": { "$ref": "#/components/schemas/stock.POSDeficitCorrectionSelection" }, "type": "array" }, "sku_code": { "type": "string" } }, "required": [ "id", "bucket_id", "sku_code", "depot_code", "before_base_units", "counted_base_units", "before_revision", "after_revision", "actor_id", "reason", "selections", "cost_status", "occurred_at" ], "type": "object" }, "stock.POSDeficitCorrectionSelection": { "additionalProperties": false, "properties": { "base_units": { "format": "int64", "minimum": 1, "type": "integer" }, "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "obligation_id": { "type": "string" } }, "required": [ "obligation_id", "expected_revision", "base_units" ], "type": "object" }, "stock.POSSaleItemAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/stock.POSSaleItemEvidence" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "stock.POSSaleItemEvidence": { "properties": { "command_digest": { "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sale_id": { "type": "string" }, "settlement_id": { "type": "string" }, "sku_code": { "type": "string" }, "sold_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" } }, "required": [ "sale_id", "order_number", "fulfillment_generation", "settlement_id", "command_digest", "order_item_id", "sku_code", "package_option", "sold_composition" ], "type": "object" }, "stock.POSSaleItemQuery": { "properties": { "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "sale_id": { "type": "string" } }, "required": [ "order_number", "order_item_id" ], "type": "object" }, "stock.POSStockDeficit": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "bucket_id": { "type": "string" }, "lot_id": { "type": "string" }, "order_item_id": { "type": "string" }, "sku_code": { "type": "string" }, "tracking_status": { "enum": [ "tracked", "unknown" ], "type": "string" }, "unidentified": { "type": "boolean" } }, "required": [ "order_item_id", "sku_code", "bucket_id", "base_units", "unidentified", "tracking_status" ], "type": "object" }, "stock.POSStockSaleLine": { "properties": { "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "order_item_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "sku_code": { "type": "string" } }, "required": [ "order_item_id", "sku_code", "package_option", "composition" ], "type": "object" }, "stock.POSStockSaleMovement": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "cost_status": { "description": "Present for unallocated or unresolved-cost physical issues.", "enum": [ "valued", "unresolved" ], "type": "string" }, "deficit": { "type": "boolean" }, "movement_id": { "type": "string" }, "order_item_id": { "type": "string" } }, "required": [ "order_item_id", "movement_id", "base_units", "deficit" ], "type": "object" }, "stock.POSStockSaleReceipt": { "properties": { "command_digest": { "type": "string" }, "deficits": { "items": { "$ref": "#/components/schemas/stock.POSStockDeficit" }, "type": "array" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "movement_ids": { "items": { "type": "string" }, "type": "array" }, "movements": { "items": { "$ref": "#/components/schemas/stock.POSStockSaleMovement" }, "type": "array" }, "non_stock_order_item_ids": { "description": "Sorted lines settled with no movement and no deficit because their SKU is non-stock.", "items": { "type": "string" }, "type": "array" }, "operator_id": { "type": "string" }, "order_number": { "type": "string" }, "replayed": { "type": "boolean" }, "sale_id": { "type": "string" }, "settlement_id": { "type": "string" }, "sold_at": { "format": "date-time", "type": "string" } }, "required": [ "sale_id", "order_number", "fulfillment_generation", "settlement_id", "command_digest", "movement_ids", "movements", "deficits", "replayed", "sold_at", "operator_id" ], "type": "object" }, "stock.POSStockSaleReceiptAPIResponse": { "properties": { "data": { "$ref": "#/components/schemas/stock.POSStockSaleReceipt" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" }, "stock.POSStockSaleReceiptQuery": { "properties": { "depot_code": { "type": "string" }, "fulfillment_generation": { "format": "int64", "type": "integer" }, "lines": { "items": { "$ref": "#/components/schemas/stock.POSStockSaleLine" }, "type": "array" }, "market_code": { "type": "string" }, "operator_id": { "type": "string" }, "order_number": { "type": "string" }, "sale_id": { "type": "string" }, "sold_at": { "format": "date-time", "type": "string" } }, "required": [ "sale_id", "order_number", "fulfillment_generation", "market_code", "depot_code", "operator_id", "sold_at", "lines" ], "type": "object" }, "suppliers.BulkSupplierRequest": { "additionalProperties": false, "properties": { "patch": { "$ref": "#/components/schemas/bulk.ActivePatch" }, "supplier_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed, case-sensitive code; at most 128 UTF-8 bytes and no control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "supplier_codes", "patch" ], "type": "object" }, "suppliers.BulkSupplierResult": { "additionalProperties": false, "properties": { "supplier_codes": { "description": "1 to 100 explicit identifiers, unique after normalization. Request order is preserved; there is no all-records selector.", "items": { "description": "Trimmed, case-sensitive code; at most 128 UTF-8 bytes and no control characters.", "maxLength": 128, "minLength": 1, "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "updated_count": { "description": "Selected target count, including already-matching values.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "supplier_codes", "updated_count" ], "type": "object" }, "warehouse.CameraPreset": { "properties": { "fov": { "type": "number" }, "id": { "type": "string" }, "is_default": { "type": "boolean" }, "name": { "type": "string" }, "ortho_zoom": { "type": "number" }, "position": { "$ref": "#/components/schemas/geometry.Vector3" }, "projection": { "$ref": "#/components/schemas/warehouse_enums.CameraProjection" }, "target": { "$ref": "#/components/schemas/geometry.Vector3" } }, "type": "object" }, "warehouse.DepotRegion": { "properties": { "administrative_area_code": { "type": "string" }, "code": { "type": "string" }, "country_code": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "warehouse.InventoryDateMark": { "description": "Timezone-qualified best-before or expiry date printed on an inventory lot.\nKind, a nonzero timestamp and an explicit IANA timezone are all required\nwhen a date mark is supplied; the Local machine timezone is rejected. On\nreceipt routes the date mark is optional and past instants require direct\nreceipt into EXPIRY_HOLD.", "properties": { "date_mark_at": { "description": "RFC 3339 instant at which the date mark is reached, for example\n2027-03-31T13:00:00Z (midnight 1 April in Australia/Sydney). Must not be\nthe zero time. Stored at millisecond precision in UTC.", "format": "date-time", "type": "string" }, "kind": { "$ref": "#/components/schemas/warehouse_enums.InventoryDateMarkKind", "description": "BEST_BEFORE is a quality date: the product may still be safe after it.\nEXPIRY is a use-by / safety date: stock past it must not be sold." }, "timezone": { "description": "IANA time-zone name the date mark is printed in, for example\nAustralia/Sydney. Used to interpret the date mark as a local calendar\ndate. UTC offsets such as +10:00 and the Local zone are rejected.", "type": "string" } }, "required": [ "kind", "date_mark_at", "timezone" ], "type": "object" }, "warehouse.InventoryLot": { "description": "Inventory received or manufactured together. A lot carries no depot of its\nown; its stock sits in package-qualified buckets at depot locations.", "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "type": "string" }, "date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark", "description": "Omitted when the lot has no date mark." }, "deleted_at": { "description": "Shared audit field; lots are not deleted, so it is normally omitted.", "format": "date-time", "type": "string" }, "deleted_by": { "description": "Shared audit field; normally omitted.", "type": "string" }, "id": { "description": "Lot id (24-character hexadecimal ObjectId).", "type": "string" }, "manufactured_at": { "format": "date-time", "type": "string" }, "manufacturer_lot_code": { "type": "string" }, "received_at": { "format": "date-time", "type": "string" }, "sku_code": { "type": "string" }, "supplier_lot_code": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" }, "updated_by": { "description": "Actor of the last change, including the last date-mark edit.", "type": "string" } }, "required": [ "id", "sku_code", "received_at", "created_at", "updated_at" ], "type": "object" }, "warehouse.LayoutNode": { "properties": { "code": { "description": "human code, e.g. \"A-12-3-2\"", "type": "string" }, "color": { "description": "hex like \"#3b82f6\"", "type": "string" }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "id": { "type": "string" }, "is_active": { "type": "boolean" }, "layout_version": { "type": "integer" }, "location_code": { "description": "links a BIN node to a StockLocation", "type": "string" }, "model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "name": { "type": "string" }, "parent_code": { "type": "string" }, "path_codes": { "description": "ancestor codes from root to immediate parent", "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "shape": { "$ref": "#/components/schemas/warehouse_enums.ShapeType" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "storage": { "$ref": "#/components/schemas/classification_enums.StorageType" }, "transform": { "$ref": "#/components/schemas/geometry.Transform" }, "type": { "$ref": "#/components/schemas/warehouse_enums.LayoutNodeType" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "warehouse.LayoutWall": { "properties": { "color": { "type": "string" }, "end": { "$ref": "#/components/schemas/geometry.Vector3" }, "height_mm": { "type": "integer" }, "id": { "type": "string" }, "start": { "$ref": "#/components/schemas/geometry.Vector3" }, "thickness_mm": { "type": "integer" } }, "type": "object" }, "warehouse.ModelAsset": { "description": "optional GLB shell of the floor plan", "properties": { "anchor": { "$ref": "#/components/schemas/geometry.Vector3" }, "bounds": { "$ref": "#/components/schemas/geometry.BoundingBox" }, "format": { "$ref": "#/components/schemas/warehouse_enums.ModelFormat" }, "id": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/metadata.Metadata" }, "sha256": { "type": "string" }, "size_bytes": { "type": "integer" }, "url": { "type": "string" } }, "type": "object" }, "warehouse.QualityAssessment": { "properties": { "assessed_at": { "type": "string" }, "assessed_by": { "type": "string" }, "assessed_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "bucket_id": { "type": "string" }, "evidence_media_urls": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "note": { "type": "string" }, "previous_condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "previous_disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "reason_code": { "type": "string" }, "result_condition": { "$ref": "#/components/schemas/warehouse_enums.InventoryCondition" }, "result_disposition": { "$ref": "#/components/schemas/warehouse_enums.InventoryDisposition" }, "resulting_movement_ids": { "items": { "type": "string" }, "type": "array", "uniqueItems": false }, "sku_code": { "type": "string" }, "stock_unit_id": { "type": "string" } }, "type": "object" }, "warehouse.StockLocationCollectionEligibility": { "properties": { "collection_code": { "type": "string" }, "priority": { "type": "integer" }, "role": { "$ref": "#/components/schemas/warehouse_enums.StockLocationCollectionRole" } }, "type": "object" }, "warehouse.StockLocationRef": { "properties": { "depot_code": { "type": "string" }, "location_code": { "type": "string" } }, "type": "object" }, "warehouse.WMSDraft": { "properties": { "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "history": { "items": { "$ref": "#/components/schemas/security.HistoryEntry" }, "type": "array", "uniqueItems": false }, "id": { "type": "string" }, "item_count": { "type": "integer" }, "items": { "items": { "$ref": "#/components/schemas/warehouse.WMSDraftItem" }, "type": "array", "uniqueItems": false }, "note": { "type": "string" }, "operator": { "type": "string" }, "purchase_order_number": { "type": "string" }, "purchase_receipt_id": { "description": "PurchaseReceiptID links inbound WMS work to the procurement receipt.\nIt may be empty only while the draft remains unsubmitted.", "type": "string" }, "status": { "$ref": "#/components/schemas/warehouse_enums.WMSDraftStatus" }, "submitted_at": { "type": "string" }, "total_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "type": { "$ref": "#/components/schemas/warehouse_enums.WMSDraftType" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" } }, "type": "object" }, "warehouse.WMSDraftItem": { "properties": { "composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "id": { "type": "string" }, "location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "lot_id": { "type": "string" }, "observed_date_mark": { "$ref": "#/components/schemas/warehouse.InventoryDateMark" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_name": { "type": "string" }, "scanned_barcode": { "type": "string" }, "sku_code": { "type": "string" } }, "type": "object" }, "warehouse.WarehouseLayout": { "properties": { "background_color": { "type": "string" }, "cameras": { "items": { "$ref": "#/components/schemas/warehouse.CameraPreset" }, "type": "array", "uniqueItems": false }, "created_at": { "type": "string" }, "created_by": { "type": "string" }, "deleted_at": { "type": "string" }, "deleted_by": { "type": "string" }, "depot_code": { "type": "string" }, "floor_texture_url": { "type": "string" }, "grid_size_mm": { "type": "integer" }, "id": { "type": "string" }, "is_published": { "type": "boolean" }, "name": { "type": "string" }, "note": { "type": "string" }, "origin": { "$ref": "#/components/schemas/geometry.Vector3" }, "primary_model": { "$ref": "#/components/schemas/warehouse.ModelAsset" }, "published_at": { "type": "string" }, "size": { "$ref": "#/components/schemas/geometry.Size3D" }, "unit_scale": { "description": "scene units per metre, default 1.0", "type": "number" }, "up_axis": { "description": "\"Y\" (default for Three.js) or \"Z\"", "type": "string" }, "updated_at": { "type": "string" }, "updated_by": { "type": "string" }, "version": { "type": "integer" }, "walls": { "items": { "$ref": "#/components/schemas/warehouse.LayoutWall" }, "type": "array", "uniqueItems": false } }, "type": "object" }, "warehouse.WarehouseReceiptItem": { "properties": { "created_at": { "type": "string" }, "destination_bucket_id": { "type": "string" }, "destination_location": { "$ref": "#/components/schemas/warehouse.StockLocationRef" }, "expected_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "handling_unit": { "$ref": "#/components/schemas/packaging_enums.PackageHandlingUnit" }, "id": { "type": "string" }, "lot_id": { "type": "string" }, "package_option": { "$ref": "#/components/schemas/packaging.PackageOptionRef" }, "product_name": { "type": "string" }, "received_composition": { "$ref": "#/components/schemas/packaging.PackageCompositionSnapshot" }, "scanned_barcode": { "type": "string" }, "sku_code": { "type": "string" }, "storage_type": { "$ref": "#/components/schemas/classification_enums.StorageType" } }, "type": "object" }, "warehouse_enums.CameraProjection": { "enum": [ "perspective", "orthographic" ], "type": "string", "x-enum-varnames": [ "CameraPerspective", "CameraOrthographic" ] }, "warehouse_enums.DamageSaleTier": { "description": "Tier is the assessed damage band: tier_30, tier_50 or tier_80. It is\ndeclared by the approver, not derived from the reason code: the band is a\njudgement about how much condition was lost, and the reason code says\nonly what happened.", "enum": [ "tier_30", "tier_50", "tier_80" ], "type": "string", "x-enum-varnames": [ "DamageSaleTier30", "DamageSaleTier50", "DamageSaleTier80" ] }, "warehouse_enums.DamageStage": { "enum": [ "inbound", "picking", "packing", "storage" ], "type": "string", "x-enum-varnames": [ "DamageStageInbound", "DamageStagePicking", "DamageStagePacking", "DamageStageStorage" ] }, "warehouse_enums.InboundReceiptStatus": { "enum": [ "draft", "confirmed" ], "type": "string", "x-enum-varnames": [ "InboundReceiptStatusDraft", "InboundReceiptStatusConfirmed" ] }, "warehouse_enums.InventoryCondition": { "enum": [ "GOOD", "PACKAGING_DAMAGED_MINOR", "PACKAGING_DAMAGED_MAJOR", "PRODUCT_DAMAGED", "OPENED", "CONTAMINATED", "SPOILED" ], "type": "string", "x-enum-varnames": [ "InventoryConditionGood", "InventoryConditionPackagingDamagedMinor", "InventoryConditionPackagingDamagedMajor", "InventoryConditionProductDamaged", "InventoryConditionOpened", "InventoryConditionContaminated", "InventoryConditionSpoiled" ] }, "warehouse_enums.InventoryDateMarkKind": { "enum": [ "BEST_BEFORE", "EXPIRY" ], "type": "string", "x-enum-varnames": [ "InventoryDateMarkBestBefore", "InventoryDateMarkExpiry" ] }, "warehouse_enums.InventoryDisposition": { "enum": [ "STANDARD_SELLABLE", "REDUCED_SELLABLE", "QUALITY_HOLD", "QUARANTINED", "BLOCKED", "RECALLED", "RETURN_TO_VENDOR", "SCRAP" ], "type": "string", "x-enum-varnames": [ "InventoryDispositionStandardSellable", "InventoryDispositionReducedSellable", "InventoryDispositionQualityHold", "InventoryDispositionQuarantined", "InventoryDispositionBlocked", "InventoryDispositionRecalled", "InventoryDispositionReturnToVendor", "InventoryDispositionScrap" ] }, "warehouse_enums.LayoutNodeType": { "enum": [ "ZONE", "AISLE", "RACK", "SHELF", "BIN" ], "type": "string", "x-enum-varnames": [ "LayoutNodeZone", "LayoutNodeAisle", "LayoutNodeRack", "LayoutNodeShelf", "LayoutNodeBin" ] }, "warehouse_enums.ModelFormat": { "enum": [ "GLB", "GLTF", "OBJ", "FBX", "USDZ" ], "type": "string", "x-enum-varnames": [ "ModelFormatGLB", "ModelFormatGLTF", "ModelFormatOBJ", "ModelFormatFBX", "ModelFormatUSDZ" ] }, "warehouse_enums.OutboundShipmentStatus": { "enum": [ "packed", "dispatched", "delivered" ], "type": "string", "x-enum-varnames": [ "OutboundShipmentStatusPacked", "OutboundShipmentStatusDispatched", "OutboundShipmentStatusDelivered" ] }, "warehouse_enums.PackingDamageHandling": { "enum": [ "replace_from_stock", "short_ship_refund" ], "type": "string", "x-enum-varnames": [ "PackingDamageReplaceFromStock", "PackingDamageShortShipRefund" ] }, "warehouse_enums.PackingDiscrepancyKind": { "enum": [ "shortage", "overweight", "damaged", "pending" ], "type": "string", "x-enum-varnames": [ "PackingDiscrepancyKindShortage", "PackingDiscrepancyKindOverweight", "PackingDiscrepancyKindDamaged", "PackingDiscrepancyKindPending" ] }, "warehouse_enums.PackingDiscrepancyWithdrawalMethod": { "description": "How shortage units changed. command is an explicit shortage withdrawal; scan is packing a short line beyond its remaining shortage; reinstate records withdrawn units that never arrived as missing again.", "enum": [ "command", "scan", "reinstate" ], "type": "string", "x-enum-varnames": [ "PackingDiscrepancyWithdrawalMethodCommand", "PackingDiscrepancyWithdrawalMethodScan", "PackingDiscrepancyWithdrawalMethodReinstate" ] }, "warehouse_enums.ShapeType": { "enum": [ "BOX", "CYLINDER", "SPHERE", "PLANE", "CUSTOM" ], "type": "string", "x-enum-varnames": [ "ShapeBox", "ShapeCylinder", "ShapeSphere", "ShapePlane", "ShapeCustom" ] }, "warehouse_enums.StockLocationAccess": { "enum": [ "CUSTOMER_ACCESSIBLE", "STAFF_ONLY" ], "type": "string", "x-enum-varnames": [ "StockLocationAccessCustomerAccessible", "StockLocationAccessStaffOnly" ] }, "warehouse_enums.StockLocationCollectionMode": { "enum": [ "ALLOW_LIST", "UNRESTRICTED" ], "type": "string", "x-enum-varnames": [ "StockLocationCollectionAllowList", "StockLocationCollectionUnrestricted" ] }, "warehouse_enums.StockLocationCollectionRole": { "enum": [ "PRIMARY", "OVERFLOW" ], "type": "string", "x-enum-varnames": [ "StockLocationCollectionPrimary", "StockLocationCollectionOverflow" ] }, "warehouse_enums.StockLocationHandlingMode": { "enum": [ "EACH", "CASE", "MIXED" ], "type": "string", "x-enum-varnames": [ "StockLocationHandlingEach", "StockLocationHandlingCase", "StockLocationHandlingMixed" ] }, "warehouse_enums.StockLocationPurpose": { "enum": [ "STANDARD", "QUALITY_HOLD", "ONLINE_ORDER_STAGING", "EXPIRY_HOLD" ], "type": "string", "x-enum-varnames": [ "StockLocationPurposeStandard", "StockLocationPurposeQualityHold", "StockLocationPurposeOnlineOrderStaging", "StockLocationPurposeExpiryHold" ] }, "warehouse_enums.StockMovementType": { "enum": [ "RECEIPT", "TRANSFER", "STAGE", "UNSTAGE", "PACKAGE_CONVERSION", "SALE_COMMIT", "RETURN", "QUALITY_HOLD", "QUALITY_RELEASE", "QUALITY_REJECT", "ADJUSTMENT", "RETURN_TO_VENDOR", "SCRAP", "LOT_REASSIGNMENT" ], "type": "string", "x-enum-varnames": [ "StockMovementTypeReceipt", "StockMovementTypeTransfer", "StockMovementTypeStage", "StockMovementTypeUnstage", "StockMovementTypePackageConversion", "StockMovementTypeSaleCommit", "StockMovementTypeReturn", "StockMovementTypeQualityHold", "StockMovementTypeQualityRelease", "StockMovementTypeQualityReject", "StockMovementTypeAdjustment", "StockMovementTypeReturnToVendor", "StockMovementTypeScrap", "StockMovementTypeLotReassignment" ] }, "warehouse_enums.WMSDraftStatus": { "enum": [ "DRAFT", "SUBMITTED", "CANCELLED" ], "type": "string", "x-enum-varnames": [ "WMSDraftStatusDraft", "WMSDraftStatusSubmitted", "WMSDraftStatusCancelled" ] }, "warehouse_enums.WMSDraftType": { "enum": [ "INBOUND", "OUTBOUND" ], "type": "string", "x-enum-varnames": [ "WMSDraftTypeInbound", "WMSDraftTypeOutbound" ] }, "wishes.BulkRejectInput": { "additionalProperties": false, "properties": { "ids": { "items": { "pattern": "^[a-fA-F0-9]{24}$", "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array", "uniqueItems": true }, "reason": { "description": "Required nonblank reason after trimming, measured in Unicode characters.", "maxLength": 1000, "minLength": 1, "type": "string" } }, "required": [ "ids", "reason" ], "type": "object" }, "wishes.BulkRejectResponse": { "properties": { "data": { "properties": { "ids": { "items": { "type": "string" }, "type": "array" }, "updated_count": { "description": "Actual pending-to-rejected transitions, excluding already rejected records.", "maximum": 100, "minimum": 0, "type": "integer" } }, "required": [ "ids", "updated_count" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "description": "Backend-Identity-issued HS256 user JWT whose session_id is introspected with Identity on every protected request. Send as: `Bearer \u003ctoken\u003e`.", "in": "header", "name": "Authorization", "type": "apiKey" }, "PubSubPushOIDCAuth": { "bearerFormat": "JWT", "description": "Google-signed OIDC identity token whose audience and service-account email are verified for Pub/Sub push delivery.", "scheme": "bearer", "type": "http" }, "ServiceBearerAuth": { "bearerFormat": "JWT", "description": "Service access token issued by Backend-Identity's client-credentials flow (aud=internal, route-specific scope).", "scheme": "bearer", "type": "http" } } }, "externalDocs": { "description": "", "url": "" }, "info": { "contact": { "name": "Potato Mart Platform Team" }, "description": "Potato Mart Backend-Supply service.\nOwns product catalog data, SKUs, collections, category tags,\nsuppliers, depot geography, storage locations, ambient-storage inventory lots/\nbuckets/allocations/movements/reservations, picking, packing orders,\nshipments, purchasing, receipts, date-mark checks, forecasts,\nmedia metadata, import compliance, and operational\naudit logs. Every response uses the shared envelope\n`{ \"success\": bool, \"data\": ..., \"error\": ... }`.\nOrdinary product list, detail, barcode, brand-member, SKU-series-member,\nstorefront and batch reads return Supply-owned catalogue facts without\nrequesting Insights or enriching sales. Explicit sales-based selection and\nranking continue to use Insights; unavailable analysis never becomes zero sales.", "license": { "name": "Proprietary" }, "title": "Backend-Supply API", "version": "44.11.0" }, "openapi": "3.1.0", "paths": { "/audit-logs": { "get": { "parameters": [ { "description": "Filter by actor id", "in": "query", "name": "actor_id", "schema": { "type": "string" } }, { "description": "Filter by action name", "in": "query", "name": "action", "schema": { "type": "string" } }, { "description": "Filter by resource type", "in": "query", "name": "resource", "schema": { "type": "string" } }, { "description": "Filter by outcome", "in": "query", "name": "outcome", "schema": { "enum": [ "success", "failure", "denied" ], "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "RFC3339 lower bound on the audit timestamp", "in": "query", "name": "from", "schema": { "type": "string" } }, { "description": "RFC3339 upper bound on the audit timestamp", "in": "query", "name": "to", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List audit log entries", "tags": [ "audit" ] } }, "/base-acquisition-costs": { "get": { "description": "Super-admin only. Private global SKU/currency acquisition cost. Manual writes require a reason and establish an audited lock until explicit release. Invoice sources use net goods after all discounts and exclude all tax, freight and duty. Unavailable source remains unavailable; approved selling prices cannot be changed here.", "parameters": [ { "description": "Supply-owned SKU identity", "in": "query", "name": "sku_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List current base acquisition costs", "tags": [ "base-acquisition-costs" ] }, "put": { "description": "Super-admin only. Private global SKU/currency acquisition cost. Manual writes require a reason and establish an audited lock until explicit release. Invoice sources use net goods after all discounts and exclude all tax, freight and duty. Unavailable source remains unavailable; approved selling prices cannot be changed here.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_costs.RecordCostInput", "description": "Cost to record", "summary": "body" } ] } } }, "description": "Cost to record", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Overwrite the current base acquisition cost", "tags": [ "base-acquisition-costs" ] } }, "/base-acquisition-costs/{skuCode}/{currency}": { "get": { "description": "Super-admin only. Private global SKU/currency acquisition cost. Manual writes require a reason and establish an audited lock until explicit release. Invoice sources use net goods after all discounts and exclude all tax, freight and duty. Unavailable source remains unavailable; approved selling prices cannot be changed here.", "parameters": [ { "description": "Supply-owned SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "ISO 4217 currency code", "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read the current base acquisition cost for one SKU and currency", "tags": [ "base-acquisition-costs" ] } }, "/base-acquisition-costs/{skuCode}/{currency}/advice": { "get": { "description": "Super-admin authority required for the global SKU/currency acquisition aggregate.", "parameters": [ { "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_costs.AcquisitionAdvice" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read current acquisition cost and source history", "tags": [ "base-acquisition-costs" ] } }, "/base-acquisition-costs/{skuCode}/{currency}/manual-lock/release": { "post": { "description": "Super-admin authority required for the global SKU/currency acquisition aggregate.", "parameters": [ { "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_costs.ReleaseCostLockInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_costs.AcquisitionAdvice" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Release manual acquisition lock and select newest eligible source", "tags": [ "base-acquisition-costs" ] } }, "/base-acquisition-costs/{skuCode}/{currency}/package-advice": { "post": { "description": "superAdmin plus purchase.read required. Exact SKU/code/version must be active and effective now. Existing current cost is per base unit; checked multiplication yields a suggested selected-package amount. Missing/future/unavailable cost returns available:false without a cost. Manual PO cost remains explicit and editable; no cost update occurs.", "operationId": "packageAcquisitionCostAdvice", "parameters": [ { "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_costs.PackageAdviceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_modules_costs.PackageAdvice" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Qualified advice; available:false has no selected_package_cost" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input or exact package option absent, inactive or outside its effective window" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product SKU not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Catalogue capture changed; reload and retry" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Acquisition-cost store read failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Package authority unavailable or invalid package or acquisition authority facts" } }, "security": [ { "BearerAuth": [] } ], "summary": "Current acquisition-cost advice for an exact selected package", "tags": [ "costs" ] } }, "/brands": { "get": { "parameters": [ { "description": "Case-insensitive slug or localized-name search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.Brand], page: {...} }" } }, "security": [ { "BearerAuth": [] } ], "summary": "List canonical brands", "tags": [ "brands" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.BrandInput", "description": "New brand", "summary": "body" } ] } } }, "description": "New brand", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a canonical brand", "tags": [ "brands" ] } }, "/brands/{brand_id}": { "delete": { "parameters": [ { "description": "Brand ObjectId", "in": "path", "name": "brand_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No Content" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a canonical brand by Mongo identity", "tags": [ "brands" ] }, "get": { "parameters": [ { "description": "Brand ObjectId", "in": "path", "name": "brand_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a canonical brand by Mongo identity", "tags": [ "brands" ] }, "put": { "description": "Updates current canonical product references. slug is immutable\nand SKU masters contain no product snapshots.\n\nSend expected_updated_at (the brand's updated_at as read) to refuse a\nstale write with 409 CONFLICT. Send clear_logo true to remove the logo;\nsending both logo and clear_logo is a 400 VALIDATION_ERROR.", "parameters": [ { "description": "Brand ObjectId", "in": "path", "name": "brand_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.BrandInput", "description": "Brand patch", "summary": "body" } ] } } }, "description": "Brand patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR - invalid names, a changed slug, or both logo and clear_logo." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND - no brand with this id." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT - expected_updated_at is stale, the brand changed during the write, or the managed logo changed." } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a canonical brand by Mongo identity", "tags": [ "brands" ] } }, "/brands/{brand_id}/products": { "get": { "description": "Returns Supply-owned brand members without sales enrichment or an Insights dependency.", "parameters": [ { "description": "Brand ObjectId", "in": "path", "name": "brand_id", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [productView], page: {...} }" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "List staff product views for a canonical brand", "tags": [ "brands" ] } }, "/carrying-costs/receipts": { "post": { "description": "Only ACCEPTED units contribute; rejected units are recorded and contribute nothing. The cost components are declared separately and the carried goods cost is derived as gross minus recoverable tax minus freight minus duty: recoverable input tax is reclaimed rather than carried, and freight and duty stay on the supplier invoice as their own lines and are never blended into a unit cost. Supplier packs expand using the base-unit composition captured on the receipt, never today's catalogue. idempotency_key makes a retry a no-op inside the same transaction.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_costs.ReceiptCostInput", "description": "Accepted receipt to cost", "summary": "body" } ] } } }, "description": "Accepted receipt to cost", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Add an accepted goods receipt to a depot carrying cost", "tags": [ "carrying-costs" ] } }, "/carrying-costs/supplier-returns": { "post": { "description": "A return reverses the cost of the RECEIPT the goods came from, not the current average: removing the average would move the cost of other, cheaper stock onto the supplier's account. reverses_movement_id is therefore required, and unlinked, duplicate, excessive, and negative-stock reversals are all refused. Partial returns are split by cumulative position, so a sequence of them sums to exactly the original cost with no residue.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_costs.SupplierReturnInput", "description": "Supplier return to reverse", "summary": "body" } ] } } }, "description": "Supplier return to reverse", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reverse a receipt's carrying cost for a supplier return", "tags": [ "carrying-costs" ] } }, "/carrying-costs/transfers": { "post": { "description": "Cost moves at the SOURCE depot's current average and exactly that amount arrives at the destination in the same transaction, so the platform total is preserved to the minor unit rather than re-derived and rounded twice. An empty destination_depot_code issues the stock out instead. When a depot reaches zero base units its carrying cost settles to zero and its current average becomes absent.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_costs.TransferCostInput", "description": "Transfer or issue", "summary": "body" } ] } } }, "description": "Transfer or issue", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Move stock cost between depots, or out of stock", "tags": [ "carrying-costs" ] } }, "/carrying-costs/{skuCode}": { "get": { "description": "Discovery read for the currency-scoped aggregate. Names every currency in\nwhich a depot holds a stored carrying balance for this SKU, with the\ndepots holding each, so a caller can ask for the aggregate in each one\nwithout guessing currency keys. A balance that has drawn down to zero is\nstill listed. Carries no amounts. data = {sku_code, currencies:\n[{currency, depot_codes}]}, sorted by currency and depot code; an SKU\nwith no carrying balance answers an empty currencies list. This is a\nprivate operational value and never appears in a storefront, order,\ninvoice, or receipt response.", "parameters": [ { "description": "Supply-owned SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the currencies holding a carrying balance for one SKU", "tags": [ "carrying-costs" ] } }, "/carrying-costs/{skuCode}/{currency}": { "get": { "description": "Sums the depot balances holding this SKU IN THE REQUESTED CURRENCY and derives the weighted average from exact integers. Depots holding it in another currency are named in excluded_depots rather than folded in: two currencies do not share a minor-unit exponent, so their sum has no unit. This is a private operational value and never appears in a storefront, order, invoice, or receipt response.", "parameters": [ { "description": "Supply-owned SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "ISO 4217 currency code", "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Aggregate carrying cost for one SKU in one currency", "tags": [ "carrying-costs" ] } }, "/carrying-costs/{skuCode}/{currency}/{depotCode}": { "get": { "description": "The stored authority is the exact pair (total_carrying_cost_minor, base_unit_quantity); current_average_unit_cost is DERIVED from it and is absent at zero quantity, because the average of nothing is absent rather than zero.", "parameters": [ { "description": "Supply-owned SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "ISO 4217 currency code", "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } }, { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read one depot's carrying cost", "tags": [ "carrying-costs" ] } }, "/category-tags": { "get": { "description": "The catalogue of known merchandising tags (e.g. Hotpot, Fresh Food). Backs add-new / autocomplete in the product form and standalone tag management.", "parameters": [ { "description": "Exact collection slug", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.CategoryTag], page: {...} }. With collection, tags are ordered by that collection's display_order, then name, then code; without it, by name." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List merchandising tags", "tags": [ "categories" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/classification.CategoryTag", "description": "New category tag", "summary": "body" } ] } } }, "description": "New category tag", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a merchandising tag", "tags": [ "categories" ] } }, "/category-tags/{collectionSlug}/{categorySlug}": { "delete": { "parameters": [ { "description": "Collection slug", "in": "path", "name": "collectionSlug", "required": true, "schema": { "type": "string" } }, { "description": "Category tag slug", "in": "path", "name": "categorySlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a merchandising tag", "tags": [ "categories" ] }, "get": { "parameters": [ { "description": "Collection slug", "in": "path", "name": "collectionSlug", "required": true, "schema": { "type": "string" } }, { "description": "Category tag slug", "in": "path", "name": "categorySlug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a merchandising tag by collection/category slugs", "tags": [ "categories" ] }, "put": { "description": "The internal ID remains immutable because products reference it.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "collectionSlug", "required": true, "schema": { "type": "string" } }, { "description": "Category tag slug", "in": "path", "name": "categorySlug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/classification.CategoryTag", "description": "Category tag patch", "summary": "body" } ] } } }, "description": "Category tag patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a merchandising tag", "tags": [ "categories" ] } }, "/category-tags/{collectionSlug}/{categorySlug}/products": { "get": { "description": "Requires category.read. Returns every product in the category (not paginated) ordered by position ascending, with the current revision. Products newly tagged since the last save are appended at the end.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "collectionSlug", "required": true, "schema": { "type": "string" } }, { "description": "Category tag slug", "in": "path", "name": "categorySlug", "required": true, "schema": { "type": "string" } }, { "description": "Market for last30_days_net_units; defaults to the configured default market", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.categoryProductOrderAPIResponse" } } }, "description": "data = { revision, products: [categoryProductOrderItemView] }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown collection or category tag" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; category product ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a category's ordered products", "tags": [ "categories" ] } }, "/category-tags/{collectionSlug}/{categorySlug}/products/order": { "put": { "description": "Requires category.write. Replaces the whole product order of the category and increments its revision. The storefront lists the category in this order by default.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "collectionSlug", "required": true, "schema": { "type": "string" } }, { "description": "Category tag slug", "in": "path", "name": "categorySlug", "required": true, "schema": { "type": "string" } }, { "description": "Market for last30_days_net_units; defaults to the configured default market", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.CategoryProductOrderInput" } } }, "description": "Complete new order", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.categoryProductOrderAPIResponse" } } }, "description": "data = { revision (incremented), products: [categoryProductOrderItemView] }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; missing expected_revision or sku_codes, more than 2000 codes, a blank code, or a duplicate code (details.sku_code)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown collection or category tag" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "ORDER_SET_MISMATCH; sku_codes is not exactly the current product set (details.missing_sku_code or details.unexpected_sku_code)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; category product ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace a category's product order", "tags": [ "categories" ] } }, "/collections": { "get": { "description": "Collections are ordered by display_order, then name, then code (see GET /collections/order); sort_by overrides the default order.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.Collection], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List product collections", "tags": [ "collections" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/classification.Collection", "description": "New collection", "summary": "body" } ] } } }, "description": "New collection", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; invalid body, or slug \"order\" (reserved by /collections/order)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a product collection", "tags": [ "collections" ] } }, "/collections/order": { "get": { "description": "Requires collection.read. Every collection, with its category tags, in display order, and the order's revision. A collection created later is placed last; GET /collections and GET /storefront/collections list collections in this order by default.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.collectionOrderAPIResponse" } } }, "description": "data = { revision, items }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; the order changed while existing rows were being positioned; retry" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; taxonomy ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read the collection order", "tags": [ "collections" ] }, "put": { "description": "Requires collection.write. Replaces the whole collection order and increments its revision. The storefront lists collections in this order.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.CollectionOrderInput" } } }, "description": "Complete new order", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.collectionOrderAPIResponse" } } }, "description": "data = { revision (incremented), items } in the new order" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; missing expected_revision or collection_codes, more than 500 codes, a blank code, or a duplicate code (details.collection_code)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "ORDER_SET_MISMATCH; collection_codes is not exactly the current set (details.missing_code or details.unexpected_code)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; taxonomy ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace the collection order", "tags": [ "collections" ] } }, "/collections/{slug}": { "delete": { "description": "Returns 409 when products or category tags still reference the collection.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a product collection by slug", "tags": [ "collections" ] }, "get": { "parameters": [ { "description": "Collection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a product collection", "tags": [ "collections" ] }, "put": { "parameters": [ { "description": "Collection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/classification.Collection", "description": "Collection patch", "summary": "body" } ] } } }, "description": "Collection patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; invalid body, or a new slug \"order\" (reserved by /collections/order)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a product collection by slug", "tags": [ "collections" ] } }, "/collections/{slug}/category-tags/order": { "get": { "description": "Requires category.read. The collection's category tags in display order, and the order's revision. A tag created in, or moved into, the collection later is placed last.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.categoryTagOrderAPIResponse" } } }, "description": "data = { revision, items }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown collection" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; the order changed while existing rows were being positioned; retry" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; taxonomy ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a collection's category tag order", "tags": [ "categories" ] }, "put": { "description": "Requires category.write. Replaces the tag order of this collection only and increments its revision. Collection.category_tags, GET /category-tags?collection= and GET /storefront/collections list the tags in this order.", "parameters": [ { "description": "Collection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.CategoryTagOrderInput" } } }, "description": "Complete new order", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.categoryTagOrderAPIResponse" } } }, "description": "data = { revision (incremented), items } in the new order" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; missing expected_revision or category_tag_codes, more than 500 codes, a blank code, or a duplicate code (details.category_tag_code)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown collection" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "ORDER_SET_MISMATCH; category_tag_codes is not exactly the current set (details.missing_code or details.unexpected_code)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; taxonomy ordering is not wired" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace a collection's category tag order", "tags": [ "categories" ] } }, "/damage-reports": { "get": { "parameters": [ { "description": "Filter by product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by damage stage", "in": "query", "name": "stage", "schema": { "enum": [ "inbound", "picking", "packing", "storage" ], "type": "string" } }, { "description": "Filter by the originating reference id (e.g. receipt or pick task)", "in": "query", "name": "reference_id", "schema": { "type": "string" } }, { "description": "Filter by the reporting actor", "in": "query", "name": "reported_by", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List damage reports", "tags": [ "damage" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_damage.CreateInput", "description": "New damage report; reports are append-only and never patched or deleted", "summary": "body" } ] } } }, "description": "New damage report; reports are append-only and never patched or deleted", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a damage report", "tags": [ "damage" ] } }, "/damage-reports/{id}": { "get": { "parameters": [ { "description": "Damage report id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a damage report by id", "tags": [ "damage" ] } }, "/date-mark-checks": { "get": { "parameters": [ { "description": "Filter by alert level (OK, WARNING, CRITICAL, EXPIRED)", "in": "query", "name": "alert", "schema": { "type": "string" } }, { "description": "Filter by product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by lot ID", "in": "query", "name": "lot_id", "schema": { "type": "string" } }, { "description": "Filter by supplier lot code", "in": "query", "name": "supplier_lot_code", "schema": { "type": "string" } }, { "description": "Filter by date-mark kind", "in": "query", "name": "date_mark_kind", "schema": { "enum": [ "BEST_BEFORE", "USE_BY", "EXPIRY" ], "type": "string" } }, { "description": "Free-text search across product SKU code, lot ID, and supplier lot code", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []Check, page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List inventory date-mark checks", "tags": [ "date-marks" ] } }, "/date-mark-checks/run": { "post": { "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Run a date-mark threshold scan", "tags": [ "date-marks" ] } }, "/depot-coverage-rules/bulk": { "patch": { "description": "Requires depot.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateDepotCoverageRules", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depots.BulkCoverageRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/depots.BulkCoverageResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "depot.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_ids is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update depot coverage rule activation", "tags": [ "depot-coverage-rules" ] } }, "/depot-coverage-rules/{id}": { "delete": { "parameters": [ { "description": "Coverage rule ObjectID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.DeleteInput", "description": "Expected revision", "summary": "body" } ] } } }, "description": "Expected revision", "required": true }, "responses": { "204": { "description": "No Content" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete an individual coverage rule", "tags": [ "depots" ] }, "get": { "parameters": [ { "description": "Coverage rule ObjectID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an individual coverage rule", "tags": [ "depots" ] }, "patch": { "parameters": [ { "description": "Coverage rule ObjectID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.UpdateCoverageRuleInput", "description": "Revisioned patch", "summary": "body" } ] } } }, "description": "Revisioned patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update an individual coverage rule using its revision", "tags": [ "depots" ] } }, "/depot-markets": { "get": { "parameters": [ { "description": "Pricing-owned market code", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List depot to market associations", "tags": [ "depot-markets" ] }, "post": { "description": "A depot may serve several markets and a market several depots, so the association is stored explicitly and Depot.Country is never assumed to equal Market.Country. A market with no active association resolves no depots, and sale eligibility fails closed with DEPOT_MARKET_UNRESOLVED.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_listings.DepotMarketInput", "description": "Association to create", "summary": "body" } ] } } }, "description": "Association to create", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Associate a depot with a market", "tags": [ "depot-markets" ] } }, "/depot-markets/bulk": { "patch": { "description": "Requires depot.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateDepotMarkets", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/listings.BulkDepotMarketRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/listings.BulkDepotMarketResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "depot.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_ids is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update depot market activation", "tags": [ "depot-markets" ] } }, "/depot-markets/{id}": { "patch": { "parameters": [ { "description": "Association id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_listings.UpdateDepotMarketInput", "description": "Fields to change with the expected revision", "summary": "body" } ] } } }, "description": "Fields to change with the expected revision", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Edit a depot to market association", "tags": [ "depot-markets" ] } }, "/depot-regions": { "get": { "parameters": [ { "description": "Active status", "in": "query", "name": "active", "schema": { "type": "boolean" } }, { "description": "ISO country code", "in": "query", "name": "country", "schema": { "type": "string" } }, { "description": "Name or code search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Page size", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "List depot regions", "tags": [ "depots" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.RegionInput", "description": "Depot region", "summary": "body" } ] } } }, "description": "Depot region", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a depot region", "tags": [ "depots" ] } }, "/depot-regions/bulk": { "patch": { "description": "Requires depot.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateDepotRegions", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depots.BulkRegionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/depots.BulkRegionResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "depot.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_region_codes is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update depot region activation", "tags": [ "depot-regions" ] } }, "/depot-regions/{code}": { "delete": { "parameters": [ { "description": "Region code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.DeleteInput", "description": "Expected revision", "summary": "body" } ] } } }, "description": "Expected revision", "required": true }, "responses": { "204": { "description": "No Content" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete an unused depot region", "tags": [ "depots" ] }, "get": { "parameters": [ { "description": "Region code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a depot region", "tags": [ "depots" ] }, "patch": { "parameters": [ { "description": "Region code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.UpdateRegionInput", "description": "Patch", "summary": "body" } ] } } }, "description": "Patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a depot region", "tags": [ "depots" ] } }, "/depots": { "get": { "parameters": [ { "description": "Active status", "in": "query", "name": "active", "schema": { "type": "boolean" } }, { "description": "Public status", "in": "query", "name": "public", "schema": { "type": "boolean" } }, { "description": "Region code", "in": "query", "name": "region_code", "schema": { "type": "string" } }, { "description": "Search", "in": "query", "name": "q", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "List depots", "tags": [ "depots" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.DepotInput", "description": "Depot", "summary": "body" } ] } } }, "description": "Depot", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a depot and its six system locations", "tags": [ "depots" ] } }, "/depots/bulk": { "patch": { "description": "Requires depot.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateDepots", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depots.BulkDepotRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/depots.BulkDepotResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "depot.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_depot_codes is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update depot activation", "tags": [ "depots" ] } }, "/depots/{code}": { "delete": { "parameters": [ { "description": "Depot code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.DeleteInput", "description": "Expected revision", "summary": "body" } ] } } }, "description": "Expected revision", "required": true }, "responses": { "204": { "description": "No Content" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete an unused depot and its system locations", "tags": [ "depots" ] }, "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a depot", "tags": [ "depots" ] }, "patch": { "parameters": [ { "description": "Depot code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.UpdateDepotInput", "description": "Patch", "summary": "body" } ] } } }, "description": "Patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a depot", "tags": [ "depots" ] } }, "/depots/{code}/coverage-rules": { "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "List individual coverage rules for a depot", "tags": [ "depots" ] }, "post": { "parameters": [ { "description": "Depot code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.CoverageRuleInput", "description": "Coverage rule", "summary": "body" } ] } } }, "description": "Coverage rule", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an individual depot coverage rule", "tags": [ "depots" ] } }, "/esl/labels/{mac}": { "get": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "mac", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.Label" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read desired and confirmed label state", "tags": [ "e-tags" ] }, "put": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "mac", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_esl.BindInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.Label" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Bind explicit physical product slots", "tags": [ "e-tags" ] } }, "/esl/labels/{mac}/commands/{id}": { "get": { "description": "Admin authority and depot scope required. id is the command_code returned in label dispatch fences; acceptance and uncorrelated observations do not confirm rendering.", "parameters": [ { "in": "path", "name": "mac", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.Command" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read command acceptance, observations and attempts", "tags": [ "e-tags" ] } }, "/esl/labels/{mac}/reconcile-outcome": { "post": { "description": "Admin esl.light.override permission and depot scope required. The operator must verify the command is no longer in flight and provide evidence. This releases a fence without claiming a rendered revision.", "parameters": [ { "in": "path", "name": "mac", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_esl.ReconcileInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "properties": { "state": { "type": "string" } }, "required": [ "state" ], "type": "object" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Audit reconciliation of unresolved submission", "tags": [ "e-tags" ] } }, "/esl/labels/{mac}/refresh": { "post": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "mac", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.Label" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Resolve current catalogue and POS pricing evidence", "tags": [ "e-tags" ] } }, "/esl/stores/{code}": { "get": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.StoreConfig" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read E-Tag store configuration", "tags": [ "e-tags" ] }, "put": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_esl.ConfigureInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_esl.StoreConfig" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revise E-Tag store configuration", "tags": [ "e-tags" ] } }, "/esl/tasks/packing/{id}/focus": { "post": { "description": "Existing packing.write permission, task operator authority and geographic scope required. A contested physical tag returns advisory busy. An override additionally requires an admin role, esl.light.override permission and an audited reason. Intent is persisted before bounded dispatch; pending does not mean a physical light succeeded.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_esl.FocusInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_esl.FocusResult" }, "type": "array" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Request finite lighting for actual task allocations", "tags": [ "e-tags" ] } }, "/esl/tasks/picking/{id}/focus": { "post": { "description": "Existing picking.write permission, task operator authority and geographic scope required. A contested physical tag returns advisory busy. An override additionally requires an admin role, esl.light.override permission and an audited reason. Intent is persisted before bounded dispatch; pending does not mean a physical light succeeded.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_esl.FocusInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_esl.FocusResult" }, "type": "array" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Request finite lighting for actual task allocations", "tags": [ "e-tags" ] } }, "/expiry/expired-lots": { "get": { "description": "EXPIRY marks at or before the current instant, including stock already in holds. Staff geography is applied using authoritative depot masters. BEST_BEFORE and undated lots are not included. Use stock.transfers with exact bucket revision/composition to move unreserved quantities.", "parameters": [ { "description": "Filter by normalized SKU code", "in": "query", "name": "sku_code", "required": false, "schema": { "type": "string" } }, { "description": "Filter by depot within staff geography", "in": "query", "name": "depot_code", "required": false, "schema": { "type": "string" } }, { "description": "Page number", "in": "query", "name": "page", "required": false, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Rows per page", "in": "query", "name": "page_size", "required": false, "schema": { "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Fixed oldest-expired-first sort", "in": "query", "name": "sort_by", "required": false, "schema": { "enum": [ "date_mark_at" ], "type": "string" } }, { "description": "Only ascending order is supported", "in": "query", "name": "order", "required": false, "schema": { "enum": [ "asc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_expiry.ExpiredLotPage" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Internal failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List positive expired inventory buckets oldest first", "tags": [ "expiry" ] } }, "/forecasts": { "get": { "parameters": [ { "description": "Filter by alert level (OK, WARNING, CRITICAL, EXPIRED)", "in": "query", "name": "alert_level", "schema": { "type": "string" } }, { "description": "Filter by product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Filter by sales channel", "in": "query", "name": "channel", "schema": { "type": "string" } }, { "description": "Filter by IANA timezone", "in": "query", "name": "timezone", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []analytics.SKUDemandForecast, page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown alert_level" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List SKU demand forecasts", "tags": [ "forecasts" ] } }, "/forecasts/bulk/clear-overrides": { "post": { "description": "Requires forecast.write and the existing authenticated staff command boundary. Release staff overrides while retaining forecast values and last producer timestamp. Selected streams use the full SKU/depot/channel/timezone business key. Already-clear records retain individual command audit semantics. Strict JSON body up to 128 KiB and 1-100 unique normalized targets. Current records and all writes share one required Mongo transaction. Missing or failed targets abort every write. Missing targets return 404; error.details.missing_forecasts is a JSON-encoded array string. No provider calls, product conversion, stock mutation or producer result calculation is performed. These modules retain existing staff visibility; no additional row geography predicate is introduced.", "operationId": "bulkClearForecastOverrides", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/forecasts.BulkClearInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/forecasts.BulkClearResponse" } } }, "description": "Atomic completion; normalized selection in request order." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid forecast key or strict JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication or actor required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Required permission denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Selected target missing" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Ineligible state or concurrent change" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Body exceeds 128 KiB" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Result uncertain; refetch before retrying" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Clear selected forecast overrides", "tags": [ "forecasts" ] } }, "/forecasts/{skuCode}": { "get": { "parameters": [ { "description": "SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "required": true, "schema": { "type": "string" } }, { "description": "Sales channel", "in": "query", "name": "channel", "required": true, "schema": { "type": "string" } }, { "description": "IANA timezone", "in": "query", "name": "timezone", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a SKU demand forecast", "tags": [ "forecasts" ] }, "put": { "parameters": [ { "description": "SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_forecasts.UpsertInput", "description": "Forecast row", "summary": "body" } ] } } }, "description": "Forecast row", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Write a staff override for a SKU demand forecast", "tags": [ "forecasts" ] } }, "/forecasts/{skuCode}/override": { "delete": { "parameters": [ { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "required": true, "schema": { "type": "string" } }, { "description": "Sales channel", "in": "query", "name": "channel", "required": true, "schema": { "type": "string" } }, { "description": "IANA timezone", "in": "query", "name": "timezone", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Clear a staff forecast override without changing its values", "tags": [ "forecasts" ] } }, "/import-compliance/capabilities": { "get": { "description": "Requires countryAdmin or superAdmin and purchase.read. Reports availability of Document AI, Vertex AI, Cloud Tasks, TIPO, and artifact rendering; optional providers report unavailable instead of silently falling back.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = Capabilities" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get import-compliance integration capabilities", "tags": [ "import-compliance" ] } }, "/import-compliance/catalogues/search": { "get": { "description": "Requires countryAdmin or superAdmin and purchase.read.", "parameters": [ { "description": "Jurisdiction (TW or AU)", "in": "query", "name": "jurisdiction", "required": true, "schema": { "type": "string" } }, { "description": "Catalogue version id (defaults to the current promoted version)", "in": "query", "name": "version_id", "schema": { "type": "string" } }, { "description": "Free-text search over code and description", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Search entries within a tariff catalogue version", "tags": [ "import-compliance" ] } }, "/import-compliance/catalogues/versions": { "get": { "description": "Requires countryAdmin or superAdmin and purchase.read.", "parameters": [ { "description": "Jurisdiction filter (TW or AU)", "in": "query", "name": "jurisdiction", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List tariff catalogue versions", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Filter by review state (draft, in_review, approved, rejected, archived)", "in": "query", "name": "state", "schema": { "type": "string" } }, { "description": "Filter by purchase-order number", "in": "query", "name": "purchase_order_number", "schema": { "type": "string" } }, { "description": "Filter by SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by variant code", "in": "query", "name": "variant_code", "schema": { "type": "string" } }, { "description": "Filter by consignment identifier", "in": "query", "name": "consignment_identifier", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Sort field", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order (asc or desc)", "in": "query", "name": "order", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List manufacturer declarations", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Snapshots the referenced purchase order and pins the latest approved import-settings revision; Idempotency-Key is required.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ManufacturerDeclaration", "description": "Initial declaration draft", "summary": "body" } ] } } }, "description": "Initial declaration draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Idempotent replay of a prior create" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Purchase-order service is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create the first manufacturer-declaration draft revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the latest manufacturer-declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/artifacts": { "get": { "description": "Requires media.read plus purchase.read (declarations, tariff assessments, RFIs) or product.read (labels).", "parameters": [ { "description": "Resource id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number filter (defaults to all revisions when omitted)", "in": "query", "name": "revision", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List rendered artifacts for a declaration, label, tariff assessment, or RFI", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all revisions of a manufacturer declaration", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Idempotency-Key is required.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fork a new declaration draft from the current approved, rejected, or archived revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a specific manufacturer-declaration revision", "tags": [ "import-compliance" ] }, "patch": { "description": "Requires purchase.write. If-Match must equal the current revision's ETag.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ManufacturerDeclaration", "description": "Updated declaration draft", "summary": "body" } ] } } }, "description": "Updated declaration draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}/approve": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a manufacturer-declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}/archive": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a manufacturer-declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}/refresh-purchase-order": { "post": { "description": "Requires purchase.write. Only a draft declaration can refresh its purchase order; If-Match must equal the current revision's ETag.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Only a draft declaration can refresh its purchase order" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Purchase-order service is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Re-snapshot a draft declaration from its live purchase order", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}/reject": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a manufacturer-declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/declarations/{id}/revisions/{revision}/submit": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Declaration id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a manufacturer-declaration revision", "tags": [ "import-compliance" ] } }, "/import-compliance/jobs": { "post": { "description": "Requires countryAdmin or superAdmin, plus purchase.write or product.write depending on the target resource type. Idempotency-Key is required; each job kind has its own input validation.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.CreateJobInput", "description": "Job request", "summary": "body" } ] } } }, "description": "Job request", "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Accepted" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Cloud Tasks or the required AI/search provider is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an automation job (OCR, structured proposal, catalogue refresh, trademark search, or artifact render)", "tags": [ "import-compliance" ] } }, "/import-compliance/jobs/{id}": { "get": { "description": "Requires countryAdmin or superAdmin, plus purchase.write or product.write depending on the job's resource type.", "parameters": [ { "description": "Job id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an automation job", "tags": [ "import-compliance" ] } }, "/import-compliance/jobs/{id}/cancel": { "post": { "description": "Requires countryAdmin or superAdmin, plus purchase.write or product.write depending on the job's resource type.", "parameters": [ { "description": "Job id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Job is not in a cancellable state" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel a queued or running automation job", "tags": [ "import-compliance" ] } }, "/import-compliance/jobs/{id}/retry": { "post": { "description": "Requires countryAdmin or superAdmin, plus purchase.write or product.write depending on the job's resource type. Requires an available Cloud Tasks dispatcher.", "parameters": [ { "description": "Job id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Accepted" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Job is not in a retryable state" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Cloud Tasks is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Retry a failed or dispatch-failed automation job", "tags": [ "import-compliance" ] } }, "/import-compliance/labels": { "get": { "description": "Requires product.read.", "parameters": [ { "description": "Filter by review state (draft, in_review, approved, rejected, archived)", "in": "query", "name": "state", "schema": { "type": "string" } }, { "description": "Filter by purchase-order number", "in": "query", "name": "purchase_order_number", "schema": { "type": "string" } }, { "description": "Filter by SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by variant code", "in": "query", "name": "variant_code", "schema": { "type": "string" } }, { "description": "Filter by consignment identifier", "in": "query", "name": "consignment_identifier", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Sort field", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order (asc or desc)", "in": "query", "name": "order", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List label masters", "tags": [ "import-compliance" ] }, "post": { "description": "Requires product.write. Prefills catalogue-derived defaults for any field left blank; Idempotency-Key is required.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.LabelMaster", "description": "Initial label draft", "summary": "body" } ] } } }, "description": "Initial label draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Idempotent replay of a prior create" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product catalogue is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create the first label-master draft revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/prefill/{sku}": { "get": { "description": "Requires product.read. Returns catalogue-derived defaults (names, weight, dimensions, barcode) for a new label without persisting anything.", "parameters": [ { "description": "SKU code", "in": "path", "name": "sku", "required": true, "schema": { "type": "string" } }, { "description": "Market code", "in": "query", "name": "market_code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = contract.LabelMaster" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "market_code is required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Listing or Pricing evidence is inactive, ambiguous, stale, or inconsistent" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Catalogue, Listings, or Pricing evidence is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Prefill a label draft from the product catalogue", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}": { "get": { "description": "Requires product.read.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the latest label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/artifacts": { "get": { "description": "Requires media.read plus purchase.read (declarations, tariff assessments, RFIs) or product.read (labels).", "parameters": [ { "description": "Resource id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number filter (defaults to all revisions when omitted)", "in": "query", "name": "revision", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List rendered artifacts for a declaration, label, tariff assessment, or RFI", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions": { "get": { "description": "Requires product.read.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all revisions of a label master", "tags": [ "import-compliance" ] }, "post": { "description": "Requires product.write. Idempotency-Key is required.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fork a new label draft from the current approved, rejected, or archived revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions/{revision}": { "get": { "description": "Requires product.read.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a specific label-master revision", "tags": [ "import-compliance" ] }, "patch": { "description": "Requires product.write. If-Match must equal the current revision's ETag.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.LabelMaster", "description": "Updated label draft", "summary": "body" } ] } } }, "description": "Updated label draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions/{revision}/approve": { "post": { "description": "Requires product.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions/{revision}/archive": { "post": { "description": "Requires product.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions/{revision}/reject": { "post": { "description": "Requires product.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/labels/{id}/revisions/{revision}/submit": { "post": { "description": "Requires product.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "Label id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a label-master revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Filter by review state (draft, in_review, approved, rejected, archived)", "in": "query", "name": "state", "schema": { "type": "string" } }, { "description": "Filter by purchase-order number", "in": "query", "name": "purchase_order_number", "schema": { "type": "string" } }, { "description": "Filter by SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by variant code", "in": "query", "name": "variant_code", "schema": { "type": "string" } }, { "description": "Filter by consignment identifier", "in": "query", "name": "consignment_identifier", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Sort field", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order (asc or desc)", "in": "query", "name": "order", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List RFI (biosecurity inspection) records", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Idempotency-Key is required. Save an RFI draft with manually entered or Places-selected inspection-address fields. No external address validation, confirmation result, Place ID, Australian state or four-digit postcode is required to save. A supplied nonempty address still requires line1, locality and country code, with existing coordinate bounds. Australian inspection-address requirements are checked on submit and approve; saving a draft does not establish submission eligibility. Existing role/country scope, idempotency and review-state rules remain unchanged.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.RFIRecord", "description": "Initial RFI draft", "summary": "body" } ] } } }, "description": "Initial RFI draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Idempotent replay of a prior create" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create the first RFI draft revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the latest RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/artifacts": { "get": { "description": "Requires media.read plus purchase.read (declarations, tariff assessments, RFIs) or product.read (labels).", "parameters": [ { "description": "Resource id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number filter (defaults to all revisions when omitted)", "in": "query", "name": "revision", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List rendered artifacts for a declaration, label, tariff assessment, or RFI", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all revisions of an RFI", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Idempotency-Key is required.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fork a new RFI draft from the current approved, rejected, or archived revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a specific RFI revision", "tags": [ "import-compliance" ] }, "patch": { "description": "Requires purchase.write. If-Match must equal the current revision's ETag. Submission events and the current submission state cannot be edited directly. Update draft inspection-address fields using structural persistence checks only. No provider verification or confirmation is required. Australian state/postcode requirements remain on submit and approve, not draft save. Existing immutable snapshot, role/country scope and draft-state rules apply.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.RFIRecord", "description": "Updated RFI draft", "summary": "body" } ] } } }, "description": "Updated RFI draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}/approve": { "post": { "description": "Requires purchase.write; approve and reject additionally require countryAdmin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job. Requires a complete Australian inspection address under existing domain rules, including AU country, Australian subdivision and four-digit postcode. Draft persistence does not imply eligibility. This is a local business check, not an external address-verification call or confirmation workflow.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject an RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}/archive": { "post": { "description": "Requires purchase.write; approve and reject additionally require countryAdmin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject an RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}/reject": { "post": { "description": "Requires purchase.write; approve and reject additionally require countryAdmin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject an RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}/submission-events": { "post": { "description": "Requires purchase.write. If-Match must equal the current revision's ETag; the RFI must be approved and the event must be a valid forward transition from the current submission state. Submitted and confirmed events require an external_reference.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.RFIExternalEvent", "description": "External submission event", "summary": "body" } ] } } }, "description": "External submission event", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "RFI is not approved, or the event is not a valid transition from the current submission state" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Append an external biosecurity-portal submission event to an approved RFI", "tags": [ "import-compliance" ] } }, "/import-compliance/rfis/{id}/revisions/{revision}/submit": { "post": { "description": "Requires purchase.write; approve and reject additionally require countryAdmin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval queues a best-effort artifact-render job. Requires a complete Australian inspection address under existing domain rules, including AU country, Australian subdivision and four-digit postcode. Draft persistence does not imply eligibility. This is a local business check, not an external address-verification call or confirmation workflow.", "parameters": [ { "description": "RFI id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject an RFI revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings": { "get": { "description": "Requires purchase.read. AI and external-provider outputs remain proposals until an explicit draft update and human approval.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = SettingsView{active,draft,history}" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get active, draft, and historical import-settings revisions", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/cost-preview": { "post": { "description": "Requires purchase.read. Evaluates configured import-cost formulas against the supplied settings without persisting anything.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ImportSettings", "description": "Settings values to preview", "summary": "body" } ] } } }, "description": "Settings values to preview", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = ImportCostPreview" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Calculate an import-cost preview with fixed-point arithmetic", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions": { "post": { "description": "Requires purchase.write. Idempotency-Key is required; replaying the same key with an identical request body returns the original revision instead of creating a new one.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ImportSettings", "description": "Initial settings draft", "summary": "body" } ] } } }, "description": "Initial settings draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Idempotent replay of a prior create" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create the first import-settings draft revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/fork": { "post": { "description": "Requires purchase.write. Idempotency-Key is required.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fork a new settings draft from the current approved or rejected revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/{revision}": { "patch": { "description": "Requires purchase.write. If-Match must equal the current revision's ETag.", "parameters": [ { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ImportSettings", "description": "Updated settings draft", "summary": "body" } ] } } }, "description": "Updated settings draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft settings revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/{revision}/approve": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject.", "parameters": [ { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a settings revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/{revision}/archive": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject.", "parameters": [ { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a settings revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/{revision}/reject": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject.", "parameters": [ { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a settings revision", "tags": [ "import-compliance" ] } }, "/import-compliance/settings/revisions/{revision}/submit": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject.", "parameters": [ { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a settings revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Filter by review state (draft, in_review, approved, rejected, archived)", "in": "query", "name": "state", "schema": { "type": "string" } }, { "description": "Filter by purchase-order number", "in": "query", "name": "purchase_order_number", "schema": { "type": "string" } }, { "description": "Filter by SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by variant code", "in": "query", "name": "variant_code", "schema": { "type": "string" } }, { "description": "Filter by consignment identifier", "in": "query", "name": "consignment_identifier", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Sort field", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "Sort order (asc or desc)", "in": "query", "name": "order", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List tariff assessments", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Snapshots the referenced purchase order; Idempotency-Key is required.", "parameters": [ { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.TariffAssessment", "description": "Initial assessment draft", "summary": "body" } ] } } }, "description": "Initial assessment draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Idempotent replay of a prior create" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Purchase-order service is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create the first tariff-assessment draft revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the latest tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/artifacts": { "get": { "description": "Requires media.read plus purchase.read (declarations, tariff assessments, RFIs) or product.read (labels).", "parameters": [ { "description": "Resource id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number filter (defaults to all revisions when omitted)", "in": "query", "name": "revision", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List rendered artifacts for a declaration, label, tariff assessment, or RFI", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List all revisions of a tariff assessment", "tags": [ "import-compliance" ] }, "post": { "description": "Requires purchase.write. Idempotency-Key is required.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Idempotency key (max 200 visible ASCII characters)", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Fork a new tariff-assessment draft from the current approved, rejected, or archived revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions/{revision}": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a specific tariff-assessment revision", "tags": [ "import-compliance" ] }, "patch": { "description": "Requires purchase.write. If-Match must equal the current revision's ETag.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/compliance.TariffAssessment", "description": "Updated assessment draft", "summary": "body" } ] } } }, "description": "Updated assessment draft", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions/{revision}/approve": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval publishes new tariff-profile revisions transactionally and queues a best-effort artifact-render job.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action, or a duplicate SKU/jurisdiction profile row" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions/{revision}/archive": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval publishes new tariff-profile revisions transactionally and queues a best-effort artifact-render job.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action, or a duplicate SKU/jurisdiction profile row" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions/{revision}/reject": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval publishes new tariff-profile revisions transactionally and queues a best-effort artifact-render job.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action, or a duplicate SKU/jurisdiction profile row" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/revisions/{revision}/submit": { "post": { "description": "Requires purchase.write; approve and reject additionally require admin or superAdmin. If-Match must equal the current revision's ETag. A reason is required to reject. Approval publishes new tariff-profile revisions transactionally and queues a best-effort artifact-render job.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Revision number", "in": "path", "name": "revision", "required": true, "schema": { "type": "integer" } }, { "description": "Strong ETag returned by the current revision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_importcompliance.ActionInput", "description": "Optional reason", "summary": "body" } ] } } }, "description": "Optional reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision is not in a state that allows this action, or a duplicate SKU/jurisdiction profile row" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match does not match the current revision" }, "428": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "If-Match header is required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit, archive, approve, or reject a tariff-assessment revision", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/assessments/{id}/trademark-evidence": { "get": { "description": "Requires purchase.read.", "parameters": [ { "description": "Assessment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List trademark-search evidence collected for a tariff assessment", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/profiles": { "get": { "description": "Requires purchase.read. Profiles are the durable Taiwan/Australia classifications published when a tariff assessment is approved.", "parameters": [ { "description": "SKU code (query form, used when sku is not in the path)", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List published tariff classification profiles", "tags": [ "import-compliance" ] } }, "/import-compliance/tariffs/profiles/{sku}": { "get": { "description": "Requires purchase.read. Profiles are the durable Taiwan/Australia classifications published when a tariff assessment is approved.", "parameters": [ { "description": "SKU code (path form)", "in": "path", "name": "sku", "required": true, "schema": { "type": "string" } }, { "description": "SKU code (query form, used when sku is not in the path)", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List published tariff classification profiles", "tags": [ "import-compliance" ] } }, "/inbound-receipts": { "get": { "parameters": [ { "description": "Filter by depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Filter by reference (e.g. purchase-order number)", "in": "query", "name": "reference", "schema": { "type": "string" } }, { "description": "Filter by supplier code (case-insensitive substring)", "in": "query", "name": "supplier_code", "schema": { "type": "string" } }, { "description": "Filter by operator", "in": "query", "name": "operator", "schema": { "type": "string" } }, { "description": "Filter by status (DRAFT, CONFIRMED)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []warehouse.WarehouseReceipt, page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List inbound receipts", "tags": [ "inbound" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_inbound.CreateInput", "description": "New inbound receipt (DRAFT)", "summary": "body" } ] } } }, "description": "New inbound receipt (DRAFT)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an inbound receipt", "tags": [ "inbound" ] } }, "/inbound-receipts/{id}": { "get": { "parameters": [ { "description": "Inbound receipt ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an inbound receipt", "tags": [ "inbound" ] } }, "/inbound-receipts/{id}/items": { "put": { "parameters": [ { "description": "Inbound receipt ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_inbound.UpdateItemsInput", "description": "Full replacement item list", "summary": "body" } ] } } }, "description": "Full replacement item list", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only DRAFT receipts can be edited, or status changed concurrently" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace inbound receipt items", "tags": [ "inbound" ] } }, "/inbound-receipts/{id}/status": { "post": { "parameters": [ { "description": "Inbound receipt ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_inbound.TransitionInput", "description": "Target status", "summary": "body" } ] } } }, "description": "Target status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown status, transition not allowed, or status changed concurrently" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Transition inbound receipt status", "tags": [ "inbound" ] } }, "/me/favourite-lists": { "get": { "description": "Retail customers list their own lists. Wholesale members require favourite_lists.view_org and share their organisation's lists.", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = array of favouritecontract.FavouriteList" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the authenticated owner's favourite lists", "tags": [ "favourite-lists" ] }, "post": { "description": "Maximum five per owner. A blank name allocates the lowest unused List-1 through List-5 slot; system List-n names are reserved.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_favouritelists.CreateInput", "description": "New favourite list", "summary": "body" } ] } } }, "description": "New favourite list", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "validation, list limit, or name conflict" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a favourite list", "tags": [ "favourite-lists" ] } }, "/me/favourite-lists/{listId}": { "delete": { "parameters": [ { "description": "Favourite list ID", "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { deleted: true }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "not found for this owner" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete one owned favourite list", "tags": [ "favourite-lists" ] }, "get": { "parameters": [ { "description": "Favourite list ID", "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "not found for this owner" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get one owned favourite list", "tags": [ "favourite-lists" ] }, "patch": { "parameters": [ { "description": "Favourite list ID", "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_favouritelists.UpdateInput", "description": "New name", "summary": "body" } ] } } }, "description": "New name", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "validation or name conflict" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "not found for this owner" } }, "security": [ { "BearerAuth": [] } ], "summary": "Rename one owned favourite list", "tags": [ "favourite-lists" ] } }, "/me/favourite-lists/{listId}/products/{skuCode}": { "delete": { "parameters": [ { "description": "Favourite list ID", "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } }, { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "list not found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Idempotently remove a product from a favourite list", "tags": [ "favourite-lists" ] }, "put": { "description": "Maximum 200 product memberships per list. A product may belong to multiple lists.", "parameters": [ { "description": "Favourite list ID", "in": "path", "name": "listId", "required": true, "schema": { "type": "string" } }, { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "product limit reached" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "list or product not found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Idempotently add a product to a favourite list", "tags": [ "favourite-lists" ] } }, "/me/restock-alerts": { "get": { "description": "Lists the caller's ACTIVE restock alerts only, newest first, at most 200. Fired and cancelled alerts are not listed. stock_state is the market's current in-stock baseline (unknown before the first observation). Retail customer tokens only; gated by STOREFRONT_RESTOCK_ALERTS_ENABLED.", "parameters": [ { "description": "Optional market code filter (for example AU-VIC)", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restockalerts.AlertList" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Retail customer account required" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "STOREFRONT_RESTOCK_ALERTS_ENABLED is off, or a dependency is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List my active restock alerts", "tags": [ "restock-alerts" ] } }, "/me/restock-alerts/{skuCode}": { "delete": { "description": "Cancels the caller's active alert for the SKU in the market. Idempotent; answers 204 whether or not an alert existed.", "parameters": [ { "description": "Product SKU code; the raw path segment is decoded once, so an encoded \"/\" or \"+\" is part of the code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Market code (for example AU-VIC)", "in": "query", "name": "market_code", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Cancelled, or nothing to cancel" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "market_code is required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Retail customer account required" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "STOREFRONT_RESTOCK_ALERTS_ENABLED is off, or a dependency is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Unsubscribe from a restock alert", "tags": [ "restock-alerts" ] }, "put": { "description": "Subscribes the caller to one alert when the SKU returns to stock in the market. One alert fires per subscription, and the subscription then clears; unfired subscriptions expire 180 days after subscribing. A return within 30 minutes of selling out is debounced and does not fire. At most 100 active alerts per customer per market. Idempotent: a repeat PUT answers 200 with the existing active alert; a new alert answers 201. A SKU that is currently in stock may still be subscribed.", "parameters": [ { "description": "Product SKU code; the raw path segment is decoded once, so an encoded \"/\" or \"+\" is part of the code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_restockalerts.SubscribeInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restockalerts.AlertView" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Existing active alert" }, "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restockalerts.AlertView" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Alert created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "market_code is required" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Retail customer account required" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "details.reason_code is SKU_NOT_FOUND, MARKET_UNRESOLVED or SKU_NOT_LISTED_IN_MARKET" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "details.reason_code is RESTOCK_ALERT_LIMIT_REACHED (100 active alerts per market)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "STOREFRONT_RESTOCK_ALERTS_ENABLED is off, or Pricing listings or stock availability are unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Subscribe to a restock alert", "tags": [ "restock-alerts" ] } }, "/media/buckets": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_media.bucketListAPIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List GCS buckets in the project", "tags": [ "media" ] } }, "/media/buckets/{bucket}/objects": { "get": { "description": "Requires media.read and the configured public asset bucket. By default,\nlists one directory level. recursive=true is supported only with the\nexact prefix brand/logo/ and returns a flat gallery of active, public,\nmanaged brand-logo images across dated subfolders. Unmanaged, deleted\nand non-image objects are omitted; active unattached uploads remain\nselectable by media_code. Recursive responses contain an empty folders\narray. Scans exceeding 5000 objects fail without returning partial data.\nImage previews continue to use the authenticated media download-URL route.", "parameters": [ { "description": "Bucket name", "in": "path", "name": "bucket", "required": true, "schema": { "type": "string" } }, { "description": "Prefix to list under", "in": "query", "name": "prefix", "schema": { "type": "string" } }, { "description": "Flatten brand/logo/ into managed logo images. Only true or false is accepted; defaults to false.", "in": "query", "name": "recursive", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_media.bucketObjectListAPIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing bucket, invalid recursive flag or prefix, or recursive scan exceeds 5000 objects" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List folders and objects under a prefix in a bucket", "tags": [ "media" ] } }, "/media/finalize": { "post": { "description": "Verifies the uploaded object against its folder policy (size cap and a\nMIME check on the stored bytes) and activates the media row.\nDe-duplication is per folder. When the same folder already holds an\nactive row with these bytes, the new object and pending row are\ndiscarded and the existing row is returned. The same bytes finalized in\nanother folder, for example as a product cover and as a gallery image,\nget their own media code, so each image role references a code from its\nown folder. The first folder to finalize the bytes gets the\ncontent-addressed code and later folders get a folder-scoped code of the\nsame MED + 24 upper-case hex shape. 409 usually means the upload lost a\nlifecycle race; request a new upload and retry. It is also the answer\nwhen both codes these bytes can take in this folder are already held:\nthe content-addressed code by any other row, and this folder's scoped\ncode by a media row deleted from this folder (for example the same image\nfinalized and deleted twice here). Soft delete keeps a row's code, so a\nretry does not clear that case.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_media.FinalizeRequest", "description": "Media id to finalize", "summary": "body" } ] } } }, "description": "Media id to finalize", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = active media document" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "already finalized/deleted, object not yet uploaded, or exceeds folder max size" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "lost a lifecycle race, or both codes these bytes can take in this folder are already held" } }, "security": [ { "BearerAuth": [] } ], "summary": "Finalize a pending media upload", "tags": [ "media" ] } }, "/media/folders": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = array of { key, max_bytes, mime_types, visibility }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List media folder policies", "tags": [ "media" ] } }, "/media/upload-url": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_media.UploadRequest", "description": "Upload request", "summary": "body" } ] } } }, "description": "Upload request", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a direct-to-GCS signed upload URL", "tags": [ "media" ] } }, "/media/{mediaCode}": { "delete": { "parameters": [ { "description": "Media code", "in": "path", "name": "mediaCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "media not active" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "media retained by an approved import-compliance revision" } }, "security": [ { "BearerAuth": [] } ], "summary": "Soft-delete media", "tags": [ "media" ] }, "get": { "parameters": [ { "description": "Media code", "in": "path", "name": "mediaCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = media document" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get media metadata", "tags": [ "media" ] } }, "/media/{mediaCode}/content": { "get": { "description": "Public and unauthenticated. Product cover, gallery, and detail media\nreturn image bytes directly (200), without a signed-URL redirect.\nvariant=card fits within 480x480; variant=detail fits a width of 1080\nwhile preserving complete long panels. Neither crops nor upscales.\nStorefront rendition URLs use the configured absolute public origin for\ncompatibility with installed clients that reject relative URL queries.\nOmit variant or use original for original bytes suitable for zoom.\nOpaque renditions are JPEG; transparent renditions are PNG. Animated,\nunsupported, over-limit, and non-beneficial transforms retain original\nbytes and MIME type. Other media folders retain their signed 307 redirect.\nProduct renditions persist in managed storage across service instances.\nNew uploads generate both variants during finalization; existing images\ngenerate a requested missing variant on demand. Current owner visibility\nis checked before any stored rendition or conditional response is served.\nProduct responses use public, max-age=300, must-revalidate and a\ngeneration/variant-specific ETag. If-None-Match can return 304 only after\ncurrent visibility checks. Previously cached bytes may remain visible\nfor up to five minutes after withdrawal; errors are not cacheable.\nFail-closed by design: answers 404 until the media code is attached to a\ncustomer-visible owner - an Active product that is currently\nstorefront-sellable, a collection whose current icon it is, or an active\nbrand whose current logo it is. A freshly finalized upload, media on a\nDraft, inactive or unsellable product, private media and unknown, pending\nor deleted codes all answer 404 (\"media content not found\", or \"media not\nfound\" when no active media row exists), so a 404 for a new upload is\nexpected and is not an upload failure. Staff tools must preview with\nGET /media/{mediaCode}/download-url.", "parameters": [ { "description": "Managed media code", "in": "path", "name": "mediaCode", "required": true, "schema": { "type": "string" } }, { "description": "Product image rendition. Other public media folders retain their existing redirect behavior.", "in": "query", "name": "variant", "schema": { "default": "original", "enum": [ "card", "detail", "original" ], "type": "string" } }, { "description": "ETag from an earlier product image response. Visibility is checked before matching.", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "image/avif": { "schema": { "format": "binary", "type": "string" } }, "image/gif": { "schema": { "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "format": "binary", "type": "string" } }, "image/png": { "schema": { "format": "binary", "type": "string" } }, "image/webp": { "schema": { "format": "binary", "type": "string" } } }, "description": "Product image bytes. Successful content permits cross-origin image embedding.", "headers": { "Cache-Control": { "description": "public, max-age=300, must-revalidate", "schema": { "type": "string" } }, "ETag": { "schema": { "type": "string" } } } }, "304": { "description": "Currently visible product image matches If-None-Match; no response body." }, "307": { "description": "Temporary Redirect. Successfully owner-authorized public content allows cross-origin image embedding with Cross-Origin-Resource-Policy cross-origin; private and error responses retain same-origin." }, "400": { "description": "Unknown variant." }, "404": { "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "500": { "description": "Media authorization, stored image validation, or storage failed. Not cacheable." }, "503": { "description": "Rendition capacity or deadline unavailable. Not cacheable; retry later." } }, "summary": "Serve public product images and resolve other public media", "tags": [ "media" ] } }, "/media/{mediaCode}/download-url": { "get": { "description": "Staff preview and download route. Requires a bearer token with permission\nmedia.read. Returns a short-lived signed URL for any ACTIVE media row,\npublic or private, whether or not it is attached to an owner, so it works\nimmediately after POST /media/finalize. Unknown, pending and deleted codes\nanswer 404. The public GET /media/{mediaCode}/content route is not a\npreview route.", "parameters": [ { "description": "Media code", "in": "path", "name": "mediaCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { url, expires_at }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "media not active" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Sign a media download URL", "tags": [ "media" ] } }, "/net-goods-valuations/{skuCode}/{currency}/{depotCode}": { "get": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "currency", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_netgoods.Advice" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read private net-goods valuation advice", "tags": [ "net-goods-valuations" ] } }, "/orders/{orderNumber}/carrier-booking": { "post": { "description": "One carrier job keyed by the order number covers every shipment of the order. Refused (409 shipments_not_packed or order_not_ready) until every shipment is packed and the whole packing plan is assigned. The delivery company's gates (company_disabled, booking_not_configured, sandbox_test_required, credential_revoked, configuration_invalid) are checked before any booking input, so a configuration problem is reported first. production_date is required only by companies whose booking request carries the intake date. The order is re-read and each shipment's recipient refreshed. The values actually sent are written onto every shipment's latest_carrier_booking. A pending attempt is stored before the single carrier call; booked or already_booked (with the carrier's existing reference) resolves it and dispatches every shipment with carrier = company code and tracking_number = reference in one transaction, publishing fulfilment.tracking_updated and fulfilment.shipped per shipment. A repeated command after a booking returns the dispatched shipments, or dispatches with the recorded reference without booking again. Credentials never leave Supply.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierBookingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierBookingResponse" } } }, "description": "Booked (or already booked) and every shipment dispatched" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid input, missing production_date (only for a company that sends the intake date), carrier_mismatch without override, a missing booking input (details.field), or a carrier rejection recorded on the attempt (details.attempt_id, error_code, error_fields, carrier_message)" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "The order has no shipments" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT (details.reason): shipments_not_packed, order_not_ready, mixed_carriers, booking_in_progress, already_booked (carrier holds the order without returning a reference), dispatch_failed, company_disabled, booking_not_configured, sandbox_test_required, credential_revoked, configuration_invalid, packing_not_complete, fulfilment_superseded, remainder_unpaid, refund_projection_stale (packing owner refused dispatch; no attempt stored, carrier not contacted)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Carrier unreachable (attempt recorded unreachable, error_code timeout when it did not answer in time), the order or booking configuration is unavailable, or the packing/order dispatch authority is unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Book an order's shipments with their delivery company and dispatch them", "tags": [ "shipments" ] } }, "/packing/history": { "get": { "description": "Read scoped packing history without workflow writes. Current owner status is captured with immutable rows for 30 minutes. Date bounds are from inclusive and to exclusive. Pagination and all-filtered export reuse snapshot_id, identical filters and next_offset; expiration or query/actor/scope changes require a fresh query. All closed and superseded records are included.", "parameters": [ { "in": "query", "name": "operator", "schema": { "type": "string" } }, { "description": "Records where this staff member packed any storage group (max 200 characters).", "in": "query", "name": "stage_packer", "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "order_number", "schema": { "type": "string" } }, { "in": "query", "name": "order_status", "schema": { "type": "string" } }, { "in": "query", "name": "refund_status", "schema": { "type": "string" } }, { "in": "query", "name": "from", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "to", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "has_damage", "schema": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } }, { "in": "query", "name": "snapshot_id", "schema": { "type": "string" } }, { "in": "query", "name": "offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "in": "query", "name": "limit", "schema": { "default": 100, "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_platform_historyquery.PackingPage" }, "success": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission, subject, scope or geography denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflicting or insufficient fulfilment evidence" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Owner or evidence authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read scoped packing history without workflow writes", "tags": [ "Packing" ] } }, "/packing/history/operators": { "get": { "description": "Distinct authenticated operator IDs in the scoped filtered packing history, including the packers of recorded packing stages. The operator and stage_packer filters themselves are ignored.", "parameters": [ { "in": "query", "name": "operator", "schema": { "type": "string" } }, { "description": "Ignored, like operator.", "in": "query", "name": "stage_packer", "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "order_number", "schema": { "type": "string" } }, { "in": "query", "name": "order_status", "schema": { "type": "string" } }, { "in": "query", "name": "refund_status", "schema": { "type": "string" } }, { "in": "query", "name": "from", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "to", "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "has_damage", "schema": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "type": "string" }, "type": "array" }, "success": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission, subject, scope or geography denied" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflicting or insufficient fulfilment evidence" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Owner or evidence authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Distinct authenticated operator IDs in the scoped filtered packing history", "tags": [ "Packing" ] } }, "/packing/intake": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_packing.IntakeInput", "description": "Order numbers to intake (max 100)", "summary": "body" } ] } } }, "description": "Order numbers to intake (max 100)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Open packing orders after picking starts", "tags": [ "packing" ] } }, "/packing/orders": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_packing.CreateInput", "description": "Order number to open/reuse a packing order for", "summary": "body" } ] } } }, "description": "Order number to open/reuse a packing order for", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Load or create a packing order by order number", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}": { "get": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a packing order", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/batches/{batch}/finalize": { "post": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "description": "Batch name", "in": "path", "name": "batch", "required": true, "schema": { "enum": [ "dry", "ambient", "chilled", "ambient_chilled", "frozen" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.field batch for an unknown batch name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Mark a packing batch as finalized", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/batches/{batch}/start": { "post": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "description": "Batch name", "in": "path", "name": "batch", "required": true, "schema": { "enum": [ "dry", "ambient", "chilled", "ambient_chilled", "frozen" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.field batch for an unknown batch name" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Mark a packing batch as started", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/damages": { "post": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_packing.DamageInput", "description": "Damage details", "summary": "body" } ] } } }, "description": "Damage details", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "stock reservation changed; retry" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record packing damage and write off reserved stock", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/allocations": { "get": { "description": "Requires packing write permission and order/depot geographic access. Includes original allocations even when their source is empty; it does not claim that stock remains physically present.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Required for continuation pages.", "in": "query", "name": "stock_fence", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/packing.SourceAllocationPage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store original allocation page" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing revision or stock snapshot changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the existing allocations for a packing item", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/issued-sources": { "get": { "description": "Requires packing write permission and order/depot geographic access. Returns only quantities still issued after prior corrections. Physical return confirmation and a reason are required when submitting a correction.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.PackingIssuedSourcePage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store outstanding issue page" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing revision or stock issue evidence changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List outstanding stock issues for an audited packing correction", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/shortage-reinstatements": { "post": { "description": "Requires packing.write and an authenticated staff identity. Records base_units of the item's withdrawn shortage units that are not yet packed as missing again, for a restock that did not arrive. In one transaction it appends a reinstate entry (withdrawn_by, withdrawn_at, withdrawn_base_units) to the discrepancy, releases restocked allocation made for the withdrawn units that no stock movement used (topping the line up again when a released allocation was larger than needed), re-applies the shortage's stock hold, increments the packing revision and publishes fulfilment.packing_updated, so Orders sees the larger remaining shortage and may raise a refund request. The same idempotency_key and request replays the current record.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "description": "Order item ID of the short line", "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_packing.ShortageReinstatementInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "The packing order with the reinstatement applied, or the replayed current record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid body or missing staff identity (VALIDATION_ERROR), or stock for a top-up is not available (INSUFFICIENT_STOCK)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing packing.write" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Packing order, item or the item's shortage discrepancy not found (NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Stale expected_revision, base_units above the withdrawn units not yet packed (details.unpacked_withdrawn_base_units), idempotency_key reused with a different request, order not in packing, or stock changed (CONFLICT); the line has no active stock reservation (PACKING_LINE_NOT_RESERVED). PACKING_LINE_NOT_RESERVED is an invariant guard (every order line is reserved in full at order time), never a business outcome." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Order, stock or transaction authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record withdrawn shortage units missing again", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/shortage-withdrawals": { "post": { "description": "Requires packing.write and an authenticated staff identity. Takes back base_units of the item's recorded shortage (fully or partly) so the restocked units can be packed; 待補 (wait restock) is a shortage, not a separate kind. Allowed while the shortage's refund is only requested or there is none, and refused with 409 PACKING_SHORTAGE_REFUND_APPLIED once the missing-item refund has been applied. In one transaction it appends a withdrawal (method command, withdrawn_by, withdrawn_at, withdrawn_base_units) to the discrepancy, extends the line's allocation from stock when the quantity to pack exceeds it, releases the shortage's stock hold when nothing remains missing, increments the packing revision and publishes fulfilment.packing_updated so Orders can cancel a requested refund. A shortage withdrawn in full gives the reservation back the expiry its hold cleared, or now plus 48 hours when that expiry is past or within 48 hours. The withdrawn units must then be packed before mark-packed, or recorded missing again with shortage-reinstatements. The same idempotency_key and request replays the current record.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "description": "Order item ID of the short line", "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_packing.ShortageWithdrawalInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "The packing order with the withdrawal applied, or the replayed current record" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid body or missing staff identity (VALIDATION_ERROR), or the restocked units are not available to allocate (INSUFFICIENT_STOCK)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing packing.write" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Packing order, item or the item's shortage discrepancy not found (NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "The shortage's refund is applied (PACKING_SHORTAGE_REFUND_APPLIED); stale expected_revision, base_units above the remaining shortage (details.remaining_base_units), idempotency_key reused with a different request, order not in packing, or stock changed (CONFLICT); the line has no active stock reservation (PACKING_LINE_NOT_RESERVED). PACKING_LINE_NOT_RESERVED is an invariant guard (every order line is reserved in full at order time), never a business outcome." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Order, stock or transaction authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Take back a recorded packing shortage", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/shortages/{discrepancyID}/release-sources": { "get": { "description": "Requires packing write and depot access. Candidates are not a stock reservation. To continue, send next.after_id as cursor, next.query_hash as cursor_hash, and the returned stock_fence.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discrepancyID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "stock_fence", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "cursor_hash", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/packing.ShortageReleasePage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store source candidates" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing or stock snapshot changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List sources eligible for a shortage reinstatement", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/shortages/{discrepancyID}/release-sources/{allocationID}/units": { "get": { "description": "Requires packing write and depot access. Return the allocation and bucket versions and stock fence from the source page. For continuation send next.after_id as cursor and next.query_hash as cursor_hash.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "discrepancyID", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "allocationID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "stock_fence", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "allocation_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "bucket_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "bucket_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "cursor_hash", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/packing.ShortageReleaseUnitPage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store tracked unit candidates" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing or stock snapshot changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List tracked units for a shortage reinstatement source", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/sources": { "get": { "description": "Requires packing write permission and order/depot geographic access. Candidates are not proof that stock was physically identified; the packing settlement rechecks the selected source.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Required for continuation pages.", "in": "query", "name": "stock_fence", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/packing.SourcePage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store source candidate page" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing revision or stock snapshot changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List physical source candidates for a packing item", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/items/{itemID}/sources/{bucketID}/units": { "get": { "description": "Requires packing write permission and order/depot geographic access. A listed unit is a candidate, not a claim that staff physically identified it. Currently only units in the item's existing allocations are available for selection.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "itemID", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "bucketID", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "stock_fence", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/packing.SourceUnitPage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store tracked-unit candidate page" }, "400": { "description": "Invalid page query" }, "401": { "description": "Authentication required" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Packing revision or stock snapshot changed" } }, "security": [ { "BearerAuth": [] } ], "summary": "List tracked units held by this packing item at a source", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/mark-packed": { "post": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_packing.MarkPackedInput" } } }, "description": "The packing revision reviewed by the staff member.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "stock reservation changed; retry" } }, "security": [ { "BearerAuth": [] } ], "summary": "Settle stock and finish packing", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/progress": { "patch": { "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_packing.ProgressInput", "description": "Scanned lines", "summary": "body" } ] } } }, "description": "Scanned lines", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Stale revision, changed frozen evidence or allocation, a recorded shortage changed other than by withdrawn units, the shortage's refund is applied (PACKING_SHORTAGE_REFUND_APPLIED), or the short line has no active stock reservation (PACKING_LINE_NOT_RESERVED). PACKING_LINE_NOT_RESERVED is an invariant guard (every order line is reserved in full at order time), never a business outcome." } }, "security": [ { "BearerAuth": [] } ], "summary": "Record packing quantities and immediately update physical stock", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/reopen": { "post": { "description": "Reopen the specified packed revision for repacking. Undispatched shipments without a successful carrier booking are archived and their box assignments released. A physical return is a separate confirmed packing progress operation. Repeat the same idempotency key only with the same revision and reason. Another authorized packer may retry; the original actor and the retrying actor remain recorded.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "expected_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "reason": { "minLength": 1, "type": "string" } }, "required": [ "expected_revision", "idempotency_key", "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Reopened packing record" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Reopen refused or revision changed. When available, details.reason identifies shipment_dispatched, carrier_booked, booking_in_progress, or booking_outcome_unknown." }, "503": { "description": "Owner coordination unavailable or recovery pending" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reopen a packed order for repacking", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/reopen/recover": { "post": { "description": "Resume the current owner-recorded reopen after an interruption. An authorized packer can recover it without the original workstation's idempotency key. If reopening has already completed and no operation remains pending, return the current in-progress packing record.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Recovered or current packing record" }, "401": { "description": "Unauthorized" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "No recoverable reopen, or another operation is pending" }, "503": { "description": "Owner coordination unavailable or recovery pending" } }, "security": [ { "BearerAuth": [] } ], "summary": "Recover an interrupted packing reopen", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/scans": { "post": { "description": "Requires expected revision and idempotency key. Returns the authoritative aggregate; physical stock and manifest changes commit atomically. Replays do not increment counts. Scanning a line with a recorded shortage past its requested quantity less the remaining shortage withdraws the excess from the shortage (method scan) in the same transaction, allocating the scanned package from stock first when the line's allocation does not cover it; a shortage withdrawn in full releases its stock hold. Once the shortage's missing-item refund is applied the scan answers 409 PACKING_SHORTAGE_REFUND_APPLIED.", "parameters": [ { "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_packing.ScanInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.CommandResponse" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Authoritative packing order and the allocated container identity" }, "400": { "description": "Invalid command" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Packing write permission required" }, "404": { "description": "Packing order not found" }, "409": { "description": "Stale revision, conflicting replay, ineligible order, the shortage's refund is applied (PACKING_SHORTAGE_REFUND_APPLIED), or the short line has no active stock reservation to allocate restocked units from (PACKING_LINE_NOT_RESERVED). PACKING_LINE_NOT_RESERVED is an invariant guard (every order line is reserved in full at order time), never a business outcome." }, "503": { "description": "Required authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Apply one atomic packing scan", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/shipment": { "post": { "description": "Create or recover the packed delivery order's shipment using the authoritative depot and currently unassigned boxes. No request body is required. An exact repeat returns an existing shipment. Pickup, in-store and non-delivery orders do not create a shipment.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/fulfilment.OutboundShipment" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Created or existing outbound shipment" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Packing permission or geographic access required" }, "409": { "description": "Order or packing state no longer permits shipment creation" }, "503": { "description": "Owner coordination unavailable or recovery pending" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create or recover a packed order's shipment", "tags": [ "packing", "shipments" ] } }, "/packing/orders/{orderNumber}/stages": { "post": { "description": "Record that one storage group's labels printed. The packer is the authenticated staff member, never a request field. The first print of a storage group in the current packing cycle sets packed_by and labels_printed_at; later prints (reprints) set last_printed_at and box_count only. After the order is reopened for repacking, the first print of a group replaces that group's stage and records the new packer. Accepted while the record is packing or packed. Recording a stage does not change the record revision or updated_at, so a concurrent revisioned command's expected_revision stays valid. Prints arriving out of order keep the earliest as labels_printed_at and the newest as last_printed_at with its box_count. The same idempotency_key and request replays the current record; the same key with a different request is a conflict.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_packing.StageInput" } } }, "description": "The printed storage group and its box count.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.field packing_id, storage_group, box_count, labels_printed_at or idempotency_key; ORDER_TERMINAL for a closed packing record; ORDER_INVALID_TRANSITION when the record is not packing or packed" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized or no authenticated packer" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Packing record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "packing_id is not the current packing record (details.reason packing_superseded), the idempotency_key was used with a different request, or the stage changed concurrently; retry" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Packing stages unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a packing stage label print", "tags": [ "packing" ] } }, "/packing/orders/{orderNumber}/start": { "post": { "description": "Advances fulfilment to packing after a fresh Orders eligibility check. Requires paid payment, picking sales status, ready stock, and a recorded picking start print. Continuing local packing also accepts the owner packing projection. Digital gift-card purchases and closed records are excluded. Owner lookup failure returns 503.", "parameters": [ { "description": "Order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_packing.RecordResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Order is ineligible for packing or the packing record is closed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authoritative order eligibility provider unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Begin packing an order", "tags": [ "packing" ] } }, "/packing/queue": { "get": { "parameters": [ { "description": "Queue tab", "in": "query", "name": "tab", "schema": { "default": "pending", "enum": [ "pending", "incomplete", "packed", "awaiting" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown queue tab" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List packing workflow queue items", "tags": [ "packing" ] } }, "/pos/catalog/master": { "get": { "description": "Requires pos.access and current workforce access to the selected physical depot and market on every request. Omit cursor for a complete bootstrap; pass next_cursor for frozen continuation, or the terminal sync_cursor to poll changes. Bootstrap and terminal polls qualify Pricing membership with a fresh owner probe, at most five-minute membership evidence and the earlier owner boundary. Continuations use retained rows and do not need a new price/stock observation. Additions and tombstones do not depend on product timestamps. Unsupported or repeated query parameters are rejected. Success responses are no-store.", "parameters": [ { "description": "Physical depot code from the selected register.", "in": "query", "name": "store_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "in": "query", "name": "market_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Opaque v2 continuation or terminal checkpoint. Only native v2 cursors are accepted.", "in": "query", "name": "cursor", "schema": { "maxLength": 4096, "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.POSMasterResponse" } } }, "description": "Complete page from one retained snapshot or delta; an unchanged terminal poll has no items and retains its cursor." }, "400": { "description": "Invalid context, page size, unsupported or repeated query parameter." }, "401": { "description": "Authentication required." }, "403": { "description": "Missing pos.access or workforce geographic access." }, "404": { "description": "Depot missing, inactive or ineligible for this market." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "POS_MASTER_CURSOR_EXPIRED with recovery=bootstrap for expired, missing, malformed or context-mismatched cursor evidence; POS_MASTER_SOURCE_CHANGED for an owner/master fence change, requiring retry of the same cursor." }, "503": { "description": "Owner or storage evidence unavailable, or another snapshot build is pending. Retry with bounded backoff; never interpret this as a successful empty catalogue." } }, "security": [ { "BearerAuth": [] } ], "summary": "Immutable POS master snapshot and incremental changes", "tags": [ "pos" ] } }, "/pos/catalog/refresh": { "post": { "description": "Requires pos.access and current workforce access to the selected physical depot and market. Accepts 1 to 100 unique SKU codes in a strict JSON body of at most 32 KiB. Uses bounded Pricing eligibility and native product reads, never a full catalogue traversal. Opening and closing generation/effective-time fences reject mixed evidence. Failed or incomplete owner/stock reads fail the entire request. Unsupported or repeated query parameters are rejected. Success responses are no-store.", "parameters": [ { "description": "Physical depot code from the selected register.", "in": "query", "name": "store_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "in": "query", "name": "market_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.POSRefreshRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.POSRefreshAPIResponse" } } }, "description": "One result per requested SKU. Complete zero canonical EACH stock is out_of_stock; no canonical EACH retains aggregate unknown while exact package quantities remain available." }, "400": { "description": "Invalid context, body, SKU bounds, duplicate SKU or unsupported/repeated query parameter." }, "401": { "description": "Authentication required." }, "403": { "description": "Missing pos.access or workforce geographic access." }, "404": { "description": "Depot missing, inactive or ineligible for this market." }, "409": { "description": "POS_MASTER_SOURCE_CHANGED; price, membership, product generation or effective-time evidence changed during the read. Retry the request." }, "503": { "description": "Pricing, product or stock evidence failed validation or was unavailable. No partial refresh or false zero stock is returned." } }, "security": [ { "BearerAuth": [] } ], "summary": "Refresh bounded POS eligibility, price and exact-package stock", "tags": [ "pos" ] } }, "/pos/products/by-barcode/{barcode}": { "get": { "description": "Requires pos.access and workforce geographic access to the selected depot and market. No ESL configuration is required. Returns the hydrated POS catalogue row with Pricing-owned selling_product and price availability. Matches only effective barcode/package assignments within the store market. The administrative barcode route keeps product.read. Cursor/feed filters are not accepted.", "parameters": [ { "description": "Exact active barcode; URL-encode path characters.", "in": "path", "name": "barcode", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "description": "Physical depot code from the selected register; never an ESL configuration key.", "in": "query", "name": "store_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Selected register market; Supply validates the effective depot-market association.", "in": "query", "name": "market_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_productmodel.CatalogProduct" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing or malformed depot/market, invalid barcode or unsupported query filters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Depot inactive or ineligible for the market, or no active barcode/product package assignment in that market." }, "409": { "description": "Ambiguous barcode ownership or pricing/catalogue context changed during the lookup." }, "503": { "description": "Store, catalogue or authoritative pricing unavailable." } }, "security": [ { "BearerAuth": [] } ], "summary": "Look up an active barcode for the selected POS depot and market", "tags": [ "pos" ] } }, "/pos/stores/{store_code}": { "get": { "description": "Requires pos.access and workforce geographic access. store_code is the physical depot code from the selected Payments register, not an ESL configuration key. Supply validates active in-store depot eligibility and its effective association with market_code. Returns geography and the optional depot display name without ESL configuration, catalogue rows or selling-price lookups. No public pre-sign-in variant is exposed.", "parameters": [ { "in": "path", "name": "store_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Selected register market; validated against the authoritative depot-market association.", "in": "query", "name": "market_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.posStoreAPIResponse" } } }, "description": "Resolved store geography" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing or malformed depot/market code" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing POS permission or store outside workforce geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Depot missing, inactive or ineligible for the requested market" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Depot or market authority inconsistent or temporarily unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Resolve the selected POS depot and market geography", "tags": [ "catalog" ] } }, "/product-reviews": { "get": { "description": "Returns the protected internal projection. It carries the review owner's customer number and the moderation note, neither of which appears in a public or owner projection.", "parameters": [ { "description": "Filter by product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Filter by moderation status", "in": "query", "name": "moderation_status", "schema": { "enum": [ "draft", "pending_approval", "published", "rejected", "suppressed" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "ETag from a previous response; a match returns 304 without a body", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List internal review moderation records", "tags": [ "reviews" ] } }, "/product-reviews/{id}/moderation": { "patch": { "description": "Pending may become approved, rejected, or suppressed; approved/rejected may later be suppressed; suppressed is terminal. Repeating the current action is idempotent. Reject requires a rejection_reason.", "parameters": [ { "description": "Review id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_reviews.ModerationInput", "description": "Moderation action", "summary": "body" } ] } } }, "description": "Moderation action", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Approve, reject, or suppress review text", "tags": [ "reviews" ] } }, "/product-selections": { "get": { "description": "Requires product.read. Lists non-deleted selections ordered by display_order ascending, then name, then code.", "parameters": [ { "description": "Case-insensitive search over code, slug and localized names", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Filter by status; omitted returns every status", "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/selection_enums.ProductSelectionStatus" } }, { "description": "Filter by kind; omitted returns both kinds", "in": "query", "name": "kind", "schema": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Items per page (default 50, max 200)", "in": "query", "name": "page_size", "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionPageAPIResponse" } } }, "description": "data = { items: [selection.ProductSelection], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request; unknown status or kind" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List product selections", "tags": [ "product-selections" ] }, "post": { "description": "Requires product.write. Creates a selection (default status draft, revision 1) with no products and a server-generated code (^[A-Z0-9]{8}$, returned in data.code). code and slug stay reserved after soft delete.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSelectionInput" } } }, "description": "New product selection", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionAPIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; invalid slug, name, enums, display_order or media, an unknown field (including code), or publish rules (details.reason cover_required, icon_required, members_required)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; slug already used (including soft-deleted selections; details.slug), or media is not usable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a product selection", "tags": [ "product-selections" ] } }, "/product-selections/order": { "put": { "description": "Requires product.write. Atomically renumbers every published, non-deleted selection of one kind 1..N in the given order and increments each revision. display_order is unique among published, non-deleted selections of a kind.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSelectionOrderInput" } } }, "description": "Complete display order for one kind", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionListAPIResponse" } } }, "description": "data = [selection.ProductSelection] in the new order, each with its new display_order and revision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; unknown kind, missing items, blank or duplicate code (details.code), expected_revision missing or not positive (details.code), or an unknown field" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; items are not exactly the published selections of the kind (details.reason order_set_mismatch with details.unexpected_code or details.missing_code), an expected_revision is stale (details.code), or a concurrent write; nothing changed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reorder the published product selections of one kind", "tags": [ "product-selections" ] } }, "/product-selections/{code}": { "delete": { "description": "Requires product.delete. Soft delete guarded by expected_revision. Membership is retained; code and slug stay reserved; admin and storefront reads then answer 404. Idempotent - deleting an already-deleted selection answers 200 without another write. There is no restore endpoint.", "parameters": [ { "description": "Selection code", "in": "path", "name": "code", "required": true, "schema": { "pattern": "^[A-Z0-9]{8}$", "type": "string" } }, { "description": "Current selection revision", "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "const": true, "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Deleted (or already deleted): { \"success\": true }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; expected_revision missing or not a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; no selection with this code ever existed" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Soft-delete a product selection", "tags": [ "product-selections" ] }, "get": { "description": "Requires product.read.", "parameters": [ { "description": "Selection code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionAPIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown or soft-deleted selection" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a product selection", "tags": [ "product-selections" ] }, "patch": { "description": "Requires product.write. Partial update guarded by expected_revision; code is immutable. slug changes only while the stored status is draft. Publish rules apply whenever the resulting status is published. Publishing, or changing kind while published, onto a display_order already used by a published selection of that kind places the selection at N+1 for the kind.", "parameters": [ { "description": "Selection code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSelectionPatch" } } }, "description": "Product selection patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionAPIResponse" } } }, "description": "Updated selection with its new revision" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; invalid fields, slug change while published or archived, icon with clear_icon, cover with clear_cover, or publish rules (details.reason cover_required, icon_required, members_required)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown or soft-deleted selection" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale, slug already used, an already published selection moved onto a display_order used by another published selection of the kind (details.field display_order), or media is not usable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a product selection", "tags": [ "product-selections" ] } }, "/product-selections/{code}/products": { "get": { "description": "Requires product.read. Returns the selection and its complete ordered membership (at most 200 items, not paginated) read at one revision.", "parameters": [ { "description": "Selection code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionItemsAPIResponse" } } }, "description": "data = { selection: selection.ProductSelection, items: [productSelectionItemView] }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown or soft-deleted selection" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; membership changed during the read, retry" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a product selection's ordered products", "tags": [ "product-selections" ] }, "put": { "description": "Requires product.write. Atomically replaces the ordered membership (max 200) and increments the selection revision.", "parameters": [ { "description": "Selection code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.ProductSelectionItemsInput" } } }, "description": "Complete ordered membership", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.productSelectionItemsAPIResponse" } } }, "description": "data = { selection: selection.ProductSelection (new revision), items: [productSelectionItemView] }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; more than 200 codes, blank, duplicate or unknown sku_code (details.sku_code), or an empty list while published (details.reason members_required)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown or soft-deleted selection" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT; expected_revision is stale" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace a product selection's ordered products", "tags": [ "product-selections" ] } }, "/products": { "get": { "parameters": [ { "description": "Exact sku_code filter", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Comma-separated sku_code list (max 200); cannot combine with sku_code", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "Exact barcode filter", "in": "query", "name": "barcode", "schema": { "type": "string" } }, { "description": "SKU master code filter", "in": "query", "name": "sku_series_code", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage_type", "schema": { "type": "string" } }, { "description": "draft, active, archived, or discontinued", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Exact immutable brand code filter", "in": "query", "name": "brand_code", "schema": { "type": "string" } }, { "description": "Collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Category-tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "top_10 (requires category) or no_sales_30d", "in": "query", "name": "sales_view", "schema": { "type": "string" } }, { "description": "RESTOCKED filters products restocked within the lifecycle window. NEW requires market_code and filters products whose listing in that market (retail ONLINE channel) became available within the NEW window; products with the matching lifecycle suppression override are excluded. Both predicates apply before count and pagination. Case-insensitive; any other value answers 400.", "in": "query", "name": "lifecycle_tag", "schema": { "enum": [ "NEW", "RESTOCKED" ], "type": "string" } }, { "description": "Market whose retail (ONLINE) listing dates decide NEW. Required with lifecycle_tag=NEW; trimmed, nonempty and one value only when present. When supplied, rows carry NEW in lifecycle_tags (with display_status new and new_expires_at) for that market. It does not otherwise restrict rows to the market. An unknown market answers 400; unavailable market availability answers 503.", "in": "query", "name": "market_code", "schema": { "minLength": 1, "type": "string" } }, { "description": "Literal case-insensitive substring search over all localized product and brand names, case-insensitive prefix over SKU and SKU-series codes, and case-sensitive prefix over barcodes. Regex characters are escaped; alternatives are OR, explicit filters are AND. Brand matches are resolved before counting and pagination.", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based, default 1); offset paging has no snapshot guarantee across concurrent edits.", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (default 50, maximum 200); top_10 sales view forces page 1 and size 10.", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Product ordering token; unsupported tokens use updated_at. Price ordering is rejected.", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc (default desc), with unique SKU-code tie-breaker.", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Exact case-sensitive supplier code; trimmed, nonempty when present, one value only. Combined with all other filters before count and pagination.", "in": "query", "name": "supplier_code", "schema": { "minLength": 1, "type": "string" } }, { "description": "Single literal true or false. True selects a stored preorder object, including disabled, future and closed policies. False selects no object (including missing/null). Omit for all products; separate from storefront currently-open preorder availability.", "in": "query", "name": "has_preorder_policy", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [productView], page: {page, page_size, total_items, total_pages} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request; includes VALIDATION_ERROR for lifecycle_tag other than NEW or RESTOCKED, lifecycle_tag=NEW without market_code, an empty or repeated market_code, or an unknown market" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; market availability could not be resolved for market_code" } }, "security": [ { "BearerAuth": [] } ], "summary": "List products", "tags": [ "products" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.CreateInput", "description": "New product", "summary": "body" } ] } } }, "description": "New product", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request. details.reason_code is COUNTRY_OF_ORIGIN_INVALID (with\ndetails.field) for an invalid country_of_origin block,\nNET_CONTENT_UNIT_UNSUPPORTED (with details.supported_units) for a\nunit outside g, kg, mL, L, m, ea, or NET_CONTENT_DIMENSION_MISMATCH\nwhen net_quantity and standard_measure differ in dimension." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a product", "tags": [ "products" ] } }, "/products/bulk": { "patch": { "description": "Requires product.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. Independent new_suppressed and restocked_suppressed flags reuse persisted lifecycle overrides across all markets. False restores automatic evaluation against existing timestamps without restarting either 14-day window. Suppression-only requests do not edit product status or category tags. Mixed patches commit product edits and lifecycle overrides together. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateProducts", "requestBody": { "content": { "application/json": { "examples": { "restore_automatic_tags": { "value": { "patch": { "new_suppressed": false, "restocked_suppressed": false }, "sku_codes": [ "A00001", "A00002" ] } }, "suppress_both": { "value": { "patch": { "new_suppressed": true, "restocked_suppressed": true }, "sku_codes": [ "A00001", "A00002" ] } }, "suppress_new": { "value": { "patch": { "new_suppressed": true }, "sku_codes": [ "A00001", "A00002" ] } } }, "schema": { "$ref": "#/components/schemas/catalog.BulkProductRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/catalog.BulkProductResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "product.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_sku_codes is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update product status, category tags and lifecycle suppression", "tags": [ "products" ] } }, "/products/by-barcode/{barcode}": { "get": { "description": "Barcode values are non-unique. Returns every matching assignment with its product and package option so the caller must select the intended package. This catalogue lookup does not request Insights or enrich sales.", "parameters": [ { "description": "Product barcode", "in": "path", "name": "barcode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Look up product/package assignments by barcode", "tags": [ "products" ] } }, "/products/preorder-policies": { "put": { "description": "Requires product.write under existing catalogue authorization. One snapshot transaction reads all SKU targets and commits all updates, or aborts all. Duplicates and missing products reject the entire batch. No per-item partial result. Preserves unrelated product fields and the independent soon-expiry policy. Repeating a request reapplies the same business policy; audit timestamps advance. Body limit 128 KiB. Product catalogue scope matches the existing single-product routes.", "operationId": "bulkSetProductPreorderPolicies", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/catalog.BulkPreorderPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/catalog.BulkPreorderPolicyResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected products committed together. Refetch the current list for product views." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection or policy; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "product.write permission required (existing superAdmin bypass retained)." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: all writes rejected; error.details.missing_sku_codes is a comma-separated list in request order." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: concurrent transaction/write conflict; reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: request exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: command failed; no per-item partial success is returned. An ambiguous network/commit outcome can be checked by refetching and safely reapplying the intended policy." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bulk transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Set or clear preorder policies for selected products atomically", "tags": [ "products" ] } }, "/products/purchase-order-reviews": { "get": { "description": "Requires product.read. Shared pending entries ordered by entry ObjectID, independent of Products table filters/pagination. Only single nonblank after/limit query parameters are accepted. Restart from the first page on refresh; acknowledgement removes entries for every staff member. A deleted or unavailable product remains identifiable by its frozen name and SKU.", "parameters": [ { "description": "Exclusive last entry ID from the previous page. Omit for the first page.", "in": "query", "name": "after", "schema": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.PurchaseOrderProductReviewPage" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated or missing actor" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission denied" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Queue unavailable; no partial result" } }, "security": [ { "BearerAuth": [] } ], "summary": "List pending purchase-order product reviews", "tags": [ "products" ] } }, "/products/purchase-order-reviews/acknowledge": { "post": { "description": "Requires product.write and an authenticated actor. All selected entries are acknowledged atomically in request order. Repeating acknowledgement preserves the first actor/time. A missing entry returns 404 with no acknowledgement applied; a transaction conflict returns 409 and the whole request can be retried. Product lifecycle and purchase orders are never changed.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.AcknowledgeProductReviewsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.AcknowledgeProductReviewsResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated or missing actor" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "One or more entries missing; no changes" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Concurrent change; retry whole batch" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Queue unavailable; no partial result" } }, "security": [ { "BearerAuth": [] } ], "summary": "Acknowledge selected purchase-order product reviews", "tags": [ "products" ] } }, "/products/purchase-order-reviews/{entryID}/acknowledge": { "post": { "description": "Requires product.write and an authenticated actor. All selected entries are acknowledged atomically in request order. Repeating acknowledgement preserves the first actor/time. A missing entry returns 404 with no acknowledgement applied; a transaction conflict returns 409 and the whole request can be retried. Product lifecycle and purchase orders are never changed. No request body is required.", "parameters": [ { "in": "path", "name": "entryID", "required": true, "schema": { "description": "Canonical nonzero product/review ObjectID.", "pattern": "^[0-9a-f]{24}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.PurchaseOrderProductReview" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid input" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated or missing actor" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Entry missing" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Concurrent change; retry acknowledgement" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Queue unavailable; no partial result" } }, "security": [ { "BearerAuth": [] } ], "summary": "Acknowledge one purchase-order product review", "tags": [ "products" ] } }, "/products/sku-code-reservations": { "post": { "description": "Atomically allocates the next numeric product code and returns a rolling lease. Allocated numbers are never reused, including after lease expiry.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.ReserveSKUCodeInput", "description": "Selected SKU family", "summary": "body" } ] } } }, "description": "Selected SKU family", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Internal Server Error" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reserve the next product SKU code for a selected SKU family", "tags": [ "products" ] } }, "/products/sku-code-reservations/{reservationID}/heartbeat": { "post": { "parameters": [ { "description": "Reservation ID", "in": "path", "name": "reservationID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Extend an active product SKU-code lease", "tags": [ "products" ] } }, "/products/{skuCode}": { "delete": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a product", "tags": [ "products" ] }, "get": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a product by SKU code", "tags": [ "products" ] }, "patch": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.UpdateInput", "description": "Product patch", "summary": "body" } ] } } }, "description": "Product patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request. details.reason_code is COUNTRY_OF_ORIGIN_INVALID (with\ndetails.field) for an invalid country_of_origin block,\nNET_CONTENT_UNIT_UNSUPPORTED (with details.supported_units) for a\nunit outside g, kg, mL, L, m, ea, or NET_CONTENT_DIMENSION_MISMATCH\nwhen net_quantity and standard_measure differ in dimension.\nexpected_revision must be a positive integer." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict. details.reason_code is PRODUCT_REVISION_STALE when\nexpected_revision was supplied and no longer matches the stored\nrevision (details.expected_revision, details.current_revision);\notherwise the product or a referenced master changed concurrently.\nNothing is written in either case." } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a product", "tags": [ "products" ] } }, "/products/{skuCode}/images": { "put": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.SetImagesInput", "description": "Cover/gallery/detail images", "summary": "body" } ] } } }, "description": "Cover/gallery/detail images", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request; expected_revision must be a positive integer when supplied." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict. details.reason_code is PRODUCT_REVISION_STALE when\nexpected_revision was supplied and no longer matches the stored\nrevision (details.expected_revision, details.current_revision);\notherwise the product or a managed media attachment changed\nconcurrently." } }, "security": [ { "BearerAuth": [] } ], "summary": "Set product images", "tags": [ "products" ] } }, "/products/{skuCode}/lifecycle-tag-overrides": { "patch": { "description": "Requires an authenticated Admin actor with product.write permission.\nUpdates only supplied flags for the product across all markets. Suppression\npersists through product edits and stock updates until explicitly restored.\nFalse resumes automatic eligibility against the unchanged market listing date\nor restock timestamp; it does not restart the 14-day window. NEW suppression\nalso disables NEW display_status promotion and omits new_expires_at.", "operationId": "patchProductLifecycleTagOverrides", "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "restoreAutomaticTags": { "value": { "new_suppressed": false, "restocked_suppressed": false } }, "suppressBoth": { "value": { "new_suppressed": true, "restocked_suppressed": true } }, "suppressNew": { "value": { "new_suppressed": true } }, "suppressRestocked": { "value": { "restocked_suppressed": true } } }, "schema": { "$ref": "#/components/schemas/internal_modules_catalog.LifecycleTagOverrideInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.LifecycleTagOverrideResponse" } } }, "description": "Updated product with persisted suppression flags and computed effective lifecycle fields" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid or empty patch, or expected_revision is not a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized or missing authenticated actor" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing product.write permission" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict. details.reason_code is PRODUCT_REVISION_STALE when\nexpected_revision was supplied and no longer matches the stored\nrevision (details.expected_revision, details.current_revision);\notherwise a targeted suppression flag changed concurrently. Refresh\nand retry." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product lookup or update failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Guarded product updates unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Suppress or restore automatic NEW and RESTOCKED tags", "tags": [ "products" ] } }, "/products/{skuCode}/preorder-policy": { "delete": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Clear a product preorder policy by SKU code", "tags": [ "products" ] }, "put": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "additionalProperties": {}, "title": "body", "type": "object" } ] } } }, "description": "{ policy: \u003cpreorder policy fields\u003e }", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace a product preorder policy by SKU code", "tags": [ "products" ] } }, "/products/{skuCode}/storefront-merchandising": { "put": { "description": "Replaces the admin-managed preorder + soon-expiry merchandising policy wholesale. A null or absent sub-object clears that policy; an empty body clears the whole group. Storefront reads project the stored policy into the customer-safe storefront_display fields. The soon-expiry policy no longer decides whether or when storefront_display.expiry appears; that follows the effective soon-expiry lead days of the market listing (edited in Pricing's market-listing API as expiry_lead_days_override). An enabled policy inside its starts_at/ends_at window supplies the display's labels, descriptions and show_exact_expiry_date.", "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.storefrontMerchandisingInput", "description": "Merchandising policy group", "summary": "body" } ] } } }, "description": "Merchandising policy group", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Set product storefront merchandising policy", "tags": [ "products" ] } }, "/purchase-orders": { "get": { "parameters": [ { "description": "Purchase order status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Supplier code", "in": "query", "name": "supplier_code", "schema": { "type": "string" } }, { "description": "Order number", "in": "query", "name": "order_number", "schema": { "type": "string" } }, { "description": "Reference", "in": "query", "name": "reference", "schema": { "type": "string" } }, { "description": "Supplier name", "in": "query", "name": "supplier_name", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List purchase orders", "tags": [ "purchasing" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.CreateInput" } } }, "description": "New purchase order (created in DRAFT state)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "order_number in use" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a purchase order", "tags": [ "purchasing" ] } }, "/purchase-orders/currencies": { "get": { "description": "purchase.read required. Pinned SIX ISO 4217 List One published 2026-09-17; 165 supported numeric minor-unit codes. No default precision, active-market lookup, rates, or historical conversion. Same dataset validates package_items commands.", "operationId": "purchaseOrderCurrencies", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/internal_procurementcurrency.Catalogue" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Supported precision and exact source/data provenance" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Supported procurement currencies and precision", "tags": [ "purchasing" ] } }, "/purchase-orders/{orderNumber}": { "get": { "description": "Resolves a PO by its human order number (canonical detail route).", "parameters": [ { "description": "Purchase order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a purchase order by order number", "tags": [ "purchasing" ] }, "patch": { "description": "Only DRAFT orders can be edited; use the transition endpoint for status changes.", "parameters": [ { "description": "Purchase order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.UpdateInput" } } }, "description": "Fields to update", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only DRAFT orders can be edited" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a draft purchase order", "tags": [ "purchasing" ] } }, "/purchase-orders/{orderNumber}/transition": { "post": { "parameters": [ { "description": "Purchase order number", "in": "path", "name": "orderNumber", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_purchasing.transitionReq", "description": "Target status", "summary": "body" } ] } } }, "description": "Target status", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown status, or invalid status transition" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Transition a purchase order status", "tags": [ "purchasing" ] } }, "/receipts": { "get": { "parameters": [ { "description": "Linked purchase order number", "in": "query", "name": "purchase_order_number", "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Reference", "in": "query", "name": "reference", "schema": { "type": "string" } }, { "description": "Supplier code", "in": "query", "name": "supplier_code", "schema": { "type": "string" } }, { "description": "Operator", "in": "query", "name": "operator", "schema": { "type": "string" } }, { "description": "Receipt status", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List inbound receipts", "tags": [ "receipts" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_receipts.CreateInput", "description": "New receipt (created in DRAFT state)", "summary": "body" } ] } } }, "description": "New receipt (created in DRAFT state)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a draft goods receipt", "tags": [ "receipts" ] } }, "/receipts/{id}": { "get": { "parameters": [ { "description": "Receipt id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a receipt with its items", "tags": [ "receipts" ] }, "put": { "parameters": [ { "description": "Receipt id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_receipts.UpdateDraftInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/procurement.PurchaseReceipt" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Validation error" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Stale evidence" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Internal failure" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace DRAFT receipt lines with optional validated date marks", "tags": [ "receipts" ] } }, "/replenishment/product-settings/{sku_code}": { "put": { "parameters": [ { "description": "Product SKU code", "in": "path", "name": "sku_code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.ProductSettingInput", "description": "Product replenishment settings", "summary": "body" } ] } } }, "description": "Product replenishment settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "product not found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Save product replenishment settings", "tags": [ "replenishment" ] } }, "/replenishment/purchase-orders": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.CreatePORequest", "description": "Replenishment purchase-order lines", "summary": "body" } ] } } }, "description": "Replenishment purchase-order lines", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "supplier or product not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "purchase order number already exists" } }, "security": [ { "BearerAuth": [] } ], "summary": "Generate a draft purchase order from replenishment lines", "tags": [ "replenishment" ] } }, "/replenishment/settings": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get replenishment settings", "tags": [ "replenishment" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.Settings", "description": "Replenishment settings", "summary": "body" } ] } } }, "description": "Replenishment settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Save replenishment settings", "tags": [ "replenishment" ] } }, "/replenishment/smart-bundle": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.SmartBundleRequest", "description": "Lines to balance", "summary": "body" } ] } } }, "description": "Lines to balance", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Preview smart bundle balancing across replenishment lines", "tags": [ "replenishment" ] } }, "/replenishment/suggestions": { "get": { "parameters": [ { "description": "Case-insensitive product, SKU, or brand search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Filter by supplier code", "in": "query", "name": "supplier_code", "schema": { "type": "string" } }, { "description": "Override target days of stock", "in": "query", "name": "target_days", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List replenishment suggestions", "tags": [ "replenishment" ] } }, "/replenishment/supplier-mappings/{supplier_code}/{sku_code}": { "put": { "parameters": [ { "description": "Supplier code", "in": "path", "name": "supplier_code", "required": true, "schema": { "type": "string" } }, { "description": "Product SKU code", "in": "path", "name": "sku_code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierMappingInput", "description": "Supplier stock-list mapping", "summary": "body" } ] } } }, "description": "Supplier stock-list mapping", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Save a supplier stock-list mapping", "tags": [ "replenishment" ] } }, "/replenishment/supplier-settings/{supplier_code}": { "put": { "parameters": [ { "description": "Supplier code", "in": "path", "name": "supplier_code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.SupplierSettingInput", "description": "Supplier replenishment settings", "summary": "body" } ] } } }, "description": "Supplier replenishment settings", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Save supplier replenishment settings", "tags": [ "replenishment" ] } }, "/replenishment/supplier-stock-lists/parse": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_replenishment.StockListParseRequest", "description": "Supplier stock list rows or raw text", "summary": "body" } ] } } }, "description": "Supplier stock list rows or raw text", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Parse a supplier stock list", "tags": [ "replenishment" ] } }, "/restock-requests": { "get": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "query", "name": "depot_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "after", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 100, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_restocking.Request" }, "type": "array" } }, "required": [ "items" ], "type": "object" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List scoped restock requests", "tags": [ "restocking" ] }, "post": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_restocking.CreateInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restocking.Request" } }, "required": [], "type": "object" } ] } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a physical restock request", "tags": [ "restocking" ] } }, "/restock-requests/{id}": { "get": { "description": "Admin role, dedicated permission, and depot geographic scope required. Device failures are advisory.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restocking.Request" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a restock request", "tags": [ "restocking" ] } }, "/restock-requests/{id}/transition": { "post": { "description": "Admin restock.manage permission and depot scope required. Completion requires exact allocations of genuine replenishment movements recorded since creation. Allocated movement capacity cannot be claimed twice; this operation never creates physical stock.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_restocking.Change" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_restocking.Request" } }, "required": [], "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid configuration or evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Outside role, permission or geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Record not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision changed or physical tag busy" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Dependency unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Transition restock lifecycle using recorded movements", "tags": [ "restocking" ] } }, "/shipments": { "get": { "parameters": [ { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Linked order number", "in": "query", "name": "order_number", "schema": { "type": "string" } }, { "description": "Tracking number", "in": "query", "name": "tracking_number", "schema": { "type": "string" } }, { "description": "Delivery company code recorded as the shipment carrier. Case-insensitive exact match; shipments with no recorded carrier never match.", "in": "query", "name": "carrier", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Status", "in": "query", "name": "status", "schema": { "enum": [ "packed", "dispatched", "delivered" ], "type": "string" } }, { "description": "Outcome of the shipment's latest carrier booking (latest_carrier_booking.outcome); shipments never booked do not match. Any other value is 400 with field=booking_outcome.", "in": "query", "name": "booking_outcome", "schema": { "$ref": "#/components/schemas/courier_enums.CarrierBookingOutcome" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR (for example details.field=booking_outcome)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List outbound shipments", "tags": [ "shipments" ] }, "post": { "description": "Requires shipment.write, or packing.write for a delivery order in the caller's geographic scope. The packing-only path accepts the order's depot and all currently unassigned packed containers, without customer, address, carrier, override or note fields. Legacy orders need an authoritative delivery method. An exact repeat returns the existing shipment, including after dispatch or delivery.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_shipments.CreateInput", "description": "New shipment (created in PACKED state)", "summary": "body" } ] } } }, "description": "New shipment (created in PACKED state)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an outbound shipment", "tags": [ "shipments" ] } }, "/shipments/carrier-summary": { "get": { "description": "Counts orders (not shipments) of one delivery company for one day: pending (still has a packed shipment of the company and its latest carrier booking is not rejected or unreachable), failed (still packed and the latest booking was rejected or unreachable), pushed (the company's shipments are dispatched or delivered with the latest booking sent on that date, falling back on the delivery basis to the accepted delivery_selection.date when no delivery date was sent, and no shipment of the order is still packed) and undated (open orders whose date on the basis is unknown, including orders Orders no longer has). Shipments dispatched without a carrier booking count as pushed on the delivery basis by their delivery selection date. Only YYYY-MM-DD dates are placed on a day. An open order's day is the latest booking's sent intake_date or delivery_date, then on the delivery basis delivery_selection.date, then Orders (production_date on the intake basis; delivery selection date, then expected_delivery_date on the delivery basis). Results are narrowed to the caller's geographic scope. Requires shipment.read. data = internal_modules_shipments.CarrierPushSummary", "parameters": [ { "description": "Delivery company code (case-insensitive); must be a catalogued delivery company", "in": "query", "name": "carrier", "required": true, "schema": { "type": "string" } }, { "description": "Day to summarize (YYYY-MM-DD)", "in": "query", "name": "date", "required": true, "schema": { "format": "date", "type": "string" } }, { "description": "Date the orders are counted on. Defaults to intake_date when the company's booking request carries the intake date (BeCool Couriers), otherwise delivery_date (Detrack).", "in": "query", "name": "basis", "schema": { "enum": [ "intake_date", "delivery_date" ], "type": "string" } }, { "description": "Market code", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_shipments.CarrierPushSummaryResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR with details.field carrier (missing or not a catalogued delivery company), date or basis" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT with details.reason too_many_shipments when a shipment set exceeds 5000; narrow by market_code or depot_code" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Shipment or delivery-company catalog lookup failed" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Delivery-company catalog or configuration, or Orders, unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Summarize one delivery company's pushes for a day", "tags": [ "shipments" ] } }, "/shipments/{id}": { "get": { "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an outbound shipment", "tags": [ "shipments" ] } }, "/shipments/{id}/carrier-bookings": { "get": { "description": "Pages the append-only booking attempts that covered the shipment, newest first. data = { items: courier.CarrierBookingAttempt[], page: {...} }", "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [courier.CarrierBookingAttempt], page: {...} }" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "List a shipment's carrier booking attempts", "tags": [ "shipments" ] } }, "/shipments/{id}/deliver": { "post": { "description": "Transitions DISPATCHED to DELIVERED and transactionally enqueues one delivered fact; the final authoritative container shipment also enqueues the order-completed fact.", "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "shipment is not in DISPATCHED state, or linked order cannot be marked delivered" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Mark a dispatched shipment delivered", "tags": [ "shipments" ] } }, "/shipments/{id}/dispatch": { "post": { "description": "Transitions PACKED to DISPATCHED and transactionally enqueues tracking-updated and shipped facts. Idempotent when retried with the same tracking number. An optional carrier names a catalogued delivery company and overrides the create-time value; omitting it preserves the recorded carrier.", "parameters": [ { "description": "Shipment id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_shipments.dispatchReq", "description": "Tracking number and optional carrier", "summary": "body" } ] } } }, "description": "Tracking number and optional carrier", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "shipment is not in PACKED state, tracking_number is required, or carrier is not catalogued" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT (details.reason): packing_not_complete, fulfilment_superseded, remainder_unpaid, refund_projection_stale" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Packing or order dispatch authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Dispatch a shipment", "tags": [ "shipments" ] } }, "/sku-series": { "get": { "parameters": [ { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact code filter", "in": "query", "name": "code", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.SKUSeries], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List SKUs", "tags": [ "skus" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.SKUInput", "description": "New SKU", "summary": "body" } ] } } }, "description": "New SKU", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a SKU", "tags": [ "skus" ] } }, "/sku-series/{code}": { "delete": { "parameters": [ { "description": "SKU code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a SKU", "tags": [ "skus" ] }, "get": { "parameters": [ { "description": "SKU code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a SKU by code", "tags": [ "skus" ] }, "put": { "description": "Code is immutable. sku_codes is move-in-only: supplied products are conditionally added or moved to this destination.", "parameters": [ { "description": "SKU code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.SKUInput", "description": "SKU patch", "summary": "body" } ] } } }, "description": "SKU patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a SKU", "tags": [ "skus" ] } }, "/sku-series/{code}/products": { "get": { "description": "Resolves the SKU-series master first, then returns canonical products whose stored classification.sku_series_code equals the supplied series code. Membership is independent of the product-code prefix. This Supply-owned catalogue read does not request Insights or enrich sales.", "parameters": [ { "description": "SKU code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [productView], page: {...} }" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "List staff product views for a SKU master", "tags": [ "skus" ] } }, "/stock/adjustments": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.AdjustInput", "description": "Adjustment details", "summary": "body" } ] } } }, "description": "Adjustment details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "validation failure or insufficient available stock" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Adjust stock (positive or negative)", "tags": [ "stock" ] } }, "/stock/availability/{productSkuCode}": { "get": { "parameters": [ { "description": "Product SKU code", "in": "path", "name": "productSkuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { sku_code, available }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get total available quantity for a product", "tags": [ "stock" ] } }, "/stock/buckets": { "get": { "parameters": [ { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/packaging.PackageOptionRef" } } }, "description": "Complete immutable package identity, encoded as a JSON object. Must match sku_code when supplied.", "in": "query", "name": "package_option" }, { "description": "Product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Location code", "in": "query", "name": "location_code", "schema": { "type": "string" } }, { "description": "Lot id", "in": "query", "name": "lot_id", "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List stock buckets", "tags": [ "stock" ] } }, "/stock/deficit-correction-snapshot": { "get": { "description": "Requires stock.adjust and workforce location scope. Returns every unresolved deficit obligation needed to attest that the selected bucket has zero physical units. No lot or cost is assigned.", "parameters": [ { "in": "query", "name": "bucket_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "depot_code": { "type": "string" }, "location_code": { "type": "string" }, "on_hand_base_units": { "format": "int64", "type": "integer" }, "selections": { "items": { "$ref": "#/components/schemas/stock.POSDeficitCorrectionSelection" }, "type": "array" }, "sku_code": { "type": "string" } }, "required": [ "bucket_id", "sku_code", "depot_code", "location_code", "on_hand_base_units", "bucket_revision", "selections" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Revisioned bucket and exact obligation selections" }, "400": { "description": "Invalid bucket ID" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing permission or geographic scope" }, "409": { "description": "Bucket or obligations cannot be reconciled" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a zero-count POS deficit correction snapshot", "tags": [ "stock" ] } }, "/stock/deficit-corrections": { "post": { "description": "Requires stock.adjust and workforce location scope. All outstanding obligations must match the snapshot. This changes the signed balance to zero and records unresolved cost; it does not assign lot or valuation.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "bucket_id": { "type": "string" }, "counted_base_units": { "enum": [ 0 ], "format": "int64", "type": "integer" }, "expected_bucket_revision": { "format": "int64", "minimum": 1, "type": "integer" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "type": "string" }, "reason": { "maxLength": 1000, "minLength": 1, "type": "string" }, "selections": { "items": { "$ref": "#/components/schemas/stock.POSDeficitCorrectionSelection" }, "minItems": 1, "type": "array" } }, "required": [ "bucket_id", "expected_bucket_revision", "counted_base_units", "reason", "idempotency_key", "selections" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/stock.POSDeficitCorrectionResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Audited correction or exact replay" }, "400": { "description": "Invalid correction" }, "401": { "description": "Unauthorized" }, "403": { "description": "Missing permission or geographic scope" }, "409": { "description": "Snapshot changed or obligations do not reconcile" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a zero-count correction for a POS deficit", "tags": [ "stock" ] } }, "/stock/location-overwrite-history": { "get": { "description": "Superadmin with verified global workforce scope only. Pages use descending receipt IDs and form a live view; refresh the first page to see newer receipts.", "parameters": [ { "in": "query", "name": "sku_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "depot_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "location_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Lowercase ObjectID from next_cursor.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/stock.LocationOverwriteHistoryPage" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "No-store history from the existing overwrite receipts" }, "400": { "description": "Invalid query" }, "401": { "description": "Authentication required" }, "403": { "description": "Superadmin and global workforce scope required" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a location's stock overwrite audit history", "tags": [ "stock" ] } }, "/stock/location-overwrite-returns": { "get": { "description": "Superadmin global workforce only. Actual return receipts and their remaining quantities are pinned to the overwrite snapshot bucket revision and stock fence. Receipt IDs do not identify lots or individual units.", "parameters": [ { "in": "query", "name": "bucket_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "stock_fence", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "next_cursor": { "type": "string" }, "returns": { "items": { "properties": { "order_item_id": { "type": "string" }, "order_number": { "type": "string" }, "received_at": { "format": "date-time", "type": "string" }, "received_base_units": { "format": "int64", "type": "integer" }, "receiving_id": { "type": "string" }, "refund_operation_id": { "type": "string" }, "remaining_base_units": { "format": "int64", "type": "integer" } }, "required": [ "receiving_id", "order_number", "order_item_id", "refund_operation_id", "received_at", "received_base_units", "remaining_base_units" ], "type": "object" }, "type": "array" }, "stock_fence": { "format": "int64", "type": "integer" } }, "required": [ "bucket_id", "bucket_revision", "stock_fence", "returns" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Verified return options; next_cursor indicates another page." }, "400": { "description": "Invalid query" }, "401": { "description": "Unauthorized" }, "403": { "description": "Superadmin global workforce required" }, "409": { "description": "Snapshot changed; reload" } }, "security": [ { "BearerAuth": [] } ], "summary": "List unknown-identity return receipts for a count loss", "tags": [ "stock" ] } }, "/stock/location-overwrite-snapshot": { "get": { "description": "Superadmin only. Returns the location balance and all buckets from a fenced snapshot, with a maximum of 200 buckets.", "parameters": [ { "in": "query", "name": "sku_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "depot_code", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "location_code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/stock.LocationOverwriteSnapshot" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "data = {balance, buckets}; quantities and revisions are in base units." }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Location balance not found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a complete revisioned stock location snapshot", "tags": [ "stock" ] } }, "/stock/location-overwrite-units": { "get": { "description": "Superadmin global workforce only. Units are candidates, not proof of presence. Every page is pinned to the overwrite snapshot stock fence and bucket revision.", "parameters": [ { "in": "query", "name": "bucket_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "expected_revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "stock_fence", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "bucket_id": { "type": "string" }, "bucket_revision": { "format": "int64", "type": "integer" }, "next_cursor": { "type": "string" }, "stock_fence": { "format": "int64", "type": "integer" }, "units": { "items": { "properties": { "base_units": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "unit_label_code": { "type": "string" } }, "required": [ "id", "base_units" ], "type": "object" }, "type": "array" } }, "required": [ "bucket_id", "bucket_revision", "stock_fence", "units" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Candidate identities; next_cursor is present when another page exists." }, "400": { "description": "Invalid query" }, "401": { "description": "Unauthorized" }, "403": { "description": "Superadmin global workforce required" }, "409": { "description": "Snapshot changed; reload" } }, "security": [ { "BearerAuth": [] } ], "summary": "List tracked units for a physical count", "tags": [ "stock" ] } }, "/stock/location-overwrites": { "post": { "description": "Superadmin only. Each current bucket requires an explicit target and revision. A negative bucket can be counted to zero with the complete current deficit-correction selections; its cost remains unresolved. For a tracked bucket, a complete set of actually observed unit IDs can record a downward count and reconcile an eligible single-bucket packing hold. Staff may add identified units to an existing tracked lot when all existing units are present. For unidentified returns staff select source receipts for a multi-source count loss. Mixed tracked loss and gain, held reservations spanning buckets, negative targets and unsupported unresolved deficits remain rejected. Other gains require an existing lot and explicit net-goods cost.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/stock.LocationOverwriteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/stock.LocationOverwriteResult" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Audit result or idempotent replay" }, "400": { "description": "Invalid request or unsupported valuation" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "409": { "conflicting idempotency key or unsupported deficit": null, "description": "Stale snapshot" } }, "security": [ { "BearerAuth": [] } ], "summary": "Overwrite a stock location total", "tags": [ "stock" ] } }, "/stock/lot-reassignments": { "post": { "description": "Corrects which lot the books show at one location: moves N base units\nfrom the bucket of from_lot_id to the bucket of to_lot_id with the same\nlocation, package option, handling unit, condition and disposition. The\ndestination bucket is created when it does not exist yet. Both bucket\nchanges and the movement commit in one transaction.\n\nRequires stock.adjust. The location must resolve inside the caller's\ngeographic scope; a location outside it answers 404 like a missing one.\n\nOne movement is recorded per reassignment: type LOT_REASSIGNMENT with\nthe source and destination bucket ids (both at the same location),\nlot_id set to from_lot_id (the destination lot is the lot of\ndestination_bucket_id), cause.type lot_reassignment with cause.id the\nreassignment id, and reason_code LOT_CORRECTION unless another reason is\ngiven. GET /stock/movements?type=LOT_REASSIGNMENT lists reassignments.\nThe movement is value-neutral: no net_goods_cost is taken and the units\ncarry the source lot's unit cost to the destination lot. It is never an\nESL replenishment. Each bucket publishes the same stock events an\nadjustment would.\n\nEither bucket being unit tracked is refused (409), as for adjustments.\nSafe to retry with the same idempotency_key and body; a retry returns\nthe original result with replayed true.", "operationId": "reassignStockLot", "requestBody": { "content": { "application/json": { "example": { "cause": { "id": "lots-card", "type": "admin_manual" }, "composition": { "components": [ { "base_units": 3, "handling_unit": "EACH", "package_count": 3, "package_option": { "code": "EACH", "sku_code": "A0001", "version": 1 }, "units_per_package": 1 } ], "total_base_units": 3 }, "condition": "GOOD", "disposition": "STANDARD_SELLABLE", "expected_from_revision": 7, "from_lot_id": "6643f2a1c9e77b0012ab34cd", "handling_unit": "EACH", "idempotency_key": "2f7a0c1e-lot-correction", "location": { "depot_code": "MEL-01", "location_code": "A-01-01" }, "note": "Old lot still on shelf", "package_option": { "code": "EACH", "sku_code": "A0001", "version": 1 }, "sku_code": "A0001", "to_lot_id": "6643f2a1c9e77b0012ab34ce" }, "schema": { "$ref": "#/components/schemas/internal_modules_stock.LotReassignmentInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.LotReassignmentResponse" } } }, "description": "The reassignment and its single movement (also returned, with replayed true, for an identical retry)." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR - a required field is missing, the grain is invalid,\nthe composition does not match the package option, the two lots are\nthe same, or a lot belongs to another SKU. INSUFFICIENT_STOCK - the\nsource would go below its reserved units." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "UNAUTHORIZED - missing or invalid bearer token, or no authenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN - the token does not grant stock.adjust, or the principal has no geographic scope." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND - the location is missing or outside the caller's scope, a lot does not exist, or no source bucket has this grain." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT - expected_from_revision or expected_to_revision is stale,\neither bucket is unit tracked, or the idempotency_key was used with a\ndifferent body." } }, "security": [ { "BearerAuth": [] } ], "summary": "Move base units from one lot to another at one location", "tags": [ "stock" ] } }, "/stock/lots": { "get": { "parameters": [ { "description": "Product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Supplier lot code", "in": "query", "name": "supplier_lot_code", "schema": { "type": "string" } }, { "description": "Manufacturer lot code", "in": "query", "name": "manufacturer_lot_code", "schema": { "type": "string" } }, { "description": "Date mark kind", "in": "query", "name": "date_mark_kind", "schema": { "enum": [ "BEST_BEFORE", "USE_BY", "EXPIRY" ], "type": "string" } }, { "description": "Include lots past their date mark", "in": "query", "name": "include_past_date_mark", "schema": { "type": "boolean" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List stock lots", "tags": [ "stock" ] } }, "/stock/lots/{lotId}/date-mark": { "patch": { "description": "Corrects the date mark of one inventory lot. A date mark is the date\nprinted on the product: BEST_BEFORE is a quality date (the product may\nstill be safe after it, but quality is no longer guaranteed), while\nEXPIRY is a use-by / safety date (stock past it must not be sold). The\nmark is per lot, so one edit applies to every bucket of that lot in every\ndepot.\n\nEvery staff level may call this route. Requires the\ninventory.date_mark.write permission (superAdmin bypass retained); it does\nnot need, and is not granted by, stock.adjust or catalog permissions. The\ncaller's geographic (depot/market) scope applies: a scoped principal may\nedit only a lot that currently has positive on-hand stock in a depot\ninside its scope. A depot-scoped principal reaches its own depots. A\nmarket-scoped principal (for example marketing) reaches every depot that\ncurrently serves its market, using the active, in-window depot-to-market\nassociations managed under /depot-markets. A country-scoped principal\nreaches the depots in its country. A lot outside the caller's scope answers\n404 exactly like a missing lot.\n\nA date_mark_at in the past is accepted; the lot's stock then counts as\nexpired and is no longer offered for sale. An EXPIRY date mark in the past\nalso lists the lot's stock in GET /expiry/expired-lots for transfer to an\nexpiry hold.\n\nThe edit moves no stock and records no stock movement. It is recorded\nin the audit log with the previous and new date mark. A real change\nadvances the lot's revision, so the next date-mark threshold sweep\nre-evaluates the lot and its expiry and sale-eligibility decisions use\nthe new date. Once SellingProduct.expiry_date is wired from lot date\nmarks, it reflects the corrected date as well.\n\nSafe to retry: repeating the same body returns the same lot and writes\nnothing further. Clearing a lot that has no date mark is also a no-op.", "operationId": "setStockLotDateMark", "parameters": [ { "description": "Inventory lot id (24-character hexadecimal ObjectId), as returned by GET /stock/lots.", "in": "path", "name": "lotId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "clear": { "summary": "Clear the date mark", "value": { "date_mark": null } }, "setBestBefore": { "summary": "Set a BEST_BEFORE (quality) date", "value": { "date_mark": { "date_mark_at": "2027-03-31T13:00:00Z", "kind": "BEST_BEFORE", "timezone": "Australia/Sydney" } } }, "setExpiry": { "summary": "Set an EXPIRY (use-by / safety) date", "value": { "date_mark": { "date_mark_at": "2026-12-14T13:00:00Z", "kind": "EXPIRY", "timezone": "Australia/Melbourne" } } } }, "schema": { "$ref": "#/components/schemas/internal_modules_stock.LotDateMarkInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "data": { "created_at": "2026-10-02T03:15:00Z", "created_by": "usr_receiver", "date_mark": { "date_mark_at": "2027-03-31T13:00:00Z", "kind": "BEST_BEFORE", "timezone": "Australia/Sydney" }, "id": "6643f2a1c9e77b0012ab34cd", "received_at": "2026-10-02T03:15:00Z", "sku_code": "SKU-000123", "supplier_lot_code": "SUP-LOT-778", "updated_at": "2026-11-01T00:00:00Z", "updated_by": "usr_staff" }, "success": true }, "schema": { "$ref": "#/components/schemas/internal_modules_stock.LotDateMarkResponse" } } }, "description": "The updated lot. date_mark is omitted when it was cleared." }, "400": { "content": { "application/json": { "examples": { "invalidKind": { "value": { "error": { "code": "VALIDATION_ERROR", "message": "date_mark.kind must be BEST_BEFORE or EXPIRY" }, "success": false } }, "invalidTimezone": { "value": { "error": { "code": "VALIDATION_ERROR", "message": "date_mark.timezone must be an IANA timezone" }, "success": false } }, "missingKey": { "value": { "error": { "code": "VALIDATION_ERROR", "details": { "date_mark": "is required" }, "message": "date_mark is required; send null to clear it" }, "success": false } } }, "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: the date_mark key is missing (details.date_mark =\n\"is required\"), kind is not BEST_BEFORE or EXPIRY, date_mark_at is\nmissing, zero or not RFC 3339, timezone is not an IANA time-zone name,\nor the body has unknown fields or is not one JSON object." }, "401": { "content": { "application/json": { "example": { "error": { "code": "UNAUTHORIZED", "message": "unauthenticated" }, "success": false }, "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "UNAUTHORIZED - missing or invalid bearer token, or no authenticated actor." }, "403": { "content": { "application/json": { "example": { "error": { "code": "FORBIDDEN", "details": { "required": "inventory.date_mark.write" }, "message": "permission denied" }, "success": false }, "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "FORBIDDEN - the token does not grant inventory.date_mark.write\n(details.required names it), or the workforce principal has no\nresolvable geographic scope." }, "404": { "content": { "application/json": { "example": { "error": { "code": "NOT_FOUND", "message": "inventory lot not found" }, "success": false }, "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND - no such lot, or the lot has no on-hand stock in a depot inside the caller's scope (its own depot, or a depot currently serving its market)." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT - the lot kept changing concurrently; retry the same request." } }, "security": [ { "BearerAuth": [] } ], "summary": "Set or clear a lot's best-before / expiry date mark", "tags": [ "stock" ] } }, "/stock/movements": { "get": { "parameters": [ { "description": "Product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Movement type", "in": "query", "name": "type", "schema": { "enum": [ "RECEIPT", "TRANSFER", "STAGE", "UNSTAGE", "PACKAGE_CONVERSION", "SALE_COMMIT", "RETURN", "QUALITY_HOLD", "QUALITY_RELEASE", "QUALITY_REJECT", "ADJUSTMENT", "RETURN_TO_VENDOR", "SCRAP", "LOT_REASSIGNMENT" ], "type": "string" } }, { "description": "Reference type", "in": "query", "name": "reference_type", "schema": { "type": "string" } }, { "description": "Reference id", "in": "query", "name": "reference_id", "schema": { "type": "string" } }, { "description": "Created-by actor", "in": "query", "name": "created_by", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown movement type" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List stock movements (audit trail)", "tags": [ "stock" ] } }, "/stock/movements/filter-options": { "get": { "description": "Requires stock.read under the same authenticated live-session and scope-resolution middleware as the owner list. Reuses exactly its record filters. These existing lists currently have no row-level geographic predicate; this endpoint does not add one or claim geographic isolation. Explicit whitelist only. Returns exact stored scalar strings including service actors; no user lookup, labels, inferred actors or enum expansion. Blank, non-string, control-containing and values over 512 UTF-8 bytes are omitted. Server groups/sorts/limits to limit+1 rows, disables disk spilling, and uses a five-second context deadline. Query pins are all ANDed. Keyset pages are not a snapshot across concurrent record changes; restart discovery after changing filters. Response uses private, no-store caching.", "operationId": "stockMovementFilterOptions", "parameters": [ { "in": "query", "name": "field", "required": true, "schema": { "enum": [ "cause_type", "performed_by", "cause_id" ], "type": "string" } }, { "description": "Literal case-insensitive substring, no regex interpretation. Maximum 100 Unicode characters and 512 UTF-8 bytes.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Strict decimal integer; no sign, whitespace or leading zero.", "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exclusive binary-order keyset boundary; at most 512 UTF-8 bytes. Preserve the original value including spaces and case.", "in": "query", "name": "after", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "sku_code", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "type", "schema": { "$ref": "#/components/schemas/warehouse_enums.StockMovementType" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. Required and nonblank when field=cause_id.", "in": "query", "name": "cause_type", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "cause_id", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "performed_by", "schema": { "maxLength": 512, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/filteroptions.Result" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Distinct stored values in ascending binary order, maximum limit values. Empty results use items: []." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid field, malformed/repeated/unknown query parameter, invalid enum, missing cause_type pin, query over 8 KiB, or query value over bounds/containing control characters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated or missing workforce role." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Named read permission or existing staff scope-resolution gate denied." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Discovery store unavailable, failed query or bounded aggregation timeout; no partial result." } }, "security": [ { "BearerAuth": [] } ], "summary": "Discover record-backed stock movement filter values", "tags": [ "stock" ] } }, "/stock/opening-receipts": { "post": { "description": "Requires stock.adjust and explicit destination authorization. Removed after all cutover outcomes and retries are reconciled.", "operationId": "createOpeningReceipt", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpeningReceiptInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/inventory.StockMovement" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Success" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Permission or scope rejected" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Destination or product missing" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Identity or generation conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transaction or owner evidence unavailable" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Required owner unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a temporary opening inventory receipt" } }, "/stock/package-conversions": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.ConvertInput", "description": "Base-unit-conserving conversion command", "summary": "body" } ] } } }, "description": "Base-unit-conserving conversion command", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Convert inventory between compatible CASE/EACH package buckets", "tags": [ "stock" ] } }, "/stock/pos-add-backs": { "post": { "description": "Requires pos.access or stock.adjust, with the same store guard as GET /stock/pos-item-locations (store_code must serve market_code; the caller's geographic scope must permit the depot, its state or the market). Puts counted stock of an active product back at a store location. Shortfall first: when the product has open POS shortfall at the depot's POS deficit location (negative no-lot balances), the added base units first settle it with a valued RECEIPT movement into that deficit bucket; its POS cost obligations are attributed to the receipt oldest first and become settled with a resolved cost, each posting the sale's cost as a POS-deficit settlement issue. This settlement is accepted as evidence by the tracked-picking guard exactly like a zero- count deficit correction. Only the remainder raises lot stock, with a valued ADJUSTMENT (gain). Lot rule for the remainder: the newest lot already held at the location; otherwise lot_id when it is one of the store's lot candidates; otherwise a new lot from new_lot. With none of these the request answers 409 NO_LOT_AT_LOCATION with details.location_code only; the till offers lot_candidates from GET /stock/pos-item-locations. No lot is needed when the shortfall takes the whole quantity. Whole packages of package_code stay in that package; units left loose after the shortfall took its share are recorded in the product's smallest package. Cost: costs are keyed by the market's currency (Pricing's market default currency). The product's current acquisition cost in that currency values every movement (cost_source last_acquisition_cost); without one, unit_cost in that currency is required (422 COST_REQUIRED otherwise), is recorded as the product's acquisition cost and values the movements (cost_source request). Net-goods valuation is posted with that explicit cost, so it is resolved, not unresolved. Every write, the cost record, inventory events, availability projection and location balance rebuild commit in one transaction. The same idempotency_key and request replays the original result.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.POSAddBackInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.posAddBackAPIResponse" } } }, "description": "Added back, or the original add-back replayed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid body (VALIDATION_ERROR), such as missing store_code or market_code, quantity not positive, unknown package_code, lot_id with new_lot, invalid or past new_lot.date_mark, unit_cost not positive or not in the market's currency, location not a standard stock location, or net-goods evidence rejected" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing pos.access and stock.adjust, or store outside workforce geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store not POS-eligible for the market or location not an active location of the store (NOT_FOUND), or no active product for product_code (PRODUCT_NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "No lot for the remainder at the location (NO_LOT_AT_LOCATION, details.location_code), idempotency_key reused with a different request, stock or obligations changed concurrently, lot stock at the location in deficit, or shortfall obligations not matching the deficit stock (CONFLICT)" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "The product has no current acquisition cost in the market's currency and the request carries no unit_cost (COST_REQUIRED)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store, product, market currency, cost or valuation authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Put counted stock back at a till's store location", "tags": [ "stock" ] } }, "/stock/pos-count-corrections": { "post": { "description": "Requires pos.access or stock.adjust, with the same store guard as POST /stock/pos-add-backs (store_code must serve market_code; the caller's geographic scope must permit the depot, its state or the market). The till reports the quantity staff counted at one location of the store, in packages of package_code. Current stock is the on-hand of the product's good, standard-sellable, non-negative buckets of that package code at the location; POS shortfall (negative no-lot balances at the depot's POS deficit location) is never counted or touched, and is healed only by add-backs and deficit corrections. The count must be below current stock: an equal count answers 409 CONFLICT (nothing to correct) and a higher count answers 400 VALIDATION_ERROR pointing at POST /stock/pos-add-backs (details.use). The difference is removed earliest date mark first (undated lots, then no-lot stock, last; ties by receipt time and id), each bucket limited to its unreserved units in whole packages. Units held for orders are never removed: when the unreserved units cannot cover the difference the request answers 409 CONFLICT with details.reserved_base_units, details.unreserved_base_units and details.removal_base_units. A location holding unit-tracked or unidentified stock of the package answers 409 CONFLICT; that stock is corrected with the full stock count. Each touched bucket is decremented under its revision and gets one loss ADJUSTMENT movement (cause type pos_count_correction, cause id correction_id, reason_code, note, performed_by the token subject), valued like every other loss; the movements, inventory events, availability projection, location balance rebuild and the command receipt commit in one transaction. The same idempotency_key, till, store and request replays the original result.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.POSCountCorrectionInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.posCountCorrectionAPIResponse" } } }, "description": "Corrected, or the original correction replayed (replayed true)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid body (VALIDATION_ERROR), such as missing store_code, market_code or counted_quantity, counted_quantity negative, unknown package_code, reason_code outside the enum, note too long, location not a standard stock location, or a count above current stock (use POST /stock/pos-add-backs)" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing pos.access and stock.adjust, or store outside workforce geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store not POS-eligible for the market or location not an active location of the store (NOT_FOUND), or no active product for product_code (PRODUCT_NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Nothing to correct (count equals current stock), the correction would remove units reserved for orders, unit-tracked or unidentified stock at the location, stock of the package that does not divide into whole packages or does not match its lots (use the full stock count), idempotency_key reused with a different request or by another till, or stock changed concurrently (CONFLICT)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store, product, stock or valuation authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Correct a till's store location stock down to a shelf count", "tags": [ "stock" ] } }, "/stock/pos-item-locations": { "get": { "description": "Requires pos.access or stock.adjust. The depot named by store_code must serve market_code for in-store carry (404 otherwise), and the caller's workforce geographic scope must permit that depot, its state or that market (403 otherwise), exactly as the POS catalogue reads. Resolves the active product by barcode (the product and package that own it now) or by product_code (its canonical effective package), then lists the store's locations holding good, standard-sellable stock of it outside protected system locations, most on-hand first. has_lot reports an untracked lot bucket an add-back can raise at that location; lot_candidates lists the product's lots held anywhere in the depot, newest first, for locations without one. Negative no-lot balances at the depot's POS deficit location are open POS shortfall and are reported in open_shortfall_base_units, not as stock. Quantities are base units. Success responses are no-store.", "parameters": [ { "description": "Physical depot code of the register.", "in": "query", "name": "store_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Market the register sells in; the store must serve it.", "in": "query", "name": "market_code", "required": true, "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Scanned barcode. Send exactly one of barcode and product_code.", "in": "query", "name": "barcode", "schema": { "maxLength": 128, "minLength": 1, "type": "string" } }, { "description": "Product (SKU) code. Send exactly one of barcode and product_code.", "in": "query", "name": "product_code", "schema": { "maxLength": 128, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.posItemLocationsAPIResponse" } } }, "description": "Product, its locations at the store and open POS shortfall" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing store_code or market_code, not exactly one of barcode and product_code, or an unsupported or repeated parameter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing pos.access and stock.adjust, or store outside workforce geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store not POS-eligible for the market (NOT_FOUND) or no active product for the barcode or product code (PRODUCT_NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Barcode owned by more than one active product package" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store or product authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Locations and on-hand stock of one product at a till's store", "tags": [ "stock" ] } }, "/stock/pos-package-conversions": { "post": { "description": "Requires pos.access or stock.adjust, with the same store guard as GET /stock/pos-item-locations (store_code must serve market_code; the caller's geographic scope must permit the depot, its state or the market). The till's case conversion (\"make it 1 case?\"). The source bucket must belong to the store's depot (404 otherwise) and hold an existing lot (409 NO_LOT_AT_LOCATION otherwise); the destination bucket shares that lot, so no lot is ever created. Base units are conserved exactly as POST /stock/package-conversions, which stays stock.adjust only. The movement cause is pos_package_conversion with the idempotency key as its id. The same idempotency_key and request replays the original conversion with replayed true.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.POSConvertInput" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.posConvertAPIResponse" } } }, "description": "Converted, or the original conversion replayed" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid body, missing store_code or market_code, invalid compositions or destination package" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Missing pos.access and stock.adjust, or store outside workforce geographic scope" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store not POS-eligible for the market, or source bucket unknown or outside the store's depot (NOT_FOUND)" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Source bucket has no lot (NO_LOT_AT_LOCATION, details.location_code), stale revision, incompatible package grain, or idempotency_key reused with a different request (CONFLICT)" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Store authority unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Convert counted till stock into another package within its lot", "tags": [ "stock" ] } }, "/stock/quality-assessments": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.QualityInput", "description": "Quality evidence and target state", "summary": "body" } ] } } }, "description": "Quality evidence and target state", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Assess inventory condition and disposition", "tags": [ "stock" ] } }, "/stock/quality-assessments/{assessmentId}/reduced-sale-approval": { "post": { "description": "A quality assessment records that stock was damaged and moved to REDUCED_SELLABLE. That is an observation, not a decision: this route is the explicit decision to sell it, and it carries the assessed condition band (tier_30, tier_50 or tier_80), the approver, and the instant. Until it exists, reduced-sellable stock fails closed on the sale-eligibility query with DAMAGE_NOT_APPROVED rather than being quoted as standard stock. Unsafe dispositions (QUALITY_HOLD, QUARANTINED, BLOCKED, RECALLED, RETURN_TO_VENDOR, SCRAP) can never be approved. Supply states the band and never a price: the fixed tier-to-multiplier mapping is Pricing's, and is deliberately not one minus the damage percentage.", "parameters": [ { "description": "Quality assessment id", "in": "path", "name": "assessmentId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.ApproveReducedSaleInput", "description": "Approved condition band", "summary": "body" } ] } } }, "description": "Approved condition band", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Approve damaged stock for reduced sale", "tags": [ "stock" ] } }, "/stock/reservation-commits": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReferenceCommand", "description": "Revisioned commit command", "summary": "body" } ] } } }, "description": "Revisioned commit command", "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "No Content" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "reservation is not active" } }, "security": [ { "BearerAuth": [] } ], "summary": "Commit active stock reservations under a reference", "tags": [ "stock" ] } }, "/stock/reservation-releases": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReferenceCommand", "description": "Revisioned release command", "summary": "body" } } }, "description": "Revisioned release command", "required": true }, "responses": { "204": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "No Content" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "reservation is not active" } }, "security": [ { "BearerAuth": [] } ], "summary": "Release active stock reservations under a reference", "tags": [ "stock" ] } }, "/stock/reservations": { "get": { "parameters": [ { "description": "Product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Reservation status", "in": "query", "name": "status", "schema": { "enum": [ "RESERVED", "PARTIALLY_STAGED", "STAGED", "COMMITTED", "RELEASED", "EXPIRED", "CANCELLED" ], "type": "string" } }, { "description": "Reference type", "in": "query", "name": "reference_type", "schema": { "type": "string" } }, { "description": "Reference id", "in": "query", "name": "reference_id", "schema": { "type": "string" } }, { "description": "Exact order number that owns the reservation (for example the Orders order number a hold was placed for).", "in": "query", "name": "order_number", "schema": { "type": "string" } }, { "description": "Exact group order code shared by the parent and child orders of a group order.", "in": "query", "name": "group_order_code", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "unknown reservation status" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List stock reservations", "tags": [ "stock" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_domain_stockops.ReservationCommand", "description": "Offer-bound reservation command", "summary": "body" } ] } } }, "description": "Offer-bound reservation command", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "validation failure" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "An online command that cannot be held in full (INSUFFICIENT_STOCK, details.short_lines), or a conflicting replay, evidence or active reservation (CONFLICT)" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reserve stock against a reference (e.g. an order)", "tags": [ "stock" ] } }, "/stock/returns": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.ReturnInput", "description": "Package-aware return evidence", "summary": "body" } ] } } }, "description": "Package-aware return evidence", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Post a sealed, opened, loose, or damaged order return", "tags": [ "stock" ] } }, "/stock/staging-records": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.StageInput", "description": "Exact allocation staging command", "summary": "body" } ] } } }, "description": "Exact allocation staging command", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Move a frozen allocation into protected online staging", "tags": [ "stock" ] } }, "/stock/transfers": { "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_stock.TransferInput", "description": "Transfer details", "summary": "body" } ] } } }, "description": "Transfer details", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "one transfer movement with source and destination evidence" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "validation failure or insufficient available stock at source" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "no stock at source location" } }, "security": [ { "BearerAuth": [] } ], "summary": "Transfer stock between two locations", "tags": [ "stock" ] } }, "/stock/units": { "get": { "parameters": [ { "description": "Stock bucket id", "in": "query", "name": "bucket_id", "schema": { "type": "string" } }, { "description": "Product SKU code", "in": "query", "name": "sku_code", "schema": { "type": "string" } }, { "description": "Exact unit label code", "in": "query", "name": "unit_label_code", "schema": { "type": "string" } }, { "description": "Return only available stock units before counting and pagination. Omitted or false preserves the default non-consumed unit read. Malformed supplied values are rejected.", "in": "query", "name": "available_only", "schema": { "default": false, "type": "boolean" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_stock.stockUnitListAPIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid query parameter" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List optional stock-unit evidence", "tags": [ "stock" ] } }, "/storage-locations": { "get": { "parameters": [ { "description": "Depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Location code", "in": "query", "name": "location_code", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage_type", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "List storage locations", "tags": [ "depots" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.LocationInput", "description": "Storage location", "summary": "body" } ] } } }, "description": "Storage location", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a non-system storage location", "tags": [ "depots" ] } }, "/storage-locations/bulk": { "patch": { "description": "Requires location.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateStorageLocations", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depots.BulkLocationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/depots.BulkLocationResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "location.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_locations is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update storage location activation or storage type", "tags": [ "storage-locations" ] } }, "/storage-locations/{depotCode}/{locationCode}": { "delete": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Location code", "in": "path", "name": "locationCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.DeleteInput", "description": "Expected revision", "summary": "body" } ] } } }, "description": "Expected revision", "required": true }, "responses": { "204": { "description": "No Content" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a non-system storage location", "tags": [ "depots" ] }, "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Location code", "in": "path", "name": "locationCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a depot-qualified storage location", "tags": [ "depots" ] }, "patch": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Location code", "in": "path", "name": "locationCode", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_depots.UpdateLocationInput", "description": "Patch", "summary": "body" } ] } } }, "description": "Patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a non-system storage location", "tags": [ "depots" ] } }, "/storage-locations/{depotCode}/{locationCode}/resolve": { "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Location code", "in": "path", "name": "locationCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" } }, "security": [ { "BearerAuth": [] } ], "summary": "Resolve a storage location and owning depot", "tags": [ "depots" ] } }, "/storefront/brands": { "get": { "description": "Returns active brands with a distinct count of products in the requested market's approved, effective online catalogue. Eligibility is applied before counts and pagination. Responses are no-store; ETags are checked only after fresh eligibility validation.", "parameters": [ { "description": "Pricing-owned market; omission uses the configured storefront default.", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Case-insensitive localized-name search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Strong or weak ETag from a previous response", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontBrandSummaryAPIResponse" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "304": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not modified; ETag matched If-None-Match" }, "503": { "description": "Market eligibility or closing freshness is unavailable; no authoritative empty result is returned." } }, "summary": "List public storefront brands", "tags": [ "storefront" ] } }, "/storefront/brands/{slug}/products": { "get": { "description": "Confirmed in-stock products precede out-of-stock and unknown products before pagination. The requested sort applies within each availability group. Availability is evaluated for the current market and exact canonical retail package; unavailable stock evidence returns 503.", "parameters": [ { "description": "Brand slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [storefrontProduct], page: {...} }" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List retail-visible products for a brand slug", "tags": [ "storefront" ] } }, "/storefront/capabilities": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Customer-safe capability flags; new surfaces default disabled" } }, "summary": "Get fail-closed storefront feature availability (including restock_alerts)", "tags": [ "storefront" ] } }, "/storefront/collections": { "get": { "description": "Returns stable collection codes, localized-name arrays, public slugs, category tags, and no audit metadata. Missing translations are not synthesized. Sending market_code or exclude_empty_tags opts into per-market counts. The market is then resolved as for /storefront/brands, and every category tag row carries active_product_count. That count is the page.total_items of /storefront/products?market_code=\u0026collection=\u0026category= for that collection and tag. Without either parameter no market is resolved, no count is served and the response is unchanged. Counted responses are no-store. Collections are ordered by the admin collection order (display_order, then name), and each collection's category tags by that collection's tag order.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Pricing-owned market whose active products are counted on each category tag; omission (with exclude_empty_tags sent) uses the configured storefront default.", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Single true, false, 1 or 0. True omits category tags whose active_product_count is 0; a collection stays on its page even when no tag remains, so paging and total_items count collections as before. Sending it (either value) also serves active_product_count.", "in": "query", "name": "exclude_empty_tags", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [storefrontCollection], page: {...} }; every item includes its stable code (COL0001), even without category tags." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "exclude_empty_tags is not a single true, false, 1 or 0 value, or market_code does not name a known market." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Counts were requested and market eligibility, the default market or closing freshness is unavailable; no authoritative counts are returned." } }, "summary": "List public storefront collections", "tags": [ "storefront" ] } }, "/storefront/me/wish-proposals": { "get": { "parameters": [ { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "ETag from a previous response; a match returns 304 without a body", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List the authenticated retail account's private wish proposals", "tags": [ "wishes" ] } }, "/storefront/product-selections": { "get": { "description": "Public. Lists published, non-deleted selections ordered by display_order ascending, then name, then code. With preview_limit \u003e 0 each item also carries up to preview_limit products eligible in the requested market (curated order) and total_products, so a home page needs one call per render. Responses are no-store. Product previews place confirmed in-stock products first, preserving curated position within each availability group. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Filter by kind; omitted returns both kinds", "in": "query", "name": "kind", "schema": { "$ref": "#/components/schemas/selection_enums.ProductSelectionKind" } }, { "description": "Number of inline preview products per selection (0 = no products or total_products fields)", "in": "query", "name": "preview_limit", "schema": { "default": 0, "maximum": 12, "minimum": 0, "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Items per page (default 50, max 200; max 20 when preview_limit \u003e 0, larger values are capped to 20)", "in": "query", "name": "page_size", "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductSelectionPageAPIResponse" } } }, "description": "data = { items: [storefrontProductSelection], page: {...} }", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; unknown kind, preview_limit outside 0..12, or unknown market_code" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; market eligibility unavailable or changed during the read, retry" } }, "summary": "List published product selections", "tags": [ "storefront" ] } }, "/storefront/product-selections/{slug}": { "get": { "description": "Public. Returns one published, non-deleted selection without products; use /storefront/product-selections/{slug}/products for its product page.", "parameters": [ { "description": "Selection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductSelectionAPIResponse" } } }, "description": "OK (products and total_products are omitted)", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown, draft, archived or soft-deleted selection" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "summary": "Get a published product selection", "tags": [ "storefront" ] } }, "/storefront/product-selections/{slug}/products": { "get": { "description": "Public. Lists the selection's members that are eligible in the requested market, with every /storefront/products filter applied within the membership. Eligibility is applied before totals and pagination. sort_by=curated (the default) keeps the admin-set order. An empty membership answers an empty page. Responses are no-store. Confirmed in-stock products precede out-of-stock and unknown products before pagination. Curated order or the requested sort applies within each availability group; descending order never reverses availability priority. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Selection slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage_type", "schema": { "type": "string" } }, { "description": "Exact immutable brand slug filter", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Exact barcode match", "in": "query", "name": "barcode", "schema": { "type": "string" } }, { "description": "NEW or RESTOCKED", "in": "query", "name": "lifecycle_tag", "schema": { "type": "string" } }, { "description": "When true, only products whose enabled preorder policy is currently open", "in": "query", "name": "preorder_available", "schema": { "type": "boolean" } }, { "description": "When true, only products with a currently effective promotion", "in": "query", "name": "on_promotion", "schema": { "type": "boolean" } }, { "description": "When true, only products whose storefront_display.expiry is present, i.e. whose earliest sellable lot falls inside the effective soon-expiry lead days of their market listing (listing expiry_lead_days_override, else the market's expiry_lead_days, else 30). The product's soon-expiry merchandising policy does not affect membership.", "in": "query", "name": "soon_expiry", "schema": { "type": "boolean" } }, { "description": "curated (default; admin-set position), name, newest, restocked, popularity (aliases best_selling, best_sellers), or updated_at (alias updated). Empty, relevance or an unrecognised value means curated; price answers 400.", "in": "query", "name": "sort_by", "schema": { "default": "curated", "type": "string" } }, { "description": "asc or desc. curated and name default to asc (desc reverses the curated order); other sorts default to desc.", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "default": 1, "minimum": 1, "type": "integer" } }, { "description": "Items per page (default 50, max 200)", "in": "query", "name": "page_size", "schema": { "default": 50, "maximum": 200, "minimum": 1, "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductPageAPIResponse" } } }, "description": "data = { items: [storefrontProduct], page: {...} }", "headers": { "Cache-Control": { "schema": { "const": "no-store", "type": "string" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR; sort_by=price or unknown market_code" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found; unknown, draft, archived or soft-deleted selection, or unknown brand_slug" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable; market eligibility or sales evidence (popularity) unavailable, retry" } }, "summary": "List products in a published product selection", "tags": [ "storefront" ] } }, "/storefront/products": { "get": { "description": "Confirmed in-stock products precede out-of-stock and unknown products before pagination, for all supported filters and sorts. Requested sort and direction apply within each availability group. Availability uses the current market and exact canonical retail package; unavailable stock evidence returns 503. Promotion membership remains Pricing-owned and on_promotion=true returns an empty page.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact immutable brand slug filter", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Exact barcode match for scanner-driven lookup", "in": "query", "name": "barcode", "schema": { "type": "string" } }, { "description": "NEW or RESTOCKED", "in": "query", "name": "lifecycle_tag", "schema": { "type": "string" } }, { "description": "When true, only products whose enabled preorder policy is currently open", "in": "query", "name": "preorder_available", "schema": { "type": "boolean" } }, { "description": "When true, only products with a currently effective promotion", "in": "query", "name": "on_promotion", "schema": { "type": "boolean" } }, { "description": "When true, only products whose storefront_display.expiry is present, i.e. whose earliest sellable lot falls inside the effective soon-expiry lead days of their market listing (listing expiry_lead_days_override, else the market's expiry_lead_days, else 30). The product's soon-expiry merchandising policy does not affect membership.", "in": "query", "name": "soon_expiry", "schema": { "type": "boolean" } }, { "description": "relevance, name, newest, restocked, popularity, or updated_at. With a category filter, omitted or relevance lists the category's saved product order (PUT /category-tags/{collectionSlug}/{categorySlug}/products/order); products it does not name follow in the default order.", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [storefrontProduct], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List active storefront products", "tags": [ "storefront" ] } }, "/storefront/products/batch": { "post": { "description": "Resolves normalized, deduplicated SKU codes in request order by default. With sort_by=newest, returned products are ordered by their market listing date descending, with undated products last and SKU ascending for equal dates. Missing SKU codes remain in request order. Listing dates are not exposed. With sort_by=availability, products that can be bought now come first and the rest after, each group keeping request order. A product counts when its commercial.stock_state is in_stock or its storefront_display.preorder.status is open. out_of_stock, unknown (for example after a failed stock lookup) and products without a stock projection follow.", "parameters": [ { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } }, { "description": "Optional ordering. Whitespace is trimmed and case is ignored; absent or blank preserves request order. newest orders by market listing date; availability puts in-stock and open-preorder products first. Other values return a validation error before dependency calls.", "in": "query", "name": "sort_by", "schema": { "enum": [ "newest", "availability" ], "example": "availability", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductBatchRequest", "description": "Ordered product SKU codes", "summary": "body" } ] } } }, "description": "Ordered product SKU codes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" } }, "summary": "Resolve a customer-safe product batch by ordered SKU codes", "tags": [ "storefront" ] } }, "/storefront/products/new": { "get": { "description": "Active retail products carrying the NEW lifecycle tag in the resolved market, whose listing became available within the last 14 days. The path fixes the tag; there is no lifecycle_tag parameter. Confirmed in-stock products precede out-of-stock and unknown products before pagination. Listing date or the requested sort applies within each availability group. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact immutable brand slug filter", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Exact barcode match for scanner-driven lookup", "in": "query", "name": "barcode", "schema": { "type": "string" } }, { "description": "When true, only products whose enabled preorder policy is currently open", "in": "query", "name": "preorder_available", "schema": { "type": "boolean" } }, { "description": "When true, only products with a currently effective promotion", "in": "query", "name": "on_promotion", "schema": { "type": "boolean" } }, { "description": "When true, only products whose storefront_display.expiry is present, i.e. whose earliest sellable lot falls inside the effective soon-expiry lead days of their market listing (listing expiry_lead_days_override, else the market's expiry_lead_days, else 30). The product's soon-expiry merchandising policy does not affect membership.", "in": "query", "name": "soon_expiry", "schema": { "type": "boolean" } }, { "description": "relevance, name, newest, restocked, popularity, or updated_at; newest when absent", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [storefrontProduct], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List new storefront products", "tags": [ "storefront" ] } }, "/storefront/products/restocked": { "get": { "description": "Active retail products in the resolved market carrying the RESTOCKED lifecycle tag, restocked within the last 14 days. The path fixes the tag; there is no lifecycle_tag parameter. Confirmed in-stock products precede out-of-stock and unknown products before pagination. Restock recency or the requested sort applies within each availability group. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact immutable brand slug filter", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Exact barcode match for scanner-driven lookup", "in": "query", "name": "barcode", "schema": { "type": "string" } }, { "description": "When true, only products whose enabled preorder policy is currently open", "in": "query", "name": "preorder_available", "schema": { "type": "boolean" } }, { "description": "When true, only products with a currently effective promotion", "in": "query", "name": "on_promotion", "schema": { "type": "boolean" } }, { "description": "When true, only products whose storefront_display.expiry is present, i.e. whose earliest sellable lot falls inside the effective soon-expiry lead days of their market listing (listing expiry_lead_days_override, else the market's expiry_lead_days, else 30). The product's soon-expiry merchandising policy does not affect membership.", "in": "query", "name": "soon_expiry", "schema": { "type": "boolean" } }, { "description": "relevance, name, newest, restocked, popularity, or updated_at; restocked when absent", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [storefrontProduct], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List restocked storefront products", "tags": [ "storefront" ] } }, "/storefront/products/{skuCode}": { "get": { "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "summary": "Get an active storefront product", "tags": [ "storefront" ] } }, "/storefront/products/{skuCode}/reviews": { "get": { "description": "Public projections contain no customer or moderation identity. Pending and rejected text is hidden while its rating remains in the summary; suppressed reviews contribute neither.", "parameters": [ { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "ETag from a previous response; a match returns 304 without a body", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { rating_summary, items: [], page: {...} }" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "summary": "List public reviews and materialized rating summary", "tags": [ "reviews" ] } }, "/storefront/products/{skuCode}/reviews/me": { "delete": { "parameters": [ { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete the authenticated retail account's review", "tags": [ "reviews" ] }, "get": { "parameters": [ { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "ETag from a previous response; a match returns 304 without a body", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the authenticated retail account's review", "tags": [ "reviews" ] }, "put": { "description": "The first review verifies Orders purchase eligibility. Rating changes apply immediately. Text enters pending moderation; editing approved or rejected text resets it to pending. Suppressed is terminal.", "parameters": [ { "description": "Product SKU code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_reviews.PutInput", "description": "Review score and optional text", "summary": "body" } ] } } }, "description": "Review score and optional text", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "forbidden persona, or REVIEW_QUALIFICATION_REQUIRED" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create or replace the authenticated retail account's review", "tags": [ "reviews" ] } }, "/storefront/rankings/categories/{categoryCode}": { "get": { "description": "Returns the complete Insights seven-day category population for the stable category tag, including zero-sales products. Confirmed in-stock products precede out-of-stock and unknown products before pagination. Insights ordering is preserved within each availability group, and each item's rank remains the original Insights rank. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Stable category tag code", "in": "path", "name": "categoryCode", "required": true, "schema": { "type": "string" } }, { "description": "Sales window (only 7d is currently supported)", "in": "query", "name": "window", "schema": { "default": "7d", "enum": [ "7d" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.categoryLeaderboardAPIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List a category's seven-day product leaderboard", "tags": [ "storefront" ] } }, "/storefront/rankings/top-picks": { "get": { "description": "Confirmed in-stock products precede out-of-stock and unknown products in the complete Insights top-picks population. Insights ordering is preserved within each availability group, and each item's rank remains the original Insights rank. Unavailable stock evidence returns 503.", "parameters": [ { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Product availability could not be classified consistently; retry the request." } }, "summary": "List the global top ten products by seven-day sales", "tags": [ "storefront" ] } }, "/storefront/wholesale/approved/brands": { "get": { "description": "Requires an approved wholesale customer token. Returns only brands with at least one active B2B-listed CASE product that has a currently valid wholesale price for the authenticated organisation and access.", "parameters": [ { "description": "Case-insensitive localized-name search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated sku_code intersection (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.Brand], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List wholesale-listable brands for an approved buyer", "tags": [ "storefront" ] } }, "/storefront/wholesale/approved/brands/{slug}/products": { "get": { "description": "Requires an approved wholesale customer token. Returns only active B2B-listed CASE products with a currently valid wholesale price for the authenticated organisation and access.", "parameters": [ { "description": "Brand slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated sku_code intersection (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProductPage" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List approved-wholesale products for a brand slug", "tags": [ "storefront" ] } }, "/storefront/wholesale/approved/products": { "get": { "description": "Requires an approved wholesale customer token. Returns only products with an active B2B listing, an active CASE option and a currently valid wholesale price for the authenticated organisation and access. Pricing eligibility is applied before count and pagination. Use brand_slug for the exact canonical brand filter.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact canonical lowercase brand slug", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Comma-separated sku_code list (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "NEW or RESTOCKED", "in": "query", "name": "lifecycle_tag", "schema": { "type": "string" } }, { "description": "relevance, name, newest, restocked, or updated_at", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProductPage" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List approved-buyer wholesale storefront products", "tags": [ "storefront" ] } }, "/storefront/wholesale/approved/products/batch": { "post": { "description": "Requires an approved wholesale customer token. Resolves ordered SKU codes for the authenticated organisation and access. Products without an active B2B listing, active CASE option or currently valid wholesale price are reported in missing_sku_codes.", "parameters": [ { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_catalog.storefrontProductBatchRequest" } } }, "description": "Ordered product SKU codes", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProductBatchResponse" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Resolve an approved-buyer wholesale product batch", "tags": [ "storefront" ] } }, "/storefront/wholesale/approved/products/{skuCode}": { "get": { "description": "Requires an approved wholesale customer token. Products without an active B2B listing, active CASE option or currently valid wholesale price for the authenticated organisation and access are not returned.", "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": { "$ref": "#/components/schemas/internal_modules_catalog.approvedStorefrontProduct" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get an approved-buyer wholesale storefront product", "tags": [ "storefront" ] } }, "/storefront/wholesale/brands": { "get": { "description": "Returns active brands that have at least one active B2B-listed CASE product with an approved default wholesale price. No price, stock, buyer, book or organisation data is returned.", "parameters": [ { "description": "Case-insensitive localized-name search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated sku_code intersection (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [classification.Brand], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "summary": "List public wholesale-listable brands", "tags": [ "storefront" ] } }, "/storefront/wholesale/brands/{slug}/products": { "get": { "description": "Returns only active B2B-listed CASE products with an approved default wholesale price. Pricing is applied before count and pagination; commercial fields are omitted.", "parameters": [ { "description": "Brand slug", "in": "path", "name": "slug", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Comma-separated sku_code intersection (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [wholesaleStorefrontProduct], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "summary": "List approved-price-visible public wholesale products for a brand slug", "tags": [ "storefront" ] } }, "/storefront/wholesale/products": { "get": { "description": "Returns only active B2B-listed CASE products with an approved default wholesale price. Pricing eligibility is applied before count and pagination. Use brand_slug for the exact canonical brand filter. Commercial fields are omitted.", "parameters": [ { "description": "Free-text search", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Public collection slug filter", "in": "query", "name": "collection", "schema": { "type": "string" } }, { "description": "Public category tag slug filter", "in": "query", "name": "category", "schema": { "type": "string" } }, { "description": "AMBIENT, CHILLED, or FROZEN", "in": "query", "name": "storage", "schema": { "type": "string" } }, { "description": "Exact canonical lowercase brand slug", "in": "query", "name": "brand_slug", "schema": { "type": "string" } }, { "description": "Comma-separated sku_code intersection (max 200)", "in": "query", "name": "sku_codes", "schema": { "type": "string" } }, { "description": "NEW or RESTOCKED", "in": "query", "name": "lifecycle_tag", "schema": { "type": "string" } }, { "description": "relevance, name, newest, restocked, or updated_at", "in": "query", "name": "sort_by", "schema": { "type": "string" } }, { "description": "asc or desc", "in": "query", "name": "order", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page", "in": "query", "name": "page_size", "schema": { "type": "integer" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [wholesaleStorefrontProduct], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing or catalogue selection unavailable" } }, "summary": "List approved-price-visible wholesale products without commercial fields", "tags": [ "storefront" ] } }, "/storefront/wholesale/products/{skuCode}": { "get": { "description": "Returns an active B2B-listed CASE product only when an approved default wholesale price exists. Commercial fields are omitted.", "parameters": [ { "description": "Product sku_code", "in": "path", "name": "skuCode", "required": true, "schema": { "type": "string" } }, { "description": "Market code to answer this read for; the configured default market applies when absent", "in": "query", "name": "market_code", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Pricing unavailable" } }, "summary": "Get an approved-price-visible wholesale product without commercial fields", "tags": [ "storefront" ] } }, "/storefront/wish-proposals": { "post": { "description": "Proposal identity remains server-side; the returned projection contains no customer, account, or user identifier.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.CreateProposalInput", "description": "New wish proposal", "summary": "body" } ] } } }, "description": "New wish proposal", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit a private product wish for the authenticated retail account", "tags": [ "wishes" ] } }, "/storefront/wishes/active": { "get": { "description": "Returns WISH_NO_ACTIVE_BALLOT when no ballot is open and WISH_CANDIDATE_UNAVAILABLE if an active ballot references an unavailable candidate.", "parameters": [ { "description": "ETag from a previous response; a match returns 304 without a body", "in": "header", "name": "If-None-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "WISH_NO_ACTIVE_BALLOT" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "WISH_CANDIDATE_UNAVAILABLE" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get the active wish ballot, candidates, account selection, advisory flag, and ranking", "tags": [ "wishes" ] } }, "/storefront/wishes/active/votes": { "put": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.ReplaceVotesInput", "description": "Candidate ids to select (an empty array clears the vote)", "summary": "body" } ] } } }, "description": "Candidate ids to select (an empty array clears the vote)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "WISH_NO_ACTIVE_BALLOT" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "WISH_BALLOT_CLOSED or WISH_CANDIDATE_UNAVAILABLE" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Replace the authenticated retail account's vote selection for the active wish ballot", "tags": [ "wishes" ] } }, "/supplier-credits/{creditId}": { "get": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "creditId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCredit" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read a supplier credit", "tags": [ "supplier-invoices" ] } }, "/supplier-credits/{creditId}/cancel": { "post": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "creditId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.CreditLifecycleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCredit" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel a supplier credit atomically", "tags": [ "supplier-invoices" ] } }, "/supplier-credits/{creditId}/confirm": { "post": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "creditId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.CreditLifecycleInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCredit" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Confirm a supplier credit atomically", "tags": [ "supplier-invoices" ] } }, "/supplier-invoices": { "get": { "description": "The authoritative purchase tax record per supplier document. Acquisition and carrying cost are private operational values and never appear here. Exact receipt/item allocations conserve net-goods amounts and base units. Confirmation atomically posts acquisition decisions, inventory valuation and draft-suggestion events. Confirmed documents are immutable; corrections use typed credits or cancellation. Scoped staff may access a document only when all receipt depots are authorized.", "parameters": [ { "description": "Supplier code", "in": "query", "name": "supplier_code", "schema": { "type": "string" } }, { "description": "Supplier invoice number", "in": "query", "name": "invoice_number", "schema": { "type": "string" } }, { "description": "draft | blocked | confirmed | disputed | cancelled", "in": "query", "name": "status", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List recorded supplier invoices", "tags": [ "supplier-invoices" ] }, "post": { "description": "Each line declares its taxability (taxable | gst_free | input_taxed | out_of_scope | unknown) and its inclusive-or-exclusive price basis. Tax is CALCULATED only for an explicitly taxable line with a known basis; an explicit supplier figure is recorded as given and reconciled against the derived one. A line with unknown taxability or an unknown basis is still recorded, but the invoice lands in `blocked` and cannot be confirmed. Supplier identity and business number, the invoice number and date, and an immutable document reference plus SHA-256 are all captured; the supplier-plus-number duplicate key is enforced by a unique index, because recording the same invoice twice double-counts the input tax claim. Input tax is never marked claimable without qualifying tax-invoice evidence. Freight and duty stay on their own line fields and are never blended into a unit cost. Exact receipt/item allocations conserve net-goods amounts and base units. Confirmation atomically posts acquisition decisions, inventory valuation and draft-suggestion events. Confirmed documents are immutable; corrections use typed credits or cancellation. Scoped staff may access a document only when all receipt depots are authorized.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_purchasing.RecordSupplierInvoiceInput", "description": "Supplier invoice to record", "summary": "body" } ] } } }, "description": "Supplier invoice to record", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a received supplier invoice with its purchase tax evidence", "tags": [ "supplier-invoices" ] } }, "/supplier-invoices/{invoiceId}": { "get": { "parameters": [ { "description": "Supplier invoice id", "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Read one recorded supplier invoice", "tags": [ "supplier-invoices" ] }, "patch": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.EditSupplierInvoiceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierInvoiceRecord" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Edit a draft or blocked supplier invoice", "tags": [ "supplier-invoices" ] } }, "/supplier-invoices/{invoiceId}/cancel": { "post": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.CancelSupplierInvoiceInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierInvoiceRecord" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel supplier invoice and recompute eligible financial sources", "tags": [ "supplier-invoices" ] } }, "/supplier-invoices/{invoiceId}/confirm": { "post": { "description": "REFUSED while any line carries unknown taxability or an unknown price basis: an invoice confirmed with an unknown line asserts a tax position nobody took, and once confirmed nothing distinguishes it from the ones that were genuinely assessed. Also refused while the supplier's stated tax disagrees with the figure derived from the declared basis and rate, unless accept_declared_tax records an explicit human decision to take the supplier's — there is deliberately no silent tolerance. Exact receipt/item allocations conserve net-goods amounts and base units. Confirmation atomically posts acquisition decisions, inventory valuation and draft-suggestion events. Confirmed documents are immutable; corrections use typed credits or cancellation. Scoped staff may access a document only when all receipt depots are authorized.", "parameters": [ { "description": "Supplier invoice id", "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_purchasing.ConfirmSupplierInvoiceInput", "description": "Confirmation", "summary": "body" } ] } } }, "description": "Confirmation", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" } }, "security": [ { "BearerAuth": [] } ], "summary": "Confirm a supplier invoice as the authoritative purchase tax record", "tags": [ "supplier-invoices" ] } }, "/supplier-invoices/{invoiceId}/credits": { "get": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "items": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCredit" }, "type": "array" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List supplier invoice credits", "tags": [ "supplier-invoices" ] }, "post": { "description": "Super, country or depot admin authority and purchase permission required; all referenced receipt depots must be within geographic scope. Financial corrections never create physical stock movements.", "parameters": [ { "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_purchasing.RecordSupplierCreditInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" }, { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_purchasing.SupplierCredit" } }, "type": "object" } ] } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid evidence" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not found in scope" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision or allocation conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Financial integration unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Record a typed supplier credit draft", "tags": [ "supplier-invoices" ] } }, "/suppliers": { "get": { "parameters": [ { "description": "Free-text search across name, code, email, contact person", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Filter by exact supplier code", "in": "query", "name": "code", "schema": { "type": "string" } }, { "description": "Filter by country", "in": "query", "name": "country", "schema": { "type": "string" } }, { "description": "Filter by active status", "in": "query", "name": "active", "schema": { "type": "boolean" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List suppliers", "tags": [ "suppliers" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_suppliers.CreateInput", "description": "New supplier", "summary": "body" } ] } } }, "description": "New supplier", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "supplier code in use" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a supplier", "tags": [ "suppliers" ] } }, "/suppliers/bulk": { "patch": { "description": "Requires supplier.write under existing resource authorization and scope. Strict 128 KiB body; at most 100 unique explicit targets. Loads the latest records and revisions inside one mandatory Mongo snapshot transaction, applies existing individual-mutation validation, and commits all or none. Omitted fields preserve their current values. No client-side full-record read or expected_revision is required. Returned identifiers retain request order after normalization. Missing targets are checked before writes; a later per-target failure may include error.details.failed_identifier. No provider calls, automatic callback replay, deletes or workflow transitions.", "operationId": "bulkUpdateSuppliers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/suppliers.BulkSupplierRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "data": { "$ref": "#/components/schemas/suppliers.BulkSupplierResult" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "All selected updates committed together. Refetch list rows for current records." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "VALIDATION_ERROR: invalid selection, empty/unknown/null patch fields, invalid current record or domain rule; no writes." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated actor." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "supplier.write permission required, with the same existing superAdmin bypass as individual updates." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "NOT_FOUND: no writes. error.details.missing_supplier_codes is a JSON-encoded array string of all missing identifiers in request order. Location identifiers use DEPOT/LOCATION." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "CONFLICT: revision or transaction conflict, protected record or existing domain conflict; no writes. Reload and retry the whole batch." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "REQUEST_BODY_TOO_LARGE: JSON body exceeds 128 KiB." }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "INTERNAL_ERROR: no per-item partial result. An ambiguous network/commit outcome must be checked by refetching; setting values or appending the same tags is safe to reapply, but audit metadata can advance." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable; no fallback writes." } }, "security": [ { "BearerAuth": [] } ], "summary": "Bulk update supplier activation", "tags": [ "suppliers" ] } }, "/suppliers/{code}": { "delete": { "parameters": [ { "description": "Supplier code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a supplier", "tags": [ "suppliers" ] }, "get": { "parameters": [ { "description": "Supplier code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a supplier by code", "tags": [ "suppliers" ] }, "patch": { "parameters": [ { "description": "Supplier code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_suppliers.UpdateInput", "description": "Fields to patch", "summary": "body" } ] } } }, "description": "Fields to patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a supplier", "tags": [ "suppliers" ] } }, "/v2/courier/providers": { "get": { "description": "Administer immutable operator-authored drafts. Sensitive configuration is encrypted through KMS and masked on reads. Requires the complete company geographic scope. Saving never publishes runtime availability.", "parameters": [ { "description": "Filter by enabled status", "in": "query", "name": "enabled", "schema": { "type": "boolean" } }, { "description": "Case-insensitive substring search on the delivery company name or code. Matched literally (not as a pattern); blank lists every company.", "in": "query", "name": "q", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyView" }, "type": "array" }, "page": { "type": "object" } }, "required": [ "items", "page" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "data = { items: []DeliveryCompanyView, page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "List delivery companies", "tags": [ "courier" ] }, "post": { "description": "Requires courier.settings.write. Creates an operator-authored company with an immutable slug and enabled intent. No companies, credential keys or endpoints are seeded.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_courier.ProviderCreateInput", "description": "New delivery company", "summary": "body" } ] } } }, "description": "New delivery company", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyView" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "delivery company code in use" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Create a custom delivery company", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}": { "delete": { "description": "Administer immutable operator-authored drafts. Sensitive configuration is encrypted through KMS and masked on reads. Requires the complete company geographic scope. Saving never publishes runtime availability.", "parameters": [ { "description": "Delivery company code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Exact positive current draft revision", "in": "query", "name": "expected_revision", "required": true, "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Revision conflict or configured company must be retained" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Delete an unconfigured delivery company", "tags": [ "courier" ] }, "get": { "description": "Administer immutable operator-authored drafts. Sensitive configuration is encrypted through KMS and masked on reads. Requires the complete company geographic scope. Saving never publishes runtime availability.", "parameters": [ { "description": "Delivery company code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyDetail" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Get a delivery company by code", "tags": [ "courier" ] }, "patch": { "description": "Requires courier.settings.write and expected_revision. Code is immutable; enabled is operator intent. No connection-health prerequisite or provider-specific behavior. Retired adapter/classification input is rejected.", "parameters": [ { "description": "Delivery company code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_courier.ProviderUpdateInput", "description": "Fields to patch", "summary": "body" } ] } } }, "description": "Fields to patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyView" }, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Update a delivery company", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/booking-tests": { "post": { "description": "Sends one sample booking built from the revision's booking_request to its sandbox_endpoint (input sandbox = \"true\"). A booked or already_booked answer with a reference passes and records a receipt bound to the tested revision's booking fingerprint (its booking_request including lookup, its credential version and the values of the non-sensitive settings the booking_request reads). Live order booking is refused until a receipt exists for the current revision's fingerprint, so enabling the company or saving its name, default_instructions, policy or slot_request afterwards needs no re-test. Receipts recorded before fingerprints still count for their exact revision and credential version. A disabled company may be tested. Diagnostics and the request summary are redacted.", "parameters": [ { "description": "Delivery company code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.TestBookingInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.TestBookingResponse" } } }, "description": "Test outcome; passed with test_id only when the receipt was recorded" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "courier.settings.write or geographic scope denied" }, "404": { "description": "Company or configuration revision not found" }, "503": { "description": "Configuration or receipt storage unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Run a sandbox test booking for an exact configuration revision", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/configuration": { "get": { "description": "Read the masked current configuration draft, opaque credential version and current safety status. Requires courier.settings.write and the complete company geographic scope. booking_test reports the passing sandbox booking test that satisfies the live-booking gate for the current booking fingerprint (null when live booking would be refused with sandbox_test_required), and booking_test_failure the latest newer failed test (null otherwise). Secret plaintext, carrier error messages, request summaries and provider responses are never returned.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.ConfigurationDetailResponse" } } }, "description": "Masked immutable draft with current safety status" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Permission, scope or service subject denied" }, "404": { "description": "Company not found" }, "503": { "description": "Configuration or credential status unavailable" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Read the current masked courier configuration draft", "tags": [ "courier" ] }, "patch": { "description": "Requires courier.settings.write. Atomic revision CAS and idempotent save, 64 KiB request limit and Cache-Control no-store. Configuration replaces the whole entry array; omission preserves it and an empty array clears it. Sensitive values are encrypted at rest and masked on every read. An unchanged mask preserves the existing secret. Slot request mappings are Supply-owned; saving configuration never calls the courier and does not require a valid mapping.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.ConfigurationWriteInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyResponse" } } }, "description": "Committed company configuration without secret values" }, "400": { "description": "Invalid request; error.details contains field and reason without submitted values" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Courier settings writer permission required" }, "404": { "description": "Delivery company not found" }, "409": { "description": "Stale revision, changed idempotency payload or pending command" }, "503": { "description": "Configuration or credential storage unavailable; retry with the same idempotency key" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Atomically replace free-form courier configuration", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/configuration/revisions": { "get": { "description": "Pages the company's immutable configuration revisions, newest first, so a revision can be chosen and read through the single-revision route. Summaries never carry configuration values or secrets. Requires courier.settings.write and the complete company geographic scope, the same as the single-revision read.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "items": { "items": { "$ref": "#/components/schemas/internal_modules_courier.ConfigurationRevisionSummary" }, "type": "array" }, "page": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_paging.PageResponse" } }, "required": [ "items", "page" ], "type": "object" }, "success": { "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "data = { items: []ConfigurationRevisionSummary, page: {...} }" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Permission, subject or geographic scope denied" }, "404": { "description": "Company not found" }, "503": { "description": "Configuration history unavailable" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "List immutable configuration revisions newest first", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/configuration/revisions/{revision}": { "get": { "description": "Read one masked immutable configuration revision. booking_test and booking_test_failure are computed from that revision's snapshot (its booking_request, credential version and the settings it reads), so they report the sandbox booking test state of that revision's booking fingerprint rather than the current revision's.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "revision", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.ConfigurationDetailResponse" } } }, "description": "Success" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Permission, subject or geographic scope denied" }, "404": { "description": "Exact company, revision or credential version not found" }, "503": { "description": "Configuration or credential status unavailable" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Read a masked immutable configuration draft", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/credentials/{version}/revoke": { "post": { "description": "Idempotent and irreversible safety override for every referencing revision. Does not alter immutable drafts or ciphertext. Requires courier settings write permission and the complete company geographic scope.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "version", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "type": "object" } } }, "description": "Credential permanently revoked" }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Permission, subject or geographic scope denied" }, "404": { "description": "Exact company, revision or credential version not found" }, "503": { "description": "Configuration or credential status unavailable" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Permanently revoke one company credential version", "tags": [ "courier" ] } }, "/v2/courier/providers/{code}/policy": { "put": { "description": "Save an immutable coverage draft using positive revision CAS. Explicit country, market and live shipping-zone references must be within the complete company geographic scope. Enabled intent does not publish runtime availability.", "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.PolicyInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal_modules_courier.DeliveryCompanyResponse" } } }, "description": "Successful response" }, "400": { "description": "Validation failed" }, "401": { "description": "Unauthenticated" }, "403": { "description": "Permission or scope denied" }, "409": { "description": "Revision or idempotency conflict" }, "503": { "description": "Provider or credential unavailable" } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "url": "/" } ], "summary": "Replace linked courier coverage atomically", "tags": [ "courier" ] } }, "/warehouse-layouts": { "get": { "parameters": [ { "description": "Filter by depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Filter by published state", "in": "query", "name": "is_published", "schema": { "type": "boolean" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []warehouse.WarehouseLayout, page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List warehouse layouts", "tags": [ "layout" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_layout.CreateLayoutInput", "description": "New warehouse layout", "summary": "body" } ] } } }, "description": "New warehouse layout", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "depot + version already exists" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a warehouse layout", "tags": [ "layout" ] } }, "/warehouse-layouts/{depotCode}/{version}": { "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "version must be a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a warehouse layout", "tags": [ "layout" ] }, "patch": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_layout.UpdateLayoutInput", "description": "Layout patch", "summary": "body" } ] } } }, "description": "Layout patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a warehouse layout", "tags": [ "layout" ] } }, "/warehouse-layouts/{depotCode}/{version}/nodes": { "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } }, { "description": "Exact parent node code within this depot and layout version", "in": "query", "name": "parent_code", "schema": { "type": "string" } }, { "description": "Layout node type", "in": "query", "name": "type", "schema": { "type": "string" } }, { "description": "Filter by active state", "in": "query", "name": "is_active", "schema": { "type": "boolean" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []warehouse.LayoutNode, page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "version must be a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List layout nodes", "tags": [ "layout" ] }, "post": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_layout.CreateNodeInput", "description": "New layout node", "summary": "body" } ] } } }, "description": "New layout node", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "parent layout not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "layout node code already exists" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a layout node", "tags": [ "layout" ] } }, "/warehouse-layouts/{depotCode}/{version}/nodes/{code}": { "delete": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } }, { "description": "Node code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "version must be a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Delete a layout node", "tags": [ "layout" ] }, "get": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } }, { "description": "Node code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "version must be a positive integer" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a layout node", "tags": [ "layout" ] }, "patch": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } }, { "description": "Node code", "in": "path", "name": "code", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_layout.UpdateNodeInput", "description": "Node patch", "summary": "body" } ] } } }, "description": "Node patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a layout node", "tags": [ "layout" ] } }, "/warehouse-layouts/{depotCode}/{version}/publish": { "post": { "parameters": [ { "description": "Depot code", "in": "path", "name": "depotCode", "required": true, "schema": { "type": "string" } }, { "description": "Layout version", "in": "path", "name": "version", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Publish a warehouse layout", "tags": [ "layout" ] } }, "/wish-ballots": { "get": { "parameters": [ { "description": "Filter by ballot state", "in": "query", "name": "state", "schema": { "enum": [ "scheduled", "open", "closed" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List wish ballots", "tags": [ "wishes" ] }, "post": { "description": "An unavailable selected candidate returns WISH_CANDIDATE_UNAVAILABLE.", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.CreateBallotInput", "description": "Scheduled ballot definition", "summary": "body" } ] } } }, "description": "Scheduled ballot definition", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "WISH_CANDIDATE_UNAVAILABLE" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a scheduled ballot from published candidates", "tags": [ "wishes" ] } }, "/wish-ballots/{id}": { "get": { "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get one wish ballot", "tags": [ "wishes" ] }, "patch": { "description": "At least one ballot field is required. If-Match is optional; when supplied and stale, the response is 409 with the current ETag.", "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.PatchBallotInput", "description": "Fields to patch", "summary": "body" } ] } } }, "description": "Fields to patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Edit one scheduled ballot", "tags": [ "wishes" ] } }, "/wish-ballots/{id}/close": { "post": { "description": "If-Match is optional and a stale supplied value returns 409 with the current ETag. Repeating close on a closed ballot is idempotent.", "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Close a scheduled or open ballot", "tags": [ "wishes" ] } }, "/wish-ballots/{id}/open": { "post": { "description": "If-Match is optional and a stale supplied value returns 409 with the current ETag. Repeating open on the active in-window ballot is idempotent. Voting-window failures use WISH_BALLOT_CLOSED and unavailable candidates use WISH_CANDIDATE_UNAVAILABLE.", "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Open a scheduled ballot in its voting window", "tags": [ "wishes" ] } }, "/wish-ballots/{id}/ranking": { "get": { "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { ballot: {...}, ranking: [] }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get backend-computed ranking for one ballot", "tags": [ "wishes" ] } }, "/wish-ballots/{id}/refresh": { "post": { "description": "The body is optional and may only replace closes_at; the successor preserves the current ballot's candidate order and starts with zero votes. If-Match is optional and a stale supplied value returns 409 with the current ballot ETag. Non-active ballots use WISH_BALLOT_CLOSED and unavailable preserved candidates use WISH_CANDIDATE_UNAVAILABLE.", "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag of the current ballot", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.RefreshBallotInput", "description": "Optional closes_at override", "summary": "body" } ] } } }, "description": "Optional closes_at override" }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Close the active ballot and create a zero-vote open successor", "tags": [ "wishes" ] } }, "/wish-ballots/{id}/schedule": { "post": { "description": "The body is optional; an empty body revalidates the existing schedule. If-Match is optional and a stale supplied value returns 409 with the current ETag.", "parameters": [ { "description": "Wish ballot id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.ScheduleBallotInput", "description": "Optional schedule fields to update", "summary": "body" } ] } } }, "description": "Optional schedule fields to update" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Revalidate or update one scheduled ballot", "tags": [ "wishes" ] } }, "/wish-candidates": { "get": { "parameters": [ { "description": "Filter by candidate state", "in": "query", "name": "state", "schema": { "enum": [ "draft", "published", "retired", "fulfilled" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List wish candidates", "tags": [ "wishes" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.CreateCandidateInput", "description": "New draft candidate", "summary": "body" } ] } } }, "description": "New draft candidate", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create an admin-authored draft candidate", "tags": [ "wishes" ] } }, "/wish-candidates/{id}": { "get": { "parameters": [ { "description": "Wish candidate id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get one wish candidate", "tags": [ "wishes" ] }, "patch": { "description": "At least one candidate field is required. If-Match is optional; when supplied and stale, the response is 409 with the current ETag.", "parameters": [ { "description": "Wish candidate id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.PatchCandidateInput", "description": "Fields to patch", "summary": "body" } ] } } }, "description": "Fields to patch", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Edit one draft candidate", "tags": [ "wishes" ] } }, "/wish-candidates/{id}/link-product": { "post": { "description": "If-Match is optional; a stale supplied value returns 409 with the current ETag. Linking the same product again is idempotent.", "parameters": [ { "description": "Wish candidate id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.LinkProductInput", "description": "Product SKU code to link", "summary": "body" } ] } } }, "description": "Product SKU code to link", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Mark a candidate fulfilled by an existing product", "tags": [ "wishes" ] } }, "/wish-candidates/{id}/publish": { "post": { "description": "If-Match is optional; a stale supplied value returns 409 with the current ETag. Repeating publish on a published candidate is idempotent.", "parameters": [ { "description": "Wish candidate id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Publish one draft candidate", "tags": [ "wishes" ] } }, "/wish-candidates/{id}/retire": { "post": { "description": "If-Match is optional; a stale supplied value returns 409 with the current ETag. Repeating retire on a retired candidate is idempotent.", "parameters": [ { "description": "Wish candidate id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Optional optimistic-concurrency ETag", "in": "header", "name": "If-Match", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Conflict" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Retire a candidate that is not fulfilled or on the open ballot", "tags": [ "wishes" ] } }, "/wish-proposals": { "get": { "parameters": [ { "description": "Filter by proposal state", "in": "query", "name": "state", "schema": { "enum": [ "pending", "converted", "rejected" ], "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: [], page: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "List wish proposals", "tags": [ "wishes" ] } }, "/wish-proposals/bulk/reject": { "post": { "description": "Requires wish.manage and the existing authenticated staff command boundary. Reject pending proposals with the supplied reason and existing revision CAS. Already rejected records are no-ops and preserve their original reason and audit; converted or other states reject the whole batch with 409. Strict JSON body up to 128 KiB and 1-100 unique normalized targets. Current records and all writes share one required Mongo transaction. Missing or failed targets abort every write. Missing targets return 404; error.details.missing_ids is a JSON-encoded array string. No provider calls, product conversion, stock mutation or producer result calculation is performed. These modules retain existing staff visibility; no additional row geography predicate is introduced.", "operationId": "bulkRejectWishProposals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wishes.BulkRejectInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/wishes.BulkRejectResponse" } } }, "description": "Atomic completion; normalized selection in request order." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid target, required reason or strict JSON body" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Authentication or actor required" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Required permission denied" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Selected target missing" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Ineligible state or concurrent change" }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Body exceeds 128 KiB" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Result uncertain; refetch before retrying" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Transactional store unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reject selected pending wish proposals", "tags": [ "wishes" ] } }, "/wish-proposals/{id}/convert": { "post": { "parameters": [ { "description": "Wish proposal id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.CreateCandidateInput", "description": "Candidate content to author from this proposal", "summary": "body" } ] } } }, "description": "Candidate content to author from this proposal", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { proposal: {...}, candidate: {...} }" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only pending wish proposals can be converted" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Convert a pending proposal into an admin-authored draft candidate", "tags": [ "wishes" ] } }, "/wish-proposals/{id}/reject": { "post": { "description": "Optional customer-safe administrative reason; an empty body is accepted. Repeating reject on a rejected proposal is idempotent.", "parameters": [ { "description": "Wish proposal id", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wishes.RejectProposalInput", "description": "Optional rejection reason", "summary": "body" } ] } } }, "description": "Optional rejection reason" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only pending wish proposals can be rejected" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Service Unavailable" } }, "security": [ { "BearerAuth": [] } ], "summary": "Reject a pending wish proposal", "tags": [ "wishes" ] } }, "/wms-drafts": { "get": { "parameters": [ { "description": "Filter by depot code", "in": "query", "name": "depot_code", "schema": { "type": "string" } }, { "description": "Filter by operator", "in": "query", "name": "operator", "schema": { "type": "string" } }, { "description": "Filter by draft type", "in": "query", "name": "type", "schema": { "type": "string" } }, { "description": "Filter by status (DRAFT, SUBMITTED, CANCELLED)", "in": "query", "name": "status", "schema": { "type": "string" } }, { "description": "Page number (1-based)", "in": "query", "name": "page", "schema": { "type": "integer" } }, { "description": "Items per page (max 200)", "in": "query", "name": "page_size", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "data = { items: []warehouse.WMSDraft, page: {...} }" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "List WMS drafts", "tags": [ "wmsdraft" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wmsdraft.CreateInput", "description": "New WMS draft (DRAFT status)", "summary": "body" } ] } } }, "description": "New WMS draft (DRAFT status)", "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "Created" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" } }, "security": [ { "BearerAuth": [] } ], "summary": "Create a WMS draft", "tags": [ "wmsdraft" ] } }, "/wms-drafts/filter-options": { "get": { "description": "Requires wmsdraft.read under the same authenticated live-session and scope-resolution middleware as the owner list. Reuses exactly its record filters. These existing lists currently have no row-level geographic predicate; this endpoint does not add one or claim geographic isolation. Explicit whitelist only. Returns exact stored scalar strings including service actors; no user lookup, labels, inferred actors or enum expansion. Blank, non-string, control-containing and values over 512 UTF-8 bytes are omitted. Server groups/sorts/limits to limit+1 rows, disables disk spilling, and uses a five-second context deadline. Query pins are all ANDed. Keyset pages are not a snapshot across concurrent record changes; restart discovery after changing filters. Response uses private, no-store caching.", "operationId": "wmsDraftFilterOptions", "parameters": [ { "in": "query", "name": "field", "required": true, "schema": { "enum": [ "operator" ], "type": "string" } }, { "description": "Literal case-insensitive substring, no regex interpretation. Maximum 100 Unicode characters and 512 UTF-8 bytes.", "in": "query", "name": "search", "schema": { "maxLength": 100, "type": "string" } }, { "description": "Strict decimal integer; no sign, whitespace or leading zero.", "in": "query", "name": "limit", "schema": { "default": 50, "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Exclusive binary-order keyset boundary; at most 512 UTF-8 bytes. Preserve the original value including spaces and case.", "in": "query", "name": "after", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "depot_code", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "operator", "schema": { "maxLength": 512, "type": "string" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "type", "schema": { "$ref": "#/components/schemas/warehouse_enums.WMSDraftType" } }, { "description": "Exact existing list filter, ANDed with all other pins, including the selected field. ", "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/warehouse_enums.WMSDraftStatus" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/filteroptions.Result" }, "success": { "const": true, "type": "boolean" } }, "required": [ "success", "data" ], "type": "object" } } }, "description": "Distinct stored values in ascending binary order, maximum limit values. Empty results use items: []." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Invalid field, malformed/repeated/unknown query parameter, invalid enum, missing cause_type pin, query over 8 KiB, or query value over bounds/containing control characters." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthenticated or missing workforce role." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Named read permission or existing staff scope-resolution gate denied." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Discovery store unavailable, failed query or bounded aggregation timeout; no partial result." } }, "security": [ { "BearerAuth": [] } ], "summary": "Discover record-backed WMS draft operators", "tags": [ "wms-drafts" ] } }, "/wms-drafts/{id}": { "get": { "parameters": [ { "description": "WMS draft ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Get a WMS draft", "tags": [ "wmsdraft" ] }, "patch": { "parameters": [ { "description": "WMS draft ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "$ref": "#/components/schemas/internal_modules_wmsdraft.UpdateInput", "description": "Draft patch (DRAFT-only edits)", "summary": "body" } ] } } }, "description": "Draft patch (DRAFT-only edits)", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only DRAFT drafts can be edited" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Update a WMS draft", "tags": [ "wmsdraft" ] } }, "/wms-drafts/{id}/cancel": { "post": { "parameters": [ { "description": "WMS draft ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only DRAFT drafts can be cancelled, or status changed concurrently" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Cancel a WMS draft", "tags": [ "wmsdraft" ] } }, "/wms-drafts/{id}/submit": { "post": { "parameters": [ { "description": "WMS draft ID", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/data" } ], "properties": { "data": {}, "error": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_apiresponse.Error" }, "success": { "type": "boolean" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "only DRAFT drafts can be submitted, or status changed concurrently" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/github_com_Potato-Mart_Backend-Supply_internal_platform_httpx.APIResponse" } } }, "description": "Not Found" } }, "security": [ { "BearerAuth": [] } ], "summary": "Submit a WMS draft", "tags": [ "wmsdraft" ] } } }, "servers": [ { "url": "/v1" } ] }