{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Shipbuy V2 Public API — approved resource contract","version":"0.1.0-runtime-validation","description":"Approved resource contract with implementation under runtime validation. Shipping, orders, products, inventory and developer tools have implementations; test simulations are separately isolated. Operation metadata records implementation, not production deployment or acceptance. External tracker registration and standalone address verification remain disabled in live. No charge is authorized before the explicit commercial enablement gates are met. New customers use the V2 App and public API /v2. Unmigrated customers retain the complete original Laravel V1 UI and APIs. The separate Java three-route bridge is listed in x-legacy-compatibility; it is not the complete V1 API. No V1 routing cutover, UI shutdown or sunset is authorized by this contract.\n\nResource API base: https://api.shipbuy.com/v2. Test/live is fixed by the API key credential, with isolated storage, objects, idempotency receipts, events and simulated funds. No body/header may switch environment. Test cannot buy valid production postage or mutate live inventory/wallets. Supplier test coverage differs; deterministic sandbox scenarios and carrier acceptance are separate verification layers.\n\nInitial authentication is X-API-Key only, equally for merchant-owned integrations and third-party server-side SaaS integrations. Every integration uses an explicit scoped credential; the same named scopes and resource/warehouse/carrier-account restrictions apply. A key never bypasses tenant, plan or business guards. Scope definitions are maintained in x-scopes; each operation declares its requirements in x-required-scopes and, where applicable, x-conditional-scopes. New resource credentials require authorizationVersion=v2. Java bridge credentials retain their legacy contract; original Laravel V1 uses its separate JWT Bearer contract.\n\nBusiness writes require Idempotency-Key; PATCH additionally requires If-Match. Business reference/order number is not an idempotency key. Reauthorize before replay; completed retries return the original committed result, while unknown external effects return a recoverable operation. IDs and decimal money are strings. Date/time fields use the existing yyyy-MM-dd HH:mm:ss convention in UTC; shipDate is a local calendar date. Public DTOs must not expose raw ORM entities, carrier credentials, upstream cost or internal worker state.\n\nNo hard delete for orders/products/shipments/ledger. Cancellation, inactivation, void/refund, adjustments and reservations are explicit business commands. Orders↔fulfillments are M:N. Rates/buy apply to a specific fulfillment or standalone shipping plan; a whole order never hides multiple fulfillment purchases. Fulfillment merge/unmerge, return labels, supplier shipments, receiving/transfers/assembly/count execution and bulk job APIs remain domain targets but are intentionally not contracted in this version.\n\nCommercial enablement is separate from design approval: new live external-tracker registrations and standalone postal address verifications are disabled until their prices and quota policies are confirmed. Reject a new action with HTTP 403/service_not_enabled before any upstream call or charge; never run it silently for free. Test simulation, authorized reads of existing results and completed idempotent replays remain available without new provider calls or charges. No public product-enablement API is defined.","x-status":"implemented-runtime-acceptance-pending"},"x-status":"implemented-runtime-acceptance-pending","servers":[{"url":"https://api.shipbuy.com/v2","description":"Common resource origin for test/live credentials. Implementation is not proof of production availability; deployment and external runtime acceptance remain pending."}],"security":[{"ApiKey":[]}],"x-authorization-version":"v2","x-resource-restrictions":{"warehouseOrigin":"Standalone shipping requires explicit allowStandaloneShipping. A warehouse-restricted standalone plan requires warehouseId and shipFrom matching an authorized warehouse. Only explicit warehouses.all permits an arbitrary shipping origin.","associations":"A business resource without a store requires stores.all; an unassigned fulfillment requires allowUnassignedFulfillments. Pure standalone shipping requires neither stores.all nor allowUnassignedFulfillments in addition to its origin and shipping-account authorization."},"x-scopes":{"rates.read":"Request customer shipping quotes and discover usable shipping accounts/services.","shipments.read":"Read authorized shipment, package and shipping-document resources.","labels.buy":"Purchase labels; may spend money. Does not imply void or all shipment reads.","labels.void":"Request authorized label void/refund actions.","tracking.read":"Read package and externally registered tracker status/events.","tracking.subscribe":"Register external tracking monitoring; live new registration is disabled until prices and quota policy are confirmed. Test simulation remains available.","addresses.verify":"Request standalone postal verification; live new verification is disabled until prices and quota policy are confirmed. Test simulation remains available.","manifests.read":"Read manifest candidates, results and documents.","manifests.write":"Create manifests and explicitly release local membership where allowed.","orders.read":"Read sales orders and their fulfillment associations.","orders.write":"Create/edit/hold/release sales orders.","orders.cancel":"Cancel sales orders under business guards.","fulfillments.read":"Read fulfillment plans and associations.","fulfillments.write":"Edit/split fulfillment plans.","fulfillments.ship":"Confirm shipment through the shared inventory-aware ship workflow.","products.read":"Read catalog products, variants and components.","products.write":"Create/edit/inactivate products, variants and components.","inventory.read":"Read stocks, active manual holds, warehouses, locations and transactions.","inventory.adjust":"Perform guarded, audited physical stock adjustments.","inventory.reserve":"Create/release manual warehouse-level quantity reservations.","webhooks.manage":"Manage own integration webhook endpoints/events/deliveries; resource event scopes remain required.","usage.read":"Read environment-specific API usage and metering."},"x-future-authentication":{"status":"deferred-out-of-scope","description":"OAuth is reserved for a future design and is outside this initial API-key-only contract. No authorization-server routes, flows or token DTOs are defined here.","designReference":"../design/platform.md","section":"3.17.5"},"x-legacy-compatibility":{"implementedBackendAliases":["POST /v1/shipping/rates","POST /v1/shipping/buy","POST /v1/shipping/refund","POST /v2/open/shipping/rates","POST /v2/open/shipping/buy","POST /v2/open/shipping/refund"],"currentPublicGateway":["POST /v1/shipping/rates","POST /v1/shipping/buy","POST /v1/shipping/refund"],"authentication":"X-API-Key only. Backend /compat/* Basic Auth is a separate legacy deployment contract, not a resource API or gateway alias here.","legacyScopes":{"rates":["labels.read","labels.buy"],"buy":["labels.buy"],"refund":["labels.buy"]},"originalLaravelV1":{"baseUrl":"https://shipbuy.com/api","authentication":"POST /token with email and password returns a JWT; send it as Authorization Bearer.","scope":"Complete original V1 UI and APIs remain available to unmigrated customers; the Java bridge is not a replacement.","routeEvidence":"../../v1-reference/laravel/routes/api.php"},"coexistence":"New customers use V2 only. Preserve all original V1 UI and API routes, authentication and DTOs for unmigrated customers. Coexistence deployment and migration are separate future work. No V1 route cutover, shutdown or sunset is authorized. Do not infer feature parity from the three Java bridge operations."},"x-webhook-contract":{"delivery":"At least once; duplicates, delayed and out-of-order events are expected. Deduplicate by event.id per environment. Persist before returning 2xx; process asynchronously. Fetch resource to reconcile current state.","signature":"Shipbuy-Signature: t=<Unix-seconds>,v1=<hex-HMAC-SHA256>. Sign UTF-8 timestamp + dot + exact raw request-body bytes using the per-endpoint secret. Verify constant-time and reject timestamps outside a 300-second tolerance. A new delivery attempt is signed with its own delivery time; business createdAt remains unchanged.","headers":["Shipbuy-Event-Id","Shipbuy-Delivery-Id","Shipbuy-Signature"],"retry":"Network errors, timeouts and non-2xx responses retry with bounded exponential backoff and jitter; retry window 72 hours. Redelivery keeps event ID and never repeats business effects. Event/delivery retention is 30 days, with explicit expiry errors and usage limits.","secretRotation":"Dedicated endpoint secret, never API key credential. Managed rotation must support overlap and explicit retirement; a public rotate-secret endpoint is outside this version.","privacy":"Reference payloads minimize PII. Outbound delivery rechecks current scopes and environment, uses HTTPS and validated destinations; never include credentials or wholesale upstream responses.","authorization":"Each endpoint belongs to account+environment+stable integrationId and internally records authorizingCredentialId plus the scope/resource-constraint snapshot taken at creation. Every delivery is authorized by the intersection of that snapshot and the current authorizing API key permissions and resource restrictions. Pausing, expiring or revoking that key immediately stops its subscriptions; another key in the same integration never implicitly supplies authority. An administrator may explicitly migrate subscriptions during Rotate to a successor key in the same integration and environment without expanding authority, preserving delivery continuity. An independently created key does not automatically take over. Internal credential IDs/snapshots need not be exposed in public payloads; this contract adds no alternative authorization-management endpoint."},"x-design-defaults":{"publicTimeFormat":"yyyy-MM-dd HH:mm:ss UTC","maximumQuoteTtlSeconds":900,"pageLimit":100,"minimumGeneralIdempotencyRetentionDays":7,"webhookRetentionDays":30,"webhookRetryHours":72,"requestDiagnosticLogRetentionDays":30,"addressVerificationCacheHours":24,"addressVerificationCacheCondition":"Only where the upstream provider permits result caching; keyed by account, environment, normalized input and verification options. Financial/audit record retention is separate from request diagnostic logs."},"x-commercial-enablement":{"status":"live-new-actions-disabled","liveNewActions":{"externalTrackerRegistration":"disabled_until_prices_and_quota_policy_confirmed","standaloneAddressVerification":"disabled_until_prices_and_quota_policy_confirmed"},"blockedOperations":["POST /trackers","POST /address-verifications"],"rejection":{"httpStatus":403,"code":"service_not_enabled","before":["upstream_provider_call","new_fee_or_accrual"]},"activation":"Price and quota policy confirmation is mandatory before enabling each live capability through an explicitly authorized management/release process. No public product-enablement API exists in this contract. Design approval alone does not activate production billing or allow silent free execution.","test":"Deterministic test simulations remain usable and never call a production charging provider or debit live funds.","existingResults":"Normal credential, scope and resource checks still apply. Reads of existing trackers/package tracking/usage/results and authorized replay of an already completed idempotency receipt are not blocked by this new-action gate. They must not cause a new upstream call, monitoring cycle, fee or accrual.","ordinaryRates":"Ordinary shipping quotes are included under the account plan and remain subject to configured account quotas and rate limits; no invented numeric allowance is defined here.","billing":"Approved, unimplemented target: accrue billable completed actions, reserve accrued unsettled fees against spendable wallet funds, and settle daily. Low balance or insufficient budget stops new billable registrations/verifications without terminating an already paid tracking cycle. Daily settlement is not evidence that the billing implementation exists.","pendingDecisions":["external tracker price and included quota","standalone address verification price and included quota","tracker monitoring-cycle length and registration renewal policy","tracker polling frequency and event-history retention"],"prices":"No unit price, included allowance, tracking-cycle length or charge amount is set by this contract."},"x-metering-contract":{"addressVerification":"Count one completed authoritative postal validity verdict (valid or invalid) for a newly billable verification. A corrected result counts only when it represents a completed valid-address verdict; text normalization alone is not a validity verdict. Local format rejection, unsupported coverage, timeout, provider failure or an indeterminate/unverifiable result is not billable. Test results are never billable.","addressCache":"Subject to provider permission, reuse a completed verification result for the same account+environment+normalized input+verification options for 24 hours; a permitted cache hit does not call the provider or incur another charge. Never share address results across accounts or environments. The disabled-live new-action gate cannot be bypassed by treating a new paid request as an implicit free trial.","externalTracking":"Meter a successful unique external-tracker registration once per agreed monitoring cycle. Retries or duplicate registration within that same cycle, GET reads, polling updates and webhook redeliveries do not create another registration charge. The duplicate identity includes account+environment+carrier+tracking number+shipping period; tracking numbers can be reused. Cycle duration, renewal terms, quotas and price remain undecided, so live new registration stays disabled.","purchasedLabelTracking":"Basic tracking for Shipbuy-purchased labels is included; repeated reads do not create paid external-tracker registrations.","settlementPrecision":"Usage amount is an aggregate monetary amount, not a per-call price. Unit pricing and micro-amount accrual/rounding policy are not represented or invented by this schema; agree them before enabling live metered actions."},"tags":[{"name":"Shipping"},{"name":"Shipments"},{"name":"Tracking"},{"name":"Manifests"},{"name":"Addresses"},{"name":"Operations"},{"name":"Orders"},{"name":"Fulfillments"},{"name":"Products"},{"name":"Inventory"},{"name":"Webhooks"},{"name":"Usage"}],"paths":{"/shipping-accounts":{"get":{"operationId":"listShippingAccounts","summary":"List usable shipping accounts and service capabilities","tags":["Shipping"],"description":"Only accounts allowed by the authenticated integration, environment and tenant. Includes customer-facing services/packaging capabilities; never internal credentials or provider cost.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["rates.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingAccountListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"}]}},"/shipping/rate-quotes":{"post":{"operationId":"createRateQuote","summary":"Quote a standalone plan or a specific fulfillment","tags":["Shipping"],"description":"source is exactly one of standalone, fulfillment or an explicit order+fulfillment association. All source resource IDs and shipping accounts must fit the integration scope. Fulfillment sources additionally require fulfillments.read (order_fulfillment also orders.read). Result may contain partial carrier failures; each returned rate covers all packages.","x-status":"implemented-runtime-acceptance-pending","x-runtime-limitations":["Standalone, fulfillment and explicitly selected order_fulfillment sources are implemented; source-specific permissions and readiness apply.","Only USD quotes and zero additional insured value are currently supported.","ShipStation TEST_ UPS Ground, private development S3 and isolated MySQL/Redis wallet concurrency have passed local integration acceptance; production deployment and other carrier/service combinations are not implied."],"x-required-scopes":{"anyOf":[{"allOf":["rates.read"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateQuoteResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateQuoteRequest"},"example":{"source":{"kind":"standalone","shipping":{"shipFrom":{"name":"Warehouse","street1":"123 Market St","city":"San Francisco","state":"CA","postalCode":"94103","country":"US","phone":"4155550100","residential":false},"shipTo":{"name":"Alex Chen","street1":"456 Pine St","city":"Seattle","state":"WA","postalCode":"98101","country":"US","phone":"2065550100","residential":true},"packages":[{"packageNo":1,"length":"12","width":"9","height":"3","weight":"2","dimensionUnit":"in","weightUnit":"lb","shape":"box"}],"reference":"ERP-SHIP-1001"}},"shippingAccountIds":["41"]}}}},"x-conditional-scopes":{"source.kind=fulfillment":["fulfillments.read"],"source.kind=order_fulfillment":["orders.read","fulfillments.read"]}}},"/shipping/label-purchases":{"post":{"operationId":"purchaseLabel","summary":"Purchase all packages for a selected rate","tags":["Shipping"],"description":"Server validates immutable quote binding, expiry, current permissions, fulfillment version/readiness, policy, wallet and carrier capability before purchase. A fulfillment-origin purchase additionally requires fulfillments.write. If the current account mark_shipped_trigger or another existing business rule will automatically confirm shipment/decrement inventory, fulfillments.ship is also required before ANY carrier call; absent permission returns 403, never skips that side effect or implicitly grants it from labels.buy. One purchase produces a shipment with one or more packages. Each frozen quote binds durably to one purchase operation before the carrier call; changing the Idempotency-Key or selecting another rate from that quote cannot start another purchase. Quote expiry does not release that binding; a different purchase request remains operation_pending. Retry the original key to recover its operation/result. An intentional new shipment requires a new quote and a new key; do not create a replacement quote to retry an unknown purchase. Unknown carrier outcome is needs_review, never automatically a second purchase.","x-status":"implemented-runtime-acceptance-pending","x-runtime-limitations":["Standalone, fulfillment and explicitly selected order_fulfillment sources are implemented; source-specific permissions and readiness apply.","Only USD quotes and zero additional insured value are currently supported.","ShipStation TEST_ UPS Ground, private development S3 and isolated MySQL/Redis wallet concurrency have passed local integration acceptance; production deployment and other carrier/service combinations are not implied."],"x-required-scopes":{"anyOf":[{"allOf":["labels.buy"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResultResponse"}}}},"202":{"description":"Accepted; poll Location or GET /operations/{id}.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the durable operation."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LabelPurchaseRequest"},"example":{"quoteId":"quote_301","rateId":"rate_302","reference":"ERP-SHIP-1001"}}}},"x-conditional-scopes":{"quote.source.kind in [fulfillment,order_fulfillment]":["fulfillments.write"],"existing_business_rule_will_auto_ship":["fulfillments.ship"]}}},"/shipments":{"get":{"operationId":"listShipments","summary":"List visible shipments","tags":["Shipments"],"description":"List visible shipments.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["shipments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ShippingAccountFilter"},{"$ref":"#/components/parameters/ReferenceFilter"},{"name":"trackingNumber","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"fulfillmentId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["purchased","shipped","in_transit","delivered","exception","voided"]}}]}},"/shipments/{shipmentId}":{"get":{"operationId":"getShipment","summary":"Retrieve a shipment and all packages","tags":["Shipments"],"description":"Retrieve a shipment and all packages.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["shipments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/shipments/{shipmentId}/documents":{"get":{"operationId":"listShipmentDocuments","summary":"Retrieve refreshable shipment document links","tags":["Shipments"],"description":"Returns persisted valid documents with refreshed signed URLs, including after an original purchase response was lost. Historical voided-label access is visibly marked by the owning shipment/package status; never suggests it is valid for shipping.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["shipments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["label","commercial_invoice","carrier_form"]}}]}},"/shipments/{shipmentId}/voids":{"post":{"operationId":"voidShipmentLabels","summary":"Request label void and refund","tags":["Shipments"],"description":"Package subset is explicit; whole-shipment providers reject subsets. Void acceptance, label lifecycle and wallet/carrier refund completion are distinct. Refund cannot exceed actual collected amounts. Partial successes are durable and replayable; no rollback claim for already completed carrier actions. A fulfillment-linked void additionally requires fulfillments.write. If existing rules can revert shipment and restore inventory/reservations, fulfillments.ship is also required before the carrier call. Missing authority returns 403; never skip the existing reversal rules or silently broaden labels.void into inventory authority.","x-status":"implemented-runtime-acceptance-pending","x-conditional-scopes":{"shipment_has_fulfillment":["fulfillments.write"],"existing_business_rule_may_revert_shipment":["fulfillments.ship"]},"x-required-scopes":{"anyOf":[{"allOf":["labels.void"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidResultResponse"}}}},"202":{"description":"Accepted; poll Location or GET /operations/{id}.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the durable operation."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"shipmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidRequest"},"example":{"reason":"Customer canceled before handover"}}}}}},"/packages/{packageId}/tracking":{"get":{"operationId":"getPackageTracking","summary":"Read tracking for a purchased package","tags":["Tracking"],"description":"Cached tracking for an authorized package. Included basic tracking for Shipbuy-purchased labels does not create a paid external tracker. No immediate upstream call is caused by repeated reads.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["tracking.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingSnapshotResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"packageId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/trackers":{"post":{"operationId":"createTracker","summary":"Register an external tracking number","tags":["Tracking"],"description":"Register an external tracking number. Commercial gate: new live actions are disabled until the service price and quota policy are confirmed. Return 403/service_not_enabled before any upstream call, new fee or accrued amount; never silently execute for free. This is independent of the API key scope check. Test simulation and authorized completed-idempotency replay remain available without new charges. No public product-enablement API is provided.","x-status":"sandbox-implemented-live-disabled","x-live-availability":"service_not_enabled","x-required-scopes":{"anyOf":[{"allOf":["tracking.subscribe"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackerResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"description":"API key/resource permission denied, or live new-action capability has not been commercially enabled. service_not_enabled means no upstream call and no new fee/accrual occurred.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"serviceNotEnabled":{"value":{"code":"service_not_enabled","message":"This live service is not enabled. Prices and quota policy must be confirmed before new requests are accepted.","requestId":"req_1001","data":null}}}}}},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackerCreate"},"example":{"carrier":"ups","trackingNumber":"1Z999AA10123456784","shipDate":"2026-11-01","reference":"EXTERNAL-1001"}}}},"x-commercial-gate":{"environment":"live","enabled":false,"activationCondition":"service_price_and_quota_policy_confirmed","blockedStatus":403,"blockedCode":"service_not_enabled","testSimulationAllowed":true,"completedReplayAllowed":true}},"get":{"operationId":"listTrackers","summary":"List external tracking registrations","tags":["Tracking"],"description":"List external tracking registrations.","x-status":"sandbox-implemented-live-disabled","x-live-availability":"service_not_enabled","x-required-scopes":{"anyOf":[{"allOf":["tracking.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackerListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/ReferenceFilter"},{"name":"carrier","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"trackingNumber","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}}]}},"/trackers/{trackerId}":{"get":{"operationId":"getTracker","summary":"Retrieve an external tracker and history","tags":["Tracking"],"description":"Retrieve an external tracker and history.","x-status":"sandbox-implemented-live-disabled","x-live-availability":"service_not_enabled","x-required-scopes":{"anyOf":[{"allOf":["tracking.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackerResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"trackerId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/manifest-candidates":{"get":{"operationId":"listManifestCandidates","summary":"Preflight shipments eligible for a manifest","tags":["Manifests"],"description":"Preflight shipments eligible for a manifest. Determine the ship date from persisted shipping options.shipDate first, then shippedAt. An unknown or mismatched date returns eligible=false with an issue; never infer the ship date from label creation time.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestCandidateListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"shippingAccountId","in":"query","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/WarehouseFilter"},{"name":"shipDate","in":"query","required":true,"schema":{"$ref":"#/components/schemas/CalendarDate"}}]}},"/manifests":{"post":{"operationId":"createManifest","summary":"Create one manifest for a compatible shipment group","tags":["Manifests"],"description":"Create one manifest for a compatible shipment group.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.write"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestResponse"}}}},"202":{"description":"Accepted; poll Location or GET /operations/{id}.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the durable operation."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestCreate"},"example":{"shipmentIds":["301","302"],"shipDate":"2026-11-01"}}}}},"get":{"operationId":"listManifests","summary":"List manifests","tags":["Manifests"],"description":"List manifests.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ShippingAccountFilter"}]}},"/manifests/{manifestId}":{"get":{"operationId":"getManifest","summary":"Retrieve a manifest and recovery state","tags":["Manifests"],"description":"Retrieve a manifest and recovery state.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"manifestId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/manifests/{manifestId}/documents":{"get":{"operationId":"listManifestDocuments","summary":"Retrieve manifest PDF links","tags":["Manifests"],"description":"Retrieve manifest PDF links.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"manifestId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}]}},"/manifests/{manifestId}/void":{"post":{"operationId":"voidManifestLocally","summary":"Release local manifest membership where permitted","tags":["Manifests"],"description":"Only local membership release; does not void the carrier document. Unknown/partial/document-failed results remain occupied and return 409 until reconciliation. Must not be presented as carrier cancellation.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["manifests.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"manifestId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ManifestVoidRequest"},"example":{"reason":"Reorganize local manifest group"}}}}}},"/address-verifications":{"post":{"operationId":"verifyAddress","summary":"Verify a postal address without changing saved records","tags":["Addresses"],"description":"Verify a postal address without changing saved records. Commercial gate: new live actions are disabled until the service price and quota policy are confirmed. Return 403/service_not_enabled before any upstream call, new fee or accrued amount; never silently execute for free. This is independent of the API key scope check. Test simulation and authorized completed-idempotency replay remain available without new charges. No public product-enablement API is provided.","x-status":"sandbox-implemented-live-disabled","x-live-availability":"service_not_enabled","x-required-scopes":{"anyOf":[{"allOf":["addresses.verify"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressVerificationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"description":"API key/resource permission denied, or live new-action capability has not been commercially enabled. service_not_enabled means no upstream call and no new fee/accrual occurred.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"},"examples":{"serviceNotEnabled":{"value":{"code":"service_not_enabled","message":"This live service is not enabled. Prices and quota policy must be confirmed before new requests are accepted.","requestId":"req_1001","data":null}}}}}},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressVerificationRequest"},"example":{"address":{"name":"Alex Chen","street1":"456 Pine St","city":"Seattle","state":"WA","postalCode":"98101","country":"US","phone":"2065550100","residential":true}}}}},"x-commercial-gate":{"environment":"live","enabled":false,"activationCondition":"service_price_and_quota_policy_confirmed","blockedStatus":403,"blockedCode":"service_not_enabled","testSimulationAllowed":true,"completedReplayAllowed":true}}},"/operations/{operationId}":{"get":{"operationId":"getOperation","summary":"Recover an asynchronous or uncertain business operation","tags":["Operations"],"description":"Authorization must match this operation type (purchase:labels.buy; void:labels.void; manifest:manifests.write; ship:fulfillments.ship), integration identity and resource restrictions. Possessing a different listed scope does not grant access. Completed label purchases remain recoverable after response loss; documents may carry freshly signed links.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["labels.buy"]},{"allOf":["labels.void"]},{"allOf":["manifests.write"]},{"allOf":["fulfillments.ship"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"operationId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}],"x-scope-by-operation-type":{"label_purchase":"labels.buy","label_void":"labels.void","manifest_create":"manifests.write","manifest_void":"manifests.write","fulfillment_ship":"fulfillments.ship"}}},"/orders":{"post":{"operationId":"createOrder","summary":"Create an order through the normal ingest pipeline","tags":["Orders"],"description":"Create an order through the normal ingest pipeline.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.write"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"},"example":{"externalId":"ERP-ORDER-1001","orderNumber":"SO-1001","currency":"USD","shipTo":{"name":"Alex Chen","street1":"456 Pine St","city":"Seattle","state":"WA","postalCode":"98101","country":"US","phone":"2065550100","residential":true},"warehouseId":"10","deliveryMethod":"label","items":[{"clientLineId":"line-1","productId":"501","quantity":2,"unitPrice":"19.95"}],"shippingAmount":"0.00","taxAmount":"0.00","discountAmount":"0.00"}}}}},"get":{"operationId":"listOrders","summary":"List sales orders","tags":["Orders"],"description":"List sales orders.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/ReferenceFilter"},{"name":"externalId","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"orderNumber","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":50}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","closed","canceled"]}}]}},"/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"Retrieve a sales order","tags":["Orders"],"description":"Retrieve a sales order.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]},"patch":{"operationId":"updateOrder","summary":"Edit allowed order fields","tags":["Orders"],"description":"Edit allowed order fields.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"428":{"$ref":"#/components/responses/Error428"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPatch"},"example":{"reference":"PO-2026-1200","note":"Customer requested side door delivery."}}}}}},"/orders/{orderId}/cancel":{"post":{"operationId":"cancelOrder","summary":"Cancel an order with business guards","tags":["Orders"],"description":"Cancel an order with business guards.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.cancel"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCancelRequest"},"example":{"reason":"Customer canceled"}}}}}},"/orders/{orderId}/hold":{"post":{"operationId":"holdOrder","summary":"Hold an order and eligible related fulfillments","tags":["Orders"],"description":"Hold an order and eligible related fulfillments.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HoldRequest"},"example":{"reason":"Customer address needs confirmation","holdUntil":"2026-11-02 18:00:00"}}}}}},"/orders/{orderId}/release":{"post":{"operationId":"releaseOrder","summary":"Release an order hold","tags":["Orders"],"description":"Uses the existing order release cascade only where the affected fulfillment hold is unambiguous. The current domain has no independent hold-source tracking. The public adapter must reject ambiguous shared-order/manual-hold release with 409 before mutation, not promise preservation or silently change shared hold semantics. No status rewind or inventory movement.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonRequest"},"example":{"reason":"Address confirmed"}}}}}},"/orders/{orderId}/fulfillments":{"get":{"operationId":"listOrderFulfillments","summary":"List fulfillments related to an order","tags":["Orders"],"description":"List fulfillments related to an order.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["orders.read","fulfillments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"orderId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"}]}},"/fulfillments":{"get":{"operationId":"listFulfillments","summary":"List fulfillment plans","tags":["Fulfillments"],"description":"List fulfillment plans.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["fulfillments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"name":"orderId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","label_purchased","shipped","canceled","voided"]}}]}},"/fulfillments/{fulfillmentId}":{"get":{"operationId":"getFulfillment","summary":"Retrieve a fulfillment plan","tags":["Fulfillments"],"description":"Retrieve a fulfillment plan.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["fulfillments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]},"patch":{"operationId":"updateFulfillment","summary":"Edit a fulfillment shipping plan","tags":["Fulfillments"],"description":"Edit a fulfillment shipping plan.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["fulfillments.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"428":{"$ref":"#/components/responses/Error428"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentPatch"},"example":{"packages":[{"packageNo":1,"length":"12","width":"9","height":"3","weight":"2","dimensionUnit":"in","weightUnit":"lb","shape":"box"}],"plannedShipDate":"2026-11-02"}}}}}},"/fulfillments/{fulfillmentId}/rate-quotes":{"post":{"operationId":"quoteFulfillment","summary":"Quote the persisted fulfillment shipping plan","tags":["Fulfillments"],"description":"Quote the persisted fulfillment shipping plan.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["rates.read","fulfillments.read"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateQuoteResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentRateQuoteRequest"},"example":{"expectedVersion":"7","shippingAccountIds":["41"]}}}}}},"/fulfillments/{fulfillmentId}/ship":{"post":{"operationId":"shipFulfillment","summary":"Confirm physical shipment or pickup","tags":["Fulfillments"],"description":"Uses the existing inventory-aware shared ship transition and current account trigger. Does not buy labels; label purchase may already have auto-shipped under account settings, in which case idempotent state guards apply. Reject unsupported partial/dropship handling explicitly.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["fulfillments.ship"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentResponse"}}}},"202":{"description":"Accepted; poll Location or GET /operations/{id}.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the durable operation."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipRequest"},"example":{"mode":"label","expectedVersion":"8"}}}}}},"/fulfillments/{fulfillmentId}/split":{"post":{"operationId":"splitFulfillment","summary":"Split unexecuted quantities into a new fulfillment","tags":["Fulfillments"],"description":"Split unexecuted quantities into a new fulfillment.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["fulfillments.write"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitResultResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"fulfillmentId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SplitRequest"},"example":{"expectedVersion":"4","items":[{"fulfillmentItemId":"601","moveQuantity":1}]}}}}}},"/products":{"post":{"operationId":"createProduct","summary":"Create a product, parent, variant or component product","tags":["Products"],"description":"Create a product, parent, variant or component product.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["products.write"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductCreate"},"example":{"type":"single","sku":"TEE-BLK-M","name":"Black cotton T-shirt M","currency":"USD","salePrice":"19.95","trackInventory":true}}}}},"get":{"operationId":"listProducts","summary":"List the unified product catalog","tags":["Products"],"description":"All six types are first-class products. parentId selects variants; component definitions are on bundle/assembly products. No separate variants or SKU inventory master is introduced.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["products.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"name":"sku","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":64}},{"name":"parentId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ProductType"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","inactive"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":200}}]}},"/products/{productId}":{"get":{"operationId":"getProduct","summary":"Retrieve a product with options and components","tags":["Products"],"description":"Retrieve a product with options and components.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["products.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"productId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}]},"patch":{"operationId":"updateProduct","summary":"Edit or inactivate a product","tags":["Products"],"description":"Edit or inactivate a product.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["products.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"428":{"$ref":"#/components/responses/Error428"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"productId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPatch"},"example":{"status":"inactive"}}}}}},"/products/{productId}/archive":{"post":{"operationId":"archiveProduct","summary":"Inactivate a product without deleting its history","tags":["Products"],"description":"Sets status=inactive through the normal product service. Does not hard-delete, remove BOM links, cancel orders or mutate stock. Existing reference/type business guards still apply; replay returns the original result.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["products.write"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"productId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonRequest"},"example":{"reason":"Product discontinued"}}}}}},"/warehouses":{"get":{"operationId":"listWarehouses","summary":"Discover authorized warehouses and shipping origins","tags":["Inventory"],"description":"Always applies integration warehouse restrictions. Shipping-only credentials receive origin/capability metadata, not inventory balances.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]},{"allOf":["fulfillments.read"]},{"allOf":["rates.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WarehouseListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"}]}},"/locations":{"get":{"operationId":"listLocations","summary":"Discover locations in authorized warehouses","tags":["Inventory"],"description":"Discover locations in authorized warehouses.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["storage","receiving","returns","hold"]}}]}},"/inventory":{"get":{"operationId":"listStocks","summary":"Read product-by-warehouse stock balances","tags":["Inventory"],"description":"Read product-by-warehouse stock balances. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ProductFilter"}]}},"/inventory/locations":{"get":{"operationId":"listLocationStocks","summary":"Read location-level physical stock","tags":["Inventory"],"description":"Read location-level physical stock. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LocationStockListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ProductFilter"},{"name":"locationId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/inventory/transactions":{"get":{"operationId":"listInventoryTransactions","summary":"Read the immutable inventory ledger","tags":["Inventory"],"description":"Stable order by occurredAt,id. No transaction mutation endpoints. These records represent executed business changes, not requested future quantities. Source order, fulfillment and store references must also be within the credential resource restrictions before pagination. A restricted ledger may contain fewer rows than the full physical warehouse ledger; stock quantities are never reduced to match those visible rows.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryTransactionListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ProductFilter"},{"name":"locationId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"occurredAfter","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UtcTimestamp"}},{"name":"sourceId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}}]}},"/inventory/adjustments":{"post":{"operationId":"createInventoryAdjustment","summary":"Apply an atomic guarded stock adjustment","tags":["Inventory"],"description":"Apply an atomic guarded stock adjustment.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.adjust"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryAdjustmentCreate"},"example":{"warehouseId":"10","reasonCode":"correction","reason":"Cycle check found two additional units","lines":[{"productId":"501","locationId":"22","mode":"delta","quantityDelta":2,"expectedOnHand":20}]}}}}}},"/inventory/reservations":{"post":{"operationId":"createManualReservation","summary":"Create a manual warehouse-level stock hold","tags":["Inventory"],"description":"Create a manual warehouse-level stock hold.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.reserve"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationCreate"},"example":{"warehouseId":"10","productId":"501","quantity":3,"reason":"Reserved for upcoming promotion","expiresAt":"2026-11-03 18:00:00"}}}}},"get":{"operationId":"listManualReservations","summary":"List active manual stock holds","tags":["Inventory"],"description":"Only active manual holds; fully released/expired rows are not retained as resources by the current model. Audit/operation receipts are separate. Fulfillment holds are not editable here.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"},{"$ref":"#/components/parameters/WarehouseFilter"},{"$ref":"#/components/parameters/ProductFilter"}]}},"/inventory/reservations/{reservationId}/releases":{"post":{"operationId":"releaseManualReservation","summary":"Release all or part of a manual stock hold","tags":["Inventory"],"description":"Release all or part of a manual stock hold.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["inventory.reserve"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationReleaseResultResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"reservationId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReservationRelease"},"example":{"quantity":1,"reason":"Promotion requirement reduced"}}}}}},"/webhook-endpoints":{"post":{"operationId":"createWebhookEndpoint","summary":"Create an environment-scoped webhook endpoint","tags":["Webhooks"],"description":"Create an environment-scoped webhook endpoint. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreatedResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointCreate"},"example":{"url":"https://integrator.example.com/webhooks/shipbuy","description":"ERP shipment updates","events":["shipment.purchased","tracking.updated"]}}}},"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}},"get":{"operationId":"listWebhookEndpoints","summary":"List this integration webhook endpoints","tags":["Webhooks"],"description":"List this integration webhook endpoints. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/UpdatedAfter"}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/webhook-endpoints/{endpointId}":{"get":{"operationId":"getWebhookEndpoint","summary":"Retrieve webhook endpoint configuration","tags":["Webhooks"],"description":"Retrieve webhook endpoint configuration. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}},"patch":{"operationId":"updateWebhookEndpoint","summary":"Edit or disable webhook delivery","tags":["Webhooks"],"description":"Edit or disable webhook delivery. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"ETag":{"$ref":"#/components/headers/ETag"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"412":{"$ref":"#/components/responses/Error412"},"422":{"$ref":"#/components/responses/Error422"},"428":{"$ref":"#/components/responses/Error428"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/IfMatch"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointPatch"},"example":{"enabled":false}}}},"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}},"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete a webhook endpoint","tags":["Webhooks"],"description":"Delete a webhook endpoint. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"204":{"description":"Deleted/disabled; existing event audit remains readable under retention policy.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/events":{"get":{"operationId":"listEvents","summary":"List recoverable events for this integration","tags":["Webhooks"],"description":"Only events visible under current resource scopes and integration restrictions, within published retention. Read events to reconcile missed deliveries; permissions are rechecked on every read. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"createdAfter","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UtcTimestamp"}},{"name":"type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/WebhookEventType"}}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/events/{eventId}":{"get":{"operationId":"getEvent","summary":"Retrieve one recoverable webhook event","tags":["Webhooks"],"description":"Retrieve one recoverable webhook event. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"410":{"$ref":"#/components/responses/Error410"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"eventId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/webhook-endpoints/{endpointId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"Inspect webhook delivery attempts","tags":["Webhooks"],"description":"Inspect webhook delivery attempts. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryListResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"},{"name":"eventId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}}],"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/webhook-endpoints/{endpointId}/events/{eventId}/redeliver":{"post":{"operationId":"redeliverWebhookEvent","summary":"Queue redelivery of the same event","tags":["Webhooks"],"description":"Uses the same event ID and a new delivery ID. Current endpoint destination, environment and resource scopes must still permit delivery. Does not repeat the business operation or create a billable tracker/verification. Event subscribe/read/delivery additionally requires the relevant resource read scope (see x-event-resource-scopes); operation events require the matching operation action scope. Revoked scopes stop delivery and access immediately.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["webhooks.manage"]}]},"security":[{"ApiKey":[]}],"responses":{"201":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Location":{"schema":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"description":"URL of the created resource or recoverable result."},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"410":{"$ref":"#/components/responses/Error410"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"endpointId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"eventId","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonRequest"},"example":{"reason":"Receiver recovered after outage"}}}},"x-event-resource-scopes":{"shipment.purchased":"shipments.read","shipment.voided":"shipments.read","shipment.refund_updated":"shipments.read","tracking.updated":"tracking.read","manifest.updated":"manifests.read","order.created":"orders.read","order.updated":"orders.read","order.canceled":"orders.read","fulfillment.updated":"fulfillments.read","fulfillment.shipped":"fulfillments.read","product.created":"products.read","product.updated":"products.read","inventory.changed":"inventory.read"}}},"/usage":{"get":{"operationId":"getUsage","summary":"Read API usage for a bounded period","tags":["Usage"],"description":"End is exclusive and must be after start; maximum range is 93 days. Only the authenticated test/live environment is returned; test usage cannot charge live funds.","x-status":"implemented-runtime-acceptance-pending","x-required-scopes":{"anyOf":[{"allOf":["usage.read"]}]},"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Success.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"400":{"$ref":"#/components/responses/Error400"},"401":{"$ref":"#/components/responses/Error401"},"403":{"$ref":"#/components/responses/Error403"},"404":{"$ref":"#/components/responses/Error404"},"409":{"$ref":"#/components/responses/Error409"},"422":{"$ref":"#/components/responses/Error422"},"429":{"$ref":"#/components/responses/Error429"},"500":{"$ref":"#/components/responses/Error500"},"503":{"$ref":"#/components/responses/Error503"}},"parameters":[{"name":"periodStart","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UtcTimestamp"}},{"name":"periodEnd","in":"query","required":true,"schema":{"$ref":"#/components/schemas/UtcTimestamp"}}]}}},"webhooks":{"businessEvent":{"post":{"operationId":"receiveShipbuyEvent","summary":"Receive a signed Shipbuy business event","x-status":"implemented-runtime-acceptance-pending","description":"Receiver contract. Verify Shipbuy-Signature before parsing/processing; API key credentials are not sent to your endpoint. Persist event.id for deduplication, then return 2xx. See x-webhook-contract.","security":[],"parameters":[{"name":"Shipbuy-Event-Id","in":"header","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"Shipbuy-Delivery-Id","in":"header","required":true,"schema":{"$ref":"#/components/schemas/ResourceId"}},{"name":"Shipbuy-Signature","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":300,"pattern":"^t=[0-9]+,v1=[a-f0-9]{64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"},"example":{"id":"evt_701","type":"shipment.purchased","environment":"test","createdAt":"2026-11-01 18:30:00","data":{"resourceType":"shipment","resourceId":"301","resourceVersion":"1","resourceUrl":"https://api.shipbuy.com/v2/shipments/301","operationId":"op_901"}}}}},"responses":{"200":{"description":"Event durably accepted; duplicate event is also acknowledged."},"400":{"description":"Invalid payload/signature; sender records failure and applies bounded retry policy."},"503":{"description":"Receiver temporarily unavailable; sender retries without redoing the business operation."}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Opaque tenant/integration credential; environment and scope/resource restrictions are server-bound. x-required-scopes on each operation applies identically to API keys. Secret shown once and stored hashed; no API secret pair or query-string authentication. Initial authentication applies equally to merchant-owned integrations and third-party SaaS integrations. The independent scope catalog is x-scopes; OpenAPI apiKey security requirement values remain empty arrays by definition."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":100,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]*$"},"description":"Required on every business write, including quotes, verification and DELETE. New logical action=new key; retry=same key and canonical payload. Namespace account+environment+stable integrationId+HTTP method+canonical path; credential rotation within one integration preserves integrationId. Same key/different payload=409. Lookup follows authentication/resource authorization and precedes If-Match/freshness checks so a completed retry returns its first result. General receipts retained >=7 days; financial/inventory side effects retain durable business association or tombstone beyond receipt expiry to prevent re-execution. In-flight/unknown result returns its operation, never a blind repurchase. Secret-creation responses are the deliberate exception to identical replay: the resource is replayed, but its one-time secret is null with secretUnavailable=true; use management rotation to recover."},"IfMatch":{"name":"If-Match","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"pattern":"^\"[^\"\\r\\n]+\"$"},"description":"Exact strong ETag from the latest resource read. Required for PATCH; absent=428, stale=412. Quote/ship/split actions use explicit expectedVersion. An authorized idempotent replay returns its original committed result even if the resource is now newer."},"Cursor":{"name":"cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2048},"description":"Opaque continuation bound to tenant/environment/integration scope, filters, snapshot high-watermark and stable sort (updatedAt,id or documented resource-specific sort). Do not alter filters between pages. Incremental synchronization must include archive/deletion tombstones within the published retention window; snapshot expiry fails explicitly and requires a new scan."},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"UpdatedAfter":{"name":"updatedAfter","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UtcTimestamp"},"description":"Exclusive UTC updated-time lower bound. For incremental sync keep a small overlap and deduplicate by id/version; cursor is authoritative within a scan."},"WarehouseFilter":{"name":"warehouseId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},"ProductFilter":{"name":"productId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},"ShippingAccountFilter":{"name":"shippingAccountId","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ResourceId"}},"ReferenceFilter":{"name":"reference","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}}},"headers":{"RequestId":{"description":"Server request correlation identifier.","schema":{"$ref":"#/components/schemas/ResourceId"}},"ETag":{"description":"Strong quoted resource revision for subsequent If-Match.","schema":{"type":"string","minLength":1,"maxLength":120}},"RetryAfter":{"description":"Seconds before retry/poll; respect for 429/503/202.","schema":{"type":"integer","minimum":1,"maximum":86400}},"RateLimitLimit":{"description":"Current applicable request quota in this window; actual measured limits are configured, no fixed quota is promised by this version.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},"RateLimitRemaining":{"description":"Remaining requests in the current rate-limit window.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}},"RateLimitReset":{"description":"UTC Unix epoch seconds when the applicable window resets.","schema":{"type":"integer","minimum":0,"maximum":9007199254740991}}},"responses":{"Error400":{"description":"Malformed JSON, unsupported query or invalid request syntax.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error401":{"description":"Missing, invalid, expired or revoked API key credential.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error403":{"description":"Scope, tenant/environment/warehouse/carrier-account constraint or plan entitlement denied. New live external-tracker registration and standalone address verification also return service_not_enabled until price and quota policies are confirmed; no upstream call or new fee/accrual is permitted.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error404":{"description":"Resource absent or not visible in the authorized tenant/environment.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error409":{"description":"Business conflict, changed idempotency payload, stale quote, pending side effect or insufficient stock/funds.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error412":{"description":"If-Match does not match the current resource revision.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error422":{"description":"Field/business validation failed; details identify invalid fields.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error428":{"description":"Required concurrency precondition missing.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error429":{"description":"Rate or paid-service limit exceeded. Respect Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error500":{"description":"Unexpected server error; use requestId and query operation before retrying a side effect.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error503":{"description":"Service temporarily unavailable; upstream outcome may be unknown, query/replay the operation.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"Error410":{"description":"The event has expired from the retention period.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"schemas":{"ResourceId":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-z0-9][A-Za-z0-9_-]*$","description":"Stable Shipbuy resource identifier serialized as a string. Treat as opaque; never confuse with a carrier identifier or display number.","examples":["301"]},"UtcTimestamp":{"type":"string","minLength":19,"maxLength":19,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}$","description":"UTC date/time, exactly yyyy-MM-dd HH:mm:ss. This project convention deliberately is not RFC 3339; all time zones are UTC unless a field explicitly says local calendar date.","examples":["2026-11-01 18:30:00"]},"CalendarDate":{"type":"string","minLength":10,"maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","description":"Calendar date yyyy-MM-dd; shipping dates use the ship-from warehouse time zone, or the account time zone for custom origins."},"Environment":{"type":"string","enum":["test","live"],"description":"Immutable credential/integration environment. Same resource API hostname; tenant data, IDs, quotes, events, wallet simulations and idempotency namespaces are isolated. No environment switch in request bodies."},"DecimalAmount":{"type":"string","minLength":1,"maxLength":16,"pattern":"^(0|[1-9][0-9]{0,11})\\.[0-9]{2}$","description":"Non-negative decimal monetary amount as a string; never IEEE floating point.","examples":["12.34"]},"SignedDecimalAmount":{"type":"string","minLength":1,"maxLength":17,"pattern":"^-?(0|[1-9][0-9]{0,11})\\.[0-9]{2}$","examples":["-2.50"]},"DecimalMeasurement":{"type":"string","minLength":1,"maxLength":16,"pattern":"^(0|[1-9][0-9]{0,9})(\\.[0-9]{1,4})?$","description":"Decimal measurement string; dimensions and weight must be greater than zero when purchasing."},"Currency":{"type":"string","minLength":3,"maxLength":3,"pattern":"^[A-Z]{3}$","examples":["USD"]},"CountryCode":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$","examples":["US"]},"ResourceVersion":{"type":"string","minLength":1,"maxLength":100,"description":"Opaque resource revision. The ETag header is its quoted representation; send the exact ETag as If-Match."},"ClientMetadata":{"type":"object","maxProperties":20,"propertyNames":{"type":"string","minLength":1,"maxLength":40},"additionalProperties":{"type":"string","minLength":0,"maxLength":500},"description":"Client-owned string metadata only. No secrets or card data. Not used for authorization or business rules."},"ErrorDetail":{"type":"object","additionalProperties":false,"properties":{"path":{"type":"string","minLength":1,"maxLength":250},"code":{"type":"string","minLength":1,"maxLength":80},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","message"]},"ApiError":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","enum":["bad_request","unauthorized","forbidden","not_found","conflict","validation_error","rate_limited","internal_error","unavailable","idempotency_conflict","quote_expired","stale_resource","precondition_required","insufficient_funds","operation_pending","unsupported_capability","inventory_not_tracked","insufficient_available_stock","scope_mismatch","environment_mismatch","service_not_enabled","event_expired","resource_reset"]},"message":{"type":"string","minLength":1,"maxLength":2000},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"null"},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"minItems":0,"maxItems":100},"retryAfterSeconds":{"type":"integer","minimum":0,"maximum":86400}},"required":["code","message","requestId","data"],"description":"Stable public error. Never includes upstream credentials, cost prices, stack traces or unfiltered carrier responses. A timeout is not proof a purchase failed; retrieve the operation using the same idempotency key."},"Address":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":0,"maxLength":100},"company":{"type":"string","minLength":0,"maxLength":100},"street1":{"type":"string","minLength":1,"maxLength":200},"street2":{"type":"string","minLength":0,"maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","minLength":0,"maxLength":100},"postalCode":{"type":"string","minLength":1,"maxLength":20},"country":{"$ref":"#/components/schemas/CountryCode"},"phone":{"type":"string","minLength":0,"maxLength":30},"email":{"type":"string","minLength":0,"maxLength":254},"residential":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["street1","city","postalCode","country"],"description":"Original address is preserved. Country-specific postal validation and carrier print-field limits are separate checks; do not silently truncate. Residential null means unknown."},"AddressIssue":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","minLength":1,"maxLength":80},"field":{"type":"string","enum":["name","company","street1","street2","city","state","postalCode","country","phone","email","address"]},"severity":{"type":"string","enum":["info","warning","error"]},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["code","severity","message"]},"AddressVerificationRequest":{"type":"object","additionalProperties":false,"properties":{"address":{"$ref":"#/components/schemas/Address"}},"required":["address"],"description":"Standalone postal verification subject to the live new-action gate. Verification options are currently fixed by the service; cache identity must include those effective options. Local formatting alone is not a billable postal verdict."},"AddressVerification":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"status":{"type":"string","enum":["valid","corrected","unverifiable","invalid","unverified"]},"originalAddress":{"$ref":"#/components/schemas/Address"},"suggestedAddress":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"type":"null"}]},"issues":{"type":"array","items":{"$ref":"#/components/schemas/AddressIssue"},"minItems":0,"maxItems":100},"verificationSupported":{"type":"boolean"},"providerAvailable":{"type":"boolean"},"verifiedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"billable":{"type":"boolean","description":"True only for a newly metered, completed authoritative postal validity verdict after live commercial enablement. False for test, cache reuse, formatting/coverage failures, provider failures/timeouts and indeterminate results. Does not itself authorize or determine a monetary charge."}},"required":["id","environment","status","originalAddress","suggestedAddress","issues","verificationSupported","providerAvailable","verifiedAt","billable"],"description":"Initial geographic capability is US and supported US postal territories. Unsupported country returns unverified; provider failure is not an invalid-address verdict. Suggested corrections never mutate an order or fulfillment. One completed authoritative valid/invalid verdict is eligible for one billable verification; corrected is eligible only if it expresses a completed valid-address verdict, not mere normalization. Formatting errors, unsupported coverage, timeouts, provider failures and indeterminate/unverifiable results are not billable. Provider-permitted 24-hour cache reuse for account+environment+normalized input+effective verification options never causes a second charge. Prices and quotas remain unconfirmed: new live verification is gated off before provider/fee activity; test is simulated and nonbillable."},"ParcelInput":{"type":"object","additionalProperties":false,"properties":{"packageNo":{"type":"integer","minimum":1,"maximum":100},"length":{"$ref":"#/components/schemas/DecimalMeasurement"},"width":{"$ref":"#/components/schemas/DecimalMeasurement"},"height":{"$ref":"#/components/schemas/DecimalMeasurement"},"weight":{"$ref":"#/components/schemas/DecimalMeasurement"},"dimensionUnit":{"type":"string","enum":["in","cm"]},"weightUnit":{"type":"string","enum":["lb","oz","kg","g"]},"shape":{"type":"string","enum":["box","envelope","irregular"],"default":"box"},"packageTypeId":{"$ref":"#/components/schemas/ResourceId"},"carrierPackageType":{"type":"string","minLength":1,"maxLength":64},"insuredValue":{"$ref":"#/components/schemas/DecimalAmount"}},"required":["packageNo","length","width","height","weight","dimensionUnit","weightUnit"],"description":"packageNo is dense 1..N. All packages in a purchase share dimensions/weight units. Saved or carrier packaging must agree with supplied measurements; unsupported shapes fail explicitly."},"CustomsItem":{"type":"object","additionalProperties":false,"properties":{"description":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"unitValue":{"$ref":"#/components/schemas/DecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"hsCode":{"type":"string","minLength":1,"maxLength":64},"originCountry":{"$ref":"#/components/schemas/CountryCode"},"productId":{"$ref":"#/components/schemas/ResourceId"},"unitWeight":{"allOf":[{"$ref":"#/components/schemas/DecimalAmount"}],"description":"Positive weight of one commodity unit. Supply with weightUnit. Required by FedEx Direct for international shipments; multiplied by quantity exactly once."},"weightUnit":{"type":"string","enum":["lb","oz","kg","g"],"description":"Unit for unitWeight; supply both fields together."},"commercialUnitPrice":{"$ref":"#/components/schemas/DecimalAmount","description":"Optional commercial sale price per unit, independent of unitValue (the declared customs value per unit). Defaults to unitValue when omitted; requires FedEx Direct and must be less than 100000."},"quantityUnits":{"type":"string","enum":["PCS","PC","EA"],"description":"Optional FedEx Direct count unit; omitted retains PCS. Does not change the numeric quantity."},"numberOfPieces":{"type":"integer","minimum":0,"maximum":9999,"description":"Optional FedEx Direct commodity piece count, independent of the declared quantity."}},"required":["description","quantity","unitValue","currency","originCountry"]},"Customs":{"type":"object","additionalProperties":false,"properties":{"contentsType":{"type":"string","enum":["merchandise","gift","documents","sample","returned_goods"]},"nonDeliveryOption":{"type":"string","enum":["return","abandon"]},"signer":{"type":"string","minLength":1,"maxLength":100},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomsItem"},"minItems":1,"maxItems":100},"dutiesBillingType":{"type":"string","enum":["sender","receiver","third_party"],"description":"Duties and taxes payer, independent of shipping charges. Defaults to sender. External payers require a customer-owned FedEx Direct connection."},"dutiesBillAccount":{"type":"string","pattern":"^[0-9]{9}$","description":"Required when dutiesBillingType is receiver or third_party; never defaults to the transportation payer account."},"dutiesBillCountry":{"$ref":"#/components/schemas/CountryCode"},"dutiesBillZip":{"type":"string","minLength":1,"maxLength":10},"details":{"$ref":"#/components/schemas/CustomsDetails","description":"Optional typed international information supported by FedEx Direct. Other connections reject it instead of silently dropping it."}},"required":["contentsType","nonDeliveryOption","items"],"description":"Required for shipments crossing a customs boundary; values are declared customer values, not shipping costs."},"CustomsTaxId":{"type":"object","additionalProperties":false,"properties":{"number":{"type":"string","minLength":1,"maxLength":18},"type":{"type":"string","enum":["PERSONAL_NATIONAL","PERSONAL_STATE","FEDERAL","BUSINESS_NATIONAL","BUSINESS_STATE","BUSINESS_UNION"]},"usage":{"type":"string","minLength":1,"maxLength":100},"effectiveDate":{"$ref":"#/components/schemas/CalendarDate"},"expirationDate":{"$ref":"#/components/schemas/CalendarDate"}},"required":["number","type"]},"CustomsImporterAddress":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":100},"phone":{"type":"string","maxLength":30},"email":{"type":"string","maxLength":254},"street1":{"type":"string","maxLength":200},"street2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"zip":{"type":"string","maxLength":20},"country":{"$ref":"#/components/schemas/CountryCode"},"residential":{"type":"boolean"}},"required":["phone","street1","city","country"],"description":"Importer contact and address. Supply at least one of name or company. Carrier limits apply before purchase."},"CustomsImporter":{"type":"object","additionalProperties":false,"properties":{"address":{"$ref":"#/components/schemas/CustomsImporterAddress"},"accountNumber":{"type":"string","pattern":"^[0-9]{9}$"},"taxIds":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CustomsTaxId"}}},"required":["address"]},"CustomsRecipientId":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["COMPANY","INDIVIDUAL","PASSPORT"]},"value":{"type":"string","minLength":1,"maxLength":40}},"required":["type","value"]},"CustomsMoney":{"type":"object","additionalProperties":false,"properties":{"amount":{"$ref":"#/components/schemas/DecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"}},"required":["amount","currency"],"description":"A non-negative customer-supplied invoice amount in the same currency as the commodities; never derived from transportation rates. FedEx requires each amount to be less than 100000."},"CustomsInvoice":{"type":"object","additionalProperties":false,"properties":{"termsOfSale":{"type":"string","pattern":"^[A-Za-z]{3}$"},"declarationStatement":{"type":"string","minLength":1,"maxLength":1000},"specialInstructions":{"type":"string","minLength":1,"maxLength":1000},"freightCharge":{"$ref":"#/components/schemas/CustomsMoney"},"packingCosts":{"$ref":"#/components/schemas/CustomsMoney"},"handlingCosts":{"$ref":"#/components/schemas/CustomsMoney"},"taxesOrMiscellaneousCharge":{"$ref":"#/components/schemas/CustomsMoney"},"shipmentPurpose":{"type":"string","enum":["GIFT","NOT_SOLD","PERSONAL_EFFECTS","REPAIR_AND_RETURN","SAMPLE","SOLD"]},"paymentTerms":{"type":"string","minLength":1,"maxLength":1000},"comments":{"type":"array","maxItems":2,"items":{"type":"string","minLength":1,"maxLength":1000},"description":"Explicit comments replace the contents explanation on the invoice; at most two are printed by FedEx."},"customerReferences":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/CustomsInvoiceReference"},"description":"Reference types must be unique. These belong to the commercial invoice, not label references."},"taxesOrMiscellaneousChargeType":{"type":"string","enum":["COMMISSIONS","DISCOUNTS","HANDLING_FEES","OTHER","ROYALTIES_AND_LICENSE_FEES","TAXES"],"description":"Requires taxesOrMiscellaneousCharge."}}},"CustomsInvoiceReference":{"type":"object","additionalProperties":false,"required":["type","value"],"properties":{"type":{"type":"string","enum":["CUSTOMER_REFERENCE","DEPARTMENT_NUMBER","INVOICE_NUMBER","P_O_NUMBER"]},"value":{"type":"string","minLength":1,"maxLength":30}}},"CustomsDutiesPayer":{"type":"object","additionalProperties":false,"properties":{"contactName":{"type":"string","minLength":1,"maxLength":70},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"}},"description":"Optional duties payer contact; account selection remains dutiesBillingType and dutiesBillAccount. Country must agree with dutiesBillCountry when supplied."},"CustomsExportDetail":{"type":"object","additionalProperties":false,"properties":{"b13AFilingOption":{"type":"string","enum":["NOT_REQUIRED","MANUALLY_ATTACHED","FILED_ELECTRONICALLY","SUMMARY_REPORTING","FEDEX_TO_STAMP"]},"exportComplianceStatement":{"type":"string","minLength":1,"maxLength":100}},"description":"Customer-supplied export filing information, never inferred. If eelPfc is also supplied the statements must agree. Does not file an export declaration or establish a license exemption."},"CustomsOption":{"type":"object","additionalProperties":false,"required":["type"],"properties":{"type":{"type":"string","enum":["COURTESY_RETURN_LABEL","EXHIBITION_TRADE_SHOW","FAULTY_ITEM","FOLLOWING_REPAIR","FOR_REPAIR","ITEM_FOR_LOAN","OTHER","REJECTED","REPLACEMENT","TRIAL"]},"description":{"type":"string","minLength":1,"maxLength":1000}},"description":"Customer-supplied customs reason; OTHER requires a description. Service and direction eligibility still applies."},"CustomsElectronicDocuments":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["uploaded_documents","fedex_generated"]},"documentRefs":{"type":"array","maxItems":5,"items":{"type":"string","format":"uuid"}},"letterheadRef":{"type":"string","format":"uuid"},"signatureRef":{"type":"string","format":"uuid"}},"required":["mode"],"description":"Pre-shipment ETD only. References must come from an authorized upload to the same customer-owned FedEx Direct account and environment. uploaded_documents requires an uploaded commercial/pro forma invoice; fedex_generated requires actual customer letterhead and signature image references. References expire after at most 10 days. No post-shipment upload is implied."},"CustomsDetails":{"type":"object","additionalProperties":false,"properties":{"shipperTaxIds":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CustomsTaxId"}},"recipientTaxIds":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/CustomsTaxId"}},"importerOfRecord":{"$ref":"#/components/schemas/CustomsImporter"},"recipientCustomsId":{"$ref":"#/components/schemas/CustomsRecipientId"},"commercialInvoice":{"$ref":"#/components/schemas/CustomsInvoice"},"electronicDocuments":{"$ref":"#/components/schemas/CustomsElectronicDocuments"},"insuranceCharge":{"$ref":"#/components/schemas/CustomsMoney","description":"Customer-declared insurance charge for customs; does not purchase shipment insurance or change declared customs value."},"dutiesPayer":{"$ref":"#/components/schemas/CustomsDutiesPayer"},"exportDetail":{"$ref":"#/components/schemas/CustomsExportDetail"},"customsOption":{"$ref":"#/components/schemas/CustomsOption"}}},"ShippingOptions":{"type":"object","additionalProperties":false,"allOf":[{"if":{"properties":{"billingType":{"enum":["receiver","third_party"]}},"required":["billingType"]},"then":{"required":["billAccount","billCountry","billZip"],"properties":{"billAccount":{"type":"string"},"billCountry":{"type":"string"},"billZip":{"type":"string"}}},"else":{"properties":{"billAccount":{"type":"null"},"billCountry":{"type":"null"},"billZip":{"type":"null"}}}}],"properties":{"shipDate":{"$ref":"#/components/schemas/CalendarDate"},"billingType":{"anyOf":[{"type":"string","enum":["sender","receiver","third_party"]},{"type":"null"}],"description":"Transportation charges payer, independent of customs.dutiesBillingType. Standalone shipping defaults to sender when the billing group is omitted or null. receiver bills the recipient account; third_party bills a separate account. The selected carrier connection must support that payer. FedEx Direct external billing requires a customer-owned account and returns public LIST estimates, not the payer's negotiated price."},"billAccount":{"anyOf":[{"type":"string","pattern":"^[A-Za-z0-9]{1,30}$"},{"type":"null"}],"description":"Transportation payer account, required together with billCountry and billZip for receiver or third_party. Must be a JSON string; FedEx additionally requires exactly nine digits. Omit or use null for sender; this never defaults to a duties payer account."},"billCountry":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}],"description":"Transportation payer's billing country, required for receiver or third_party. This is not the shipment origin/destination and does not select the duties payer."},"billZip":{"anyOf":[{"type":"string","minLength":1,"maxLength":10,"pattern":"^(?! *$)[ -~]{1,10}$"},{"type":"null"}],"description":"Transportation payer's billing postal code, required for receiver or third_party. Use a nonblank JSON string of printable ASCII characters; do not infer it from the ship-from address."},"signature":{"type":"string","enum":["none","signature","adult_signature"]},"saturdayDelivery":{"type":"boolean"},"labelReference1":{"type":"string","minLength":0,"maxLength":100},"labelReference2":{"type":"string","minLength":0,"maxLength":100},"fedex":{"$ref":"#/components/schemas/FedexOptions"}},"description":"Portable shipping options and optional typed FedEx Direct services. On fulfillment PATCH, omitted or null fields preserve their stored values; a supplied fedex object replaces the entire FedEx option group, and an empty object clears it. Carrier eligibility, account agreements and service combinations are validated before quoting or purchasing. Transportation billing is an atomic group: omit all four fields or use null to preserve it on PATCH; explicit sender clears the three billing details, while receiver or third_party requires all four fields together. Nonnull billing details without an external billingType are rejected. Duties and taxes remain independently configured under customs. Buying a frozen quote does not accept payer overrides.","examples":[{"billingType":"third_party","billAccount":"123456789","billCountry":"US","billZip":"10001"}]},"FedexOptions":{"type":"object","additionalProperties":false,"description":"Options supported only by FedEx Direct (newfedex); other providers reject active FedEx options. These fields do not grant carrier account permissions. Alcohol, authenticated delivery and other special services may require FedEx agreements. Empty objects clear the stored group on fulfillment PATCH. Keys, secrets and arbitrary upstream fields are not accepted.","properties":{"alcoholRecipientType":{"type":"string","enum":["LICENSEE","CONSUMER"]},"holdAtLocation":{"$ref":"#/components/schemas/FedexHoldAtLocation"},"homeDeliveryPremium":{"$ref":"#/components/schemas/FedexHomeDeliveryPremium"},"emailNotification":{"$ref":"#/components/schemas/FedexEmailNotification"},"authenticatedDelivery":{"type":"boolean"},"printReturnLabel":{"type":"boolean","description":"Request a printed return shipment label through the supported Ship workflow."},"customerTransactionId":{"type":"string","minLength":1,"maxLength":40,"description":"Optional FedEx transaction reference; does not replace ShipBuy idempotency keys."},"returnTransitTimes":{"type":"boolean"},"transportPayer":{"type":"object","additionalProperties":false,"description":"Explicit transportation billing contact and country. The payer type/account are selected by options.billingType and options.billAccount, not this object. Does not change the duties payer or Shipbuy idempotency. The country must agree with options.billCountry for receiver or third_party.","properties":{"contactName":{"type":"string","minLength":1,"maxLength":70},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"}}}}},"FedexHoldAtLocation":{"type":"object","additionalProperties":false,"required":["locationId","location"],"properties":{"locationId":{"type":"string","minLength":1,"maxLength":20,"description":"FedEx location identifier, represented as a string."},"locationType":{"type":"string","enum":["FEDEX_AUTHORIZED_SHIP_CENTER","FEDEX_OFFICE","FEDEX_SELF_SERVICE_LOCATION","FEDEX_STAFFED","RETAIL_ALLICANCE_LOCATION","FEDEX_GROUND_TERMINAL","FEDEX_ONSITE"]},"location":{"$ref":"#/components/schemas/FedexLocationAddress"}}},"FedexLocationAddress":{"type":"object","additionalProperties":false,"required":["street1","city","country"],"description":"Address returned by FedEx Locations Search. Preserve international characters and the original address. US and Canadian locations require postalCode; do not invent a postal code when FedEx returns none for another country.","allOf":[{"if":{"properties":{"country":{"enum":["US","CA"]}},"required":["country"]},"then":{"required":["postalCode"],"properties":{"postalCode":{"minLength":1}}}}],"properties":{"name":{"type":"string","maxLength":100},"company":{"type":"string","maxLength":100},"street1":{"type":"string","minLength":1,"maxLength":200},"street2":{"type":"string","maxLength":200},"city":{"type":"string","minLength":1,"maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"phone":{"type":"string","maxLength":30},"email":{"type":"string","maxLength":254},"residential":{"type":"boolean"}}},"FedexHomeDeliveryPremium":{"type":"object","additionalProperties":false,"required":["type","localNumber"],"properties":{"type":{"type":"string","enum":["APPOINTMENT","DATE_CERTAIN","EVENING"]},"deliveryDate":{"$ref":"#/components/schemas/CalendarDate"},"areaCode":{"type":"string","pattern":"^[0-9]{1,5}$"},"localNumber":{"type":"string","pattern":"^[0-9]{1,15}$"},"extension":{"type":"string","pattern":"^[0-9]{1,10}$"},"personalIdentificationNumber":{"type":"string","pattern":"^[0-9]{1,20}$"}}},"FedexEmailNotification":{"type":"object","additionalProperties":false,"required":["recipients"],"properties":{"aggregationType":{"type":"string","enum":["PER_PACKAGE","PER_SHIPMENT"]},"personalMessage":{"type":"string","minLength":1,"maxLength":120},"recipients":{"type":"array","minItems":1,"maxItems":6,"items":{"$ref":"#/components/schemas/FedexEmailRecipient"}}}},"FedexEmailRecipient":{"type":"object","additionalProperties":false,"required":["type","emailAddress","events"],"properties":{"name":{"type":"string","minLength":1,"maxLength":70},"type":{"type":"string","enum":["BROKER","OTHER","RECIPIENT","SHIPPER","THIRD_PARTY"]},"emailAddress":{"type":"string","format":"email","minLength":1,"maxLength":254},"format":{"type":"string","enum":["HTML","TEXT"]},"locale":{"type":"string","pattern":"^[a-z]{2}_[A-Z]{2}$"},"events":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","enum":["ON_DELIVERY","ON_EXCEPTION","ON_SHIPMENT","ON_TENDER","ON_ESTIMATED_DELIVERY","ON_PICKUP","ON_PICKUP_DRIVER_ARRIVED","ON_PICKUP_DRIVER_ASSIGNED","ON_PICKUP_DRIVER_DEPARTED","ON_PICKUP_DRIVER_EN_ROUTE"]}}}},"StandaloneShippingPlan":{"type":"object","additionalProperties":false,"properties":{"shipFrom":{"$ref":"#/components/schemas/Address"},"shipTo":{"$ref":"#/components/schemas/Address"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/ParcelInput"},"minItems":1,"maxItems":100},"customs":{"$ref":"#/components/schemas/Customs"},"options":{"$ref":"#/components/schemas/ShippingOptions"},"reference":{"type":"string","minLength":0,"maxLength":100},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"required":["shipFrom","shipTo","packages"],"description":"Pure shipping plan; creates no sales order, fulfillment or inventory movement. warehouseId identifies the validated origin only. Explicit allowStandaloneShipping is required. A warehouse-restricted key must supply an authorized warehouseId and a shipFrom matching that warehouse. Only explicit warehouses.all permits an arbitrary origin. Pure standalone shipping does not additionally require stores.all or allowUnassignedFulfillments."},"StandaloneQuoteSource":{"type":"object","additionalProperties":false,"properties":{"kind":{"const":"standalone","type":"string"},"shipping":{"$ref":"#/components/schemas/StandaloneShippingPlan"}},"required":["kind","shipping"]},"FulfillmentQuoteSource":{"type":"object","additionalProperties":false,"properties":{"kind":{"const":"fulfillment","type":"string"},"fulfillmentId":{"$ref":"#/components/schemas/ResourceId"},"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["kind","fulfillmentId","expectedVersion"]},"OrderQuoteSource":{"type":"object","additionalProperties":false,"properties":{"kind":{"const":"order_fulfillment","type":"string"},"orderId":{"$ref":"#/components/schemas/ResourceId"},"fulfillmentId":{"$ref":"#/components/schemas/ResourceId"},"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["kind","orderId","fulfillmentId","expectedVersion"],"description":"Order is an association check, not an implicit all-order purchase. A specific related fulfillment is mandatory because orders and fulfillments are M:N. expectedVersion is the fulfillment version."},"QuoteSource":{"oneOf":[{"$ref":"#/components/schemas/StandaloneQuoteSource"},{"$ref":"#/components/schemas/FulfillmentQuoteSource"},{"$ref":"#/components/schemas/OrderQuoteSource"}],"discriminator":{"propertyName":"kind","mapping":{"standalone":"#/components/schemas/StandaloneQuoteSource","fulfillment":"#/components/schemas/FulfillmentQuoteSource","order_fulfillment":"#/components/schemas/OrderQuoteSource"}}},"RateQuoteRequest":{"type":"object","additionalProperties":false,"properties":{"source":{"$ref":"#/components/schemas/QuoteSource"},"shippingAccountIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":30,"uniqueItems":true},"serviceCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["source"]},"FulfillmentRateQuoteRequest":{"type":"object","additionalProperties":false,"properties":{"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"},"shippingAccountIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":30,"uniqueItems":true},"serviceCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["expectedVersion"],"description":"Uses the path fulfillmentId and persisted shipping plan. No standalone or order source may be mixed into this request."},"PublicRate":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"shippingAccountId":{"$ref":"#/components/schemas/ResourceId"},"carrier":{"type":"string","minLength":1,"maxLength":64},"serviceCode":{"type":"string","minLength":1,"maxLength":64},"serviceName":{"type":"string","minLength":1,"maxLength":200},"postageAmount":{"$ref":"#/components/schemas/DecimalAmount"},"insuranceAmount":{"$ref":"#/components/schemas/DecimalAmount"},"totalAmount":{"$ref":"#/components/schemas/DecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"estimatedDeliveryDays":{"anyOf":[{"type":"integer","minimum":0,"maximum":365},{"type":"null"}]},"estimatedDeliveryDate":{"anyOf":[{"$ref":"#/components/schemas/CalendarDate"},{"type":"null"}]},"deliveryGuaranteed":{"type":"boolean"},"packageCount":{"type":"integer","minimum":1,"maximum":100},"warnings":{"type":"array","items":{"type":"string","minLength":1,"maxLength":1000},"minItems":0,"maxItems":100}},"required":["id","shippingAccountId","carrier","serviceCode","serviceName","postageAmount","insuranceAmount","totalAmount","currency","packageCount","warnings"],"description":"One customer-priced option for all packages. totalAmount=postageAmount+insuranceAmount. Carrier cost, commission and internal provider identity never appear. Delivery estimates are not guarantees unless stated."},"RateQuote":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"source":{"$ref":"#/components/schemas/QuoteSource"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"expiresAt":{"$ref":"#/components/schemas/UtcTimestamp"},"fingerprint":{"type":"string","minLength":64,"maxLength":64,"pattern":"^[a-f0-9]{64}$"},"rates":{"type":"array","items":{"$ref":"#/components/schemas/PublicRate"},"minItems":0,"maxItems":200},"issues":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"minItems":0,"maxItems":100}},"required":["id","environment","source","createdAt","expiresAt","fingerprint","rates","issues"],"description":"Server-owned quote binds tenant/environment, authorized resource scope, origin/destination, parcel order/shape, customs, options/date, selected account/service, payer/currency and fulfillment version. Maximum quote TTL is 15 minutes and never exceeds upstream quote validity; expiresAt is authoritative. Purchase must recheck credential/integration permissions and resource scope. Pricing changes or stale input require requote; there is no zero-estimate fallback. Zero rates is a valid complete result with issues."},"LabelPurchaseRequest":{"type":"object","additionalProperties":false,"properties":{"quoteId":{"$ref":"#/components/schemas/ResourceId"},"rateId":{"$ref":"#/components/schemas/ResourceId"},"reference":{"type":"string","minLength":0,"maxLength":100}},"required":["quoteId","rateId"],"description":"Buys the selected rate from the server-owned quote. reference is a searchable business reference and never an idempotency key. Neither request prices nor carrier IDs are accepted."},"Document":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"type":{"type":"string","enum":["label","commercial_invoice","carrier_form","manifest"]},"packageId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"mediaType":{"const":"application/pdf","type":"string"},"downloadUrl":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"expiresAt":{"$ref":"#/components/schemas/UtcTimestamp"},"pageCount":{"type":"integer","minimum":1,"maximum":10000}},"required":["id","type","packageId","mediaType","downloadUrl","expiresAt"],"description":"Short-lived signed HTTPS URL. Re-read the owning resource documents endpoint to refresh. PDF labels are preserved; download does not mark printed, ship inventory or trigger a purchase."},"Package":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"packageNo":{"type":"integer","minimum":1,"maximum":100},"trackingNumber":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"trackingUrl":{"anyOf":[{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},{"type":"null"}]},"status":{"type":"string","description":"ready is a persisted package whose label purchase has not fully succeeded; do not present it as labeled or ready to hand off.","enum":["ready","labeled","shipped","in_transit","delivered","exception","returned","voided","canceled"]},"trackingStatus":{"$ref":"#/components/schemas/TrackingStatus"},"postageAmount":{"$ref":"#/components/schemas/DecimalAmount"},"insuranceAmount":{"$ref":"#/components/schemas/DecimalAmount"},"refundAmount":{"$ref":"#/components/schemas/DecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"measurements":{"anyOf":[{"$ref":"#/components/schemas/ParcelInput"},{"type":"null"}]},"documentIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":0,"maxItems":20},"refundStatus":{"description":"pending_review means a confirmed void awaits financial review and does not credit the wallet. refunded is supported only by an actual refund ledger entry, never by elapsed time or a scheduled task.","anyOf":[{"type":"string","enum":["submitted","pending_review","refunded","rejected"]},{"type":"null"}]}},"required":["id","packageNo","trackingNumber","status","trackingStatus","postageAmount","insuranceAmount","refundAmount","currency","measurements","documentIds","refundStatus"]},"Shipment":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"number":{"type":"string","minLength":1,"maxLength":50},"environment":{"$ref":"#/components/schemas/Environment"},"source":{"type":"string","enum":["fulfillment","api","return","dropship"],"description":"Owner discriminator. External shipping and pickup are fulfillment delivery methods, not different shipment owners. The currently reserved transfer owner is not exposed in this version."},"fulfillmentId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"orderIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":0,"maxItems":100,"uniqueItems":true},"warehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","minLength":0,"maxLength":100},{"type":"null"}]},"shippingAccountId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}],"description":"Null for external shipping or pickup. Such shipments require shippingAccounts.all plus all warehouse/store/parent resource grants."},"carrier":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"serviceCode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"status":{"type":"string","enum":["purchased","shipped","in_transit","delivered","exception","voided"]},"billingStatus":{"type":"string","enum":["pending","charged","partially_refunded","refunded","adjusted","disputed","closed"]},"shipFrom":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/AddressSnapshot"}],"description":"Offline/pickup shipment evidence may preserve an incomplete address snapshot."},"shipTo":{"anyOf":[{"$ref":"#/components/schemas/Address"},{"$ref":"#/components/schemas/AddressSnapshot"}],"description":"Offline/pickup shipment evidence may preserve an incomplete address snapshot."},"packages":{"type":"array","items":{"$ref":"#/components/schemas/Package"},"minItems":0,"maxItems":100},"masterTrackingNumber":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"postageAmount":{"$ref":"#/components/schemas/DecimalAmount"},"insuranceAmount":{"$ref":"#/components/schemas/DecimalAmount"},"refundAmount":{"$ref":"#/components/schemas/DecimalAmount"},"adjustmentAmount":{"$ref":"#/components/schemas/SignedDecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"manifestId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["id","number","environment","source","fulfillmentId","orderIds","warehouseId","reference","shippingAccountId","carrier","serviceCode","status","billingStatus","shipFrom","shipTo","packages","masterTrackingNumber","postageAmount","insuranceAmount","refundAmount","adjustmentAmount","currency","manifestId","createdAt","updatedAt","version"],"description":"Immutable purchase/shipping snapshot apart from lifecycle, tracking, billing and manifest association. Original package count/master tracking do not change after partial void. Shipment totals follow the active-package business rules; per-package charges and refunds remain visible. Void/rebuy creates a new shipment. Public id is Shipbuy-owned, never a provider transaction ID. A non-label pickup can have zero packages; external shipments may have no measurement snapshot."},"PurchaseResult":{"type":"object","additionalProperties":false,"properties":{"operationId":{"$ref":"#/components/schemas/ResourceId"},"shipment":{"$ref":"#/components/schemas/Shipment"},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"},"minItems":1,"maxItems":200}},"required":["operationId","shipment","documents"],"description":"Committed, recoverable result. A replay returns the same shipment; signed document URLs may be refreshed without another charge."},"VoidRequest":{"type":"object","additionalProperties":false,"properties":{"packageIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":100,"uniqueItems":true},"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"description":"Omit packageIds to request all active labels. Whole-shipment carriers reject a strict subset with 409; never silently broaden the request. Submitted/accepted is not refunded."},"PackageVoidResult":{"type":"object","additionalProperties":false,"properties":{"packageId":{"$ref":"#/components/schemas/ResourceId"},"status":{"type":"string","enum":["submitted","voided","rejected","needs_review"]},"refundStatus":{"description":"pending_review means a confirmed void awaits financial review and does not credit the wallet. refunded is supported only by an actual refund ledger entry, never by elapsed time or a scheduled task.","anyOf":[{"type":"string","enum":["submitted","pending_review","refunded","rejected"]},{"type":"null"}]},"refundAmount":{"$ref":"#/components/schemas/DecimalAmount"},"message":{"type":"string","minLength":1,"maxLength":1000}},"required":["packageId","status","refundStatus","refundAmount","message"]},"VoidResult":{"type":"object","additionalProperties":false,"properties":{"operationId":{"$ref":"#/components/schemas/ResourceId"},"shipmentId":{"$ref":"#/components/schemas/ResourceId"},"results":{"type":"array","items":{"$ref":"#/components/schemas/PackageVoidResult"},"minItems":1,"maxItems":100},"currency":{"$ref":"#/components/schemas/Currency"}},"required":["operationId","shipmentId","results","currency"]},"TrackingStatus":{"type":"string","enum":["created","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","unknown"]},"TrackingEvent":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"occurredAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"status":{"$ref":"#/components/schemas/TrackingStatus"},"description":{"type":"string","minLength":1,"maxLength":1000},"city":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"state":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"country":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]}},"required":["id","occurredAt","status","description"],"description":"Normalized carrier event. Unknown source times remain null; ingestion time must not be represented as carrier event time."},"TrackingSnapshot":{"type":"object","additionalProperties":false,"properties":{"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"carrier":{"type":"string","minLength":1,"maxLength":64},"status":{"$ref":"#/components/schemas/TrackingStatus"},"description":{"type":"string","minLength":0,"maxLength":1000},"lastCheckedAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"nextCheckAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"deliveredAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"},"minItems":0,"maxItems":1000},"eventsTruncated":{"type":"boolean"},"monitoringStatus":{"type":"string","enum":["active","completed","expired","unsupported","needs_review"]}},"required":["trackingNumber","carrier","status","description","lastCheckedAt","nextCheckAt","deliveredAt","events","eventsTruncated","monitoringStatus"],"description":"Reads cached tracking, never starts a billable upstream lookup per GET. Event storage and normalized history are target capabilities, not a claim about the current poller. Events newest first; no fabricated carrier events."},"TrackerCreate":{"type":"object","additionalProperties":false,"properties":{"carrier":{"type":"string","minLength":1,"maxLength":64},"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"shipDate":{"$ref":"#/components/schemas/CalendarDate"},"reference":{"type":"string","minLength":0,"maxLength":100},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"required":["carrier","trackingNumber","shipDate"],"description":"Registers an externally purchased shipment for monitoring; creates no shipping purchase, fulfillment or stock movement. Successful unique registration is metered once per agreed monitoring cycle; duplicate registration/retry within that cycle, reads, polls and webhook retries do not create another registration charge. Deduplication includes account, environment, carrier, tracking number and shipping period because numbers can be reused. Cycle length, price and quota policy remain undecided; new live registration returns 403/service_not_enabled before provider/fee activity. Test simulation remains available."},"Tracker":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"carrier":{"type":"string","minLength":1,"maxLength":64},"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"shipDate":{"$ref":"#/components/schemas/CalendarDate"},"reference":{"anyOf":[{"type":"string","minLength":0,"maxLength":100},{"type":"null"}]},"metadata":{"$ref":"#/components/schemas/ClientMetadata"},"tracking":{"$ref":"#/components/schemas/TrackingSnapshot"},"monitoringEndsAt":{"$ref":"#/components/schemas/UtcTimestamp","description":"End of this explicitly established monitoring cycle. No universal duration is implied; duration and renewal policy must be agreed before enabling new live registrations. Test values describe simulated cycles only."},"billable":{"type":"boolean","description":"Indicates that this registration is eligible as one billable unique registration in its cycle, not that every subsequent read incurs a charge. Test is false. Duplicate registration within the existing cycle adds no new metered unit."},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","environment","carrier","trackingNumber","shipDate","reference","metadata","tracking","monitoringEndsAt","billable","createdAt","updatedAt"]},"ShippingServiceCapability":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"carrier":{"type":"string","minLength":1,"maxLength":64},"supportsRates":{"type":"boolean"},"supportsLabels":{"type":"boolean"},"supportsTracking":{"type":"boolean"},"supportsManifest":{"type":"boolean"},"supportsMultiPiece":{"type":"boolean"},"voidScope":{"type":"string","enum":["package","shipment","unsupported"]},"packageShapes":{"type":"array","items":{"type":"string","enum":["box","envelope","irregular"]},"minItems":1,"maxItems":3,"uniqueItems":true},"packageTypeCodes":{"type":"array","items":{"type":"string","minLength":1,"maxLength":64},"minItems":0,"maxItems":100,"uniqueItems":true},"originCountries":{"type":"array","items":{"$ref":"#/components/schemas/CountryCode"},"minItems":1,"maxItems":250,"uniqueItems":true}},"required":["code","name","carrier","supportsRates","supportsLabels","supportsTracking","supportsManifest","supportsMultiPiece","voidScope","packageShapes","packageTypeCodes","originCountries"]},"ShippingAccount":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","unavailable"]},"ownership":{"type":"string","enum":["shipbuy","customer"]},"services":{"type":"array","items":{"$ref":"#/components/schemas/ShippingServiceCapability"},"minItems":0,"maxItems":200},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","name","status","ownership","services","updatedAt"],"description":"Customer-facing brand and permitted capabilities only. No credentials, internal_type, aggregator keys, cost or commission. Capabilities are necessary but not sufficient: request-specific restrictions still apply."},"ManifestCandidate":{"type":"object","additionalProperties":false,"properties":{"shipmentId":{"$ref":"#/components/schemas/ResourceId"},"shippingAccountId":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"carrier":{"type":"string","minLength":1,"maxLength":64},"facilityKey":{"type":"string","minLength":1,"maxLength":200},"shipDate":{"$ref":"#/components/schemas/CalendarDate"},"trackingNumbers":{"type":"array","items":{"type":"string","minLength":1,"maxLength":120},"minItems":1,"maxItems":100},"eligible":{"type":"boolean"},"issues":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"},"minItems":0,"maxItems":100}},"required":["shipmentId","shippingAccountId","warehouseId","carrier","facilityKey","shipDate","trackingNumbers","eligible","issues"],"description":"Read-only preflight; eligibility is rechecked on creation. facilityKey is opaque, not a client-defined grouping authority."},"ManifestCreate":{"type":"object","additionalProperties":false,"properties":{"shipmentIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":500,"uniqueItems":true},"shipDate":{"$ref":"#/components/schemas/CalendarDate"}},"required":["shipmentIds","shipDate"],"description":"One carrier account, facility, carrier and compatible label date per request. Mixed groups are rejected explicitly; client can preflight/group using candidates. Occupied, ineligible, duplicate-tracking shipments reject atomically before any upstream creation."},"Manifest":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"number":{"type":"string","minLength":1,"maxLength":50},"environment":{"$ref":"#/components/schemas/Environment"},"shippingAccountId":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"carrier":{"type":"string","minLength":1,"maxLength":64},"shipDate":{"$ref":"#/components/schemas/CalendarDate"},"shipmentIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":500,"uniqueItems":true},"status":{"type":"string","enum":["creating","created","failed","voided"]},"recoveryStatus":{"anyOf":[{"type":"string","enum":["rejected","result_unknown","document_failed","partial_result"]},{"type":"null"}]},"confirmationNumber":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"canVoidLocally":{"type":"boolean"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","number","environment","shippingAccountId","warehouseId","carrier","shipDate","shipmentIds","status","recoveryStatus","confirmationNumber","canVoidLocally","createdAt","updatedAt"],"description":"Member set is frozen. Unknown/partial upstream result retains member reservation and must be reconciled; never automatically resubmit. Manifest does not establish carrier acceptance, inventory shipment or a pickup booking."},"ManifestVoidRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"description":"Local membership release only. Does not cancel or modify the carrier document. Unknown/partial/document-failed outcomes cannot be released without reconciliation."},"ResourceLink":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["shipment","manifest","fulfillment","order","inventory_adjustment","inventory_reservation"]},"id":{"$ref":"#/components/schemas/ResourceId"},"url":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"}},"required":["type","id","url"]},"Operation":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"type":{"type":"string","enum":["label_purchase","label_void","manifest_create","manifest_void","fulfillment_ship"]},"status":{"type":"string","enum":["pending","running","succeeded","failed","needs_review"]},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"retryAfterSeconds":{"type":"integer","minimum":1,"maximum":300},"result":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/PurchaseResult"},{"$ref":"#/components/schemas/VoidResult"},{"$ref":"#/components/schemas/Manifest"},{"$ref":"#/components/schemas/Fulfillment"}]},{"type":"null"}]},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ResourceLink"},"minItems":0,"maxItems":501},"error":{"anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}},"required":["id","environment","type","status","createdAt","updatedAt","result","resources","error"],"description":"Durable, tenant/environment-scoped operation. needs_review means an external effect may have occurred; polling/replaying is safe but a new key could create a duplicate charge. A succeeded purchase includes persisted result and retrievable documents. Internal attempts, lease/worker states and upstream handles are not exposed."},"OrderItemInput":{"type":"object","additionalProperties":false,"properties":{"clientLineId":{"type":"string","minLength":1,"maxLength":100},"productId":{"$ref":"#/components/schemas/ResourceId"},"sku":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"unitPrice":{"$ref":"#/components/schemas/DecimalAmount"}},"required":["clientLineId","quantity","unitPrice"],"anyOf":[{"required":["productId"]},{"required":["sku","name"]}],"description":"productId is authoritative when provided; a conflicting SKU fails. Unmatched SKU lines follow the existing account matching policy and can block fulfillment readiness."},"OrderItem":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"clientLineId":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"productId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"name":{"anyOf":[{"type":"string","minLength":0,"maxLength":500},{"type":"null"}]},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"canceledQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"fulfilledQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"unitPrice":{"anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,4})?$"},{"type":"null"}]}},"required":["id","clientLineId","productId","sku","name","quantity","canceledQuantity","fulfilledQuantity","unitPrice"]},"OrderCreate":{"type":"object","additionalProperties":false,"properties":{"externalId":{"type":"string","minLength":1,"maxLength":100},"orderNumber":{"type":"string","minLength":1,"maxLength":50},"reference":{"type":"string","minLength":0,"maxLength":100},"currency":{"$ref":"#/components/schemas/Currency"},"shipTo":{"$ref":"#/components/schemas/Address"},"shipFrom":{"$ref":"#/components/schemas/Address"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"deliveryMethod":{"type":"string","enum":["label","external","pickup"],"default":"label"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemInput"},"minItems":1,"maxItems":1000},"shippingAmount":{"$ref":"#/components/schemas/DecimalAmount"},"taxAmount":{"$ref":"#/components/schemas/DecimalAmount"},"discountAmount":{"$ref":"#/components/schemas/DecimalAmount"},"note":{"type":"string","minLength":0,"maxLength":200},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"required":["externalId","currency","shipTo","items"],"description":"externalId is unique per tenant+environment+integration identity and is stable across key rotation within that integration. Reusing externalId with conflicting content returns 409; orderNumber/reference are display/search values, not deduplication keys. Creation uses the existing order ingest/fulfillment pipeline and normal inventory reservations. Public API identity, tenant and source are server-owned."},"OrderPatch":{"type":"object","additionalProperties":false,"properties":{"reference":{"anyOf":[{"type":"string","minLength":0,"maxLength":100},{"type":"null"}]},"shipTo":{"$ref":"#/components/schemas/Address","description":"Edits only the order sales-source address snapshot. Does not automatically change fulfillment shipping addresses or already purchased shipment history; edit an eligible fulfillment explicitly with its own version."},"note":{"type":"string","minLength":0,"maxLength":200},"items":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ExistingOrderItemEdit"},{"$ref":"#/components/schemas/NewOrderItemEdit"}]},"minItems":1,"maxItems":1000},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"minProperties":1,"description":"Only currently editable business fields. Items replace the requested sales-line set, never silently remove shipped or allocated quantities. Existing label, warehouse work, channel ownership and fulfillment guards may reject with 409. Status, fulfillment totals and inventory are not writable here. shipTo changes only the order source snapshot, not fulfillment transport addresses. Editing items uses explicit orderItemId for every existing row; new rows are explicitly marked new. The whole requested sales-line list replaces the old list: an omitted old line requests its deletion, which is allowed only under existing execution/fulfillment guards. No SKU/productId-based implicit row matching."},"Order":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"externalId":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"orderNumber":{"type":"string","minLength":1,"maxLength":50},"reference":{"anyOf":[{"type":"string","minLength":0,"maxLength":100},{"type":"null"}]},"environment":{"$ref":"#/components/schemas/Environment"},"status":{"type":"string","enum":["open","closed","canceled"]},"paymentStatus":{"type":"string","enum":["unpaid","partially_paid","paid","partially_refunded","refunded"]},"fulfillmentStatus":{"type":"string","enum":["unfulfilled","partial","fulfilled"]},"deliveryMethod":{"type":"string","enum":["label","external","pickup"]},"shipTo":{"$ref":"#/components/schemas/AddressSnapshot"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"},"minItems":0,"maxItems":1000},"currency":{"$ref":"#/components/schemas/Currency"},"shippingAmount":{"$ref":"#/components/schemas/DecimalAmount"},"taxAmount":{"$ref":"#/components/schemas/DecimalAmount"},"discountAmount":{"$ref":"#/components/schemas/DecimalAmount"},"totalAmount":{"$ref":"#/components/schemas/DecimalAmount"},"isOnHold":{"type":"boolean"},"holdReason":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"holdUntil":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"fulfillmentIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":0,"maxItems":1000,"uniqueItems":true},"metadata":{"$ref":"#/components/schemas/ClientMetadata"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"},"note":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Customer note; internal staff notes are not exposed."}},"required":["id","externalId","orderNumber","reference","environment","status","paymentStatus","fulfillmentStatus","deliveryMethod","shipTo","items","currency","shippingAmount","taxAmount","discountAmount","totalAmount","isOnHold","holdReason","holdUntil","fulfillmentIds","metadata","createdAt","updatedAt","version","note"],"description":"Orders represent sales demand; fulfillmentIds are M:N associations. Fulfillment totals/status are server-derived. No hard delete is offered; cancellation is a guarded audited business action."},"ReasonRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]},"HoldRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":255},"holdUntil":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]}},"required":["reason"],"description":"Hold is orthogonal to status and only allowed for open orders. Null/omitted expiry means manual release. Order hold cascades to associated nonterminal fulfillments under existing shared-order rules."},"OrderCancelRequest":{"type":"object","additionalProperties":false,"properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"description":"Uses existing guarded cancellation. Any active label must first be explicitly voided through the label-void API; cancellation does not void labels automatically. Shared fulfillments, warehouse/procurement work and terminal states can block cancellation with 409. No hard delete, silent stock adjustment or upstream sales-channel cancellation."},"FulfillmentItem":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"orderItemId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"productId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"sku":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"name":{"anyOf":[{"type":"string","minLength":0,"maxLength":500},{"type":"null"}]},"parentItemId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"status":{"type":"string","enum":["active","exploded","substituted"]},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"pickedQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"packedQuantity":{"type":"integer","minimum":0,"maximum":2147483647}},"required":["id","orderItemId","productId","sku","name","parentItemId","status","quantity","pickedQuantity","packedQuantity"],"description":"Top-level rows preserve sales demand; only active physical rows participate in inventory, pick/pack and customs. A bundle demand row can be exploded into active component rows."},"Fulfillment":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"number":{"type":"string","minLength":1,"maxLength":50},"environment":{"$ref":"#/components/schemas/Environment"},"orderIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":0,"maxItems":1000,"uniqueItems":true},"type":{"type":"string","enum":["warehouse","backorder","dropship"]},"deliveryMethod":{"type":"string","enum":["label","external","pickup"]},"status":{"type":"string","enum":["pending","label_purchased","shipped","canceled","voided"]},"warehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"shipFrom":{"$ref":"#/components/schemas/AddressSnapshot"},"shipTo":{"$ref":"#/components/schemas/AddressSnapshot"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"},"minItems":0,"maxItems":1000},"packages":{"type":"array","items":{"$ref":"#/components/schemas/PlannedParcel"},"minItems":0,"maxItems":100},"options":{"$ref":"#/components/schemas/ShippingOptionsSnapshot"},"customs":{"anyOf":[{"$ref":"#/components/schemas/CustomsSnapshot"},{"type":"null"}]},"isOnHold":{"type":"boolean"},"holdReason":{"anyOf":[{"type":"string","minLength":1,"maxLength":255},{"type":"null"}]},"holdUntil":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"ready":{"type":"boolean"},"readinessIssues":{"type":"array","items":{"$ref":"#/components/schemas/ReadinessIssue"},"minItems":0,"maxItems":100},"shipmentIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":0,"maxItems":1000,"uniqueItems":true},"currentShipmentId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"plannedShipDate":{"anyOf":[{"$ref":"#/components/schemas/CalendarDate"},{"type":"null"}]},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["id","number","environment","orderIds","type","deliveryMethod","status","warehouseId","shipFrom","shipTo","items","packages","options","customs","isOnHold","holdReason","holdUntil","ready","readinessIssues","shipmentIds","currentShipmentId","plannedShipDate","createdAt","updatedAt","version"],"description":"Fulfillment is the quote/buy/ship unit. Multiple orders can share one fulfillment and one order can have many fulfillments. Label purchase and physical shipment are distinct; delivery tracking is on packages/shipments, not this status."},"FulfillmentPatch":{"type":"object","additionalProperties":false,"properties":{"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"shipFrom":{"$ref":"#/components/schemas/Address"},"shipTo":{"$ref":"#/components/schemas/Address"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/ParcelInput"},"minItems":1,"maxItems":100},"options":{"$ref":"#/components/schemas/ShippingOptions"},"customs":{"anyOf":[{"$ref":"#/components/schemas/Customs"},{"type":"null"}]},"plannedShipDate":{"anyOf":[{"$ref":"#/components/schemas/CalendarDate"},{"type":"null"}]},"deliveryMethod":{"type":"string","enum":["label","external","pickup"]}},"minProperties":1,"description":"Does not write items, status, reservations or shipment snapshots directly. Shipping edits invalidate affected quotes. Warehouse/delivery changes use current label, pick/pack, hold and inventory guards; prohibited transitions return 409."},"ExternalParcel":{"type":"object","additionalProperties":false,"properties":{"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"carrier":{"type":"string","minLength":1,"maxLength":32},"packageNo":{"type":"integer","minimum":1,"maximum":100}},"required":["packageNo","carrier","trackingNumber"],"description":"Evidence for one existing planned package. Supply every packageNo exactly once; all packages use the same carrier because the shipment owns carrier identity. This ships the whole fulfillment. Split first for a partial shipment."},"ShipRequest":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"mode":{"const":"label","type":"string"},"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["mode","expectedVersion"]},{"type":"object","additionalProperties":false,"properties":{"mode":{"const":"external","type":"string"},"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"},"packages":{"type":"array","items":{"$ref":"#/components/schemas/ExternalParcel"},"minItems":1,"maxItems":100}},"required":["mode","expectedVersion","packages"]},{"type":"object","additionalProperties":false,"properties":{"mode":{"const":"pickup","type":"string"},"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"},"note":{"type":"string","minLength":1,"maxLength":500},"recipientName":{"type":"string","minLength":1,"maxLength":100}},"required":["mode","expectedVersion","recipientName"]}],"description":"mode must equal the saved deliveryMethod. Confirms the entire currently shippable fulfillment through the existing shared ship transition, including inventory eligibility and reservation release. It never buys a label. Label mode requires active labels; external registers external shipment evidence; pickup may have no tracking. Dropship uses supplier-shipment workflow and is rejected here. For partial shipment, split first; no hidden quantity truncation."},"SplitRequest":{"type":"object","additionalProperties":false,"properties":{"expectedVersion":{"$ref":"#/components/schemas/ResourceVersion"},"items":{"type":"array","items":{"type":"object","additionalProperties":false,"properties":{"fulfillmentItemId":{"$ref":"#/components/schemas/ResourceId"},"moveQuantity":{"type":"integer","minimum":1,"maximum":1000000}},"required":["fulfillmentItemId","moveQuantity"]},"minItems":1,"maxItems":1000}},"required":["expectedVersion","items"],"description":"Move quantities to one new fulfillment; original must retain at least one unit. Existing split guards apply: no labels/packed work, no merged or exploded/composite line split, move quantity cannot include picked/packed quantities. Source order links are preserved."},"SplitResult":{"type":"object","additionalProperties":false,"properties":{"original":{"$ref":"#/components/schemas/Fulfillment"},"created":{"$ref":"#/components/schemas/Fulfillment"}},"required":["original","created"]},"ProductType":{"type":"string","enum":["single","parent","variant","bundle","assembly","virtual"]},"VariantAxis":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"values":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["name","values"]},"VariantSelection":{"type":"object","minProperties":1,"maxProperties":3,"propertyNames":{"type":"string","minLength":1,"maxLength":120},"additionalProperties":{"type":"string","minLength":1,"maxLength":60},"description":"Selected axis/value pairs. Axis names and values must belong to the parent options; the normalized combination is unique within the parent."},"ProductComponent":{"type":"object","additionalProperties":false,"properties":{"productId":{"$ref":"#/components/schemas/ResourceId"},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"type":{"type":"string","enum":["required","optional"],"default":"required"},"sortOrder":{"type":"integer","minimum":0,"maximum":1000},"notes":{"type":"string","minLength":0,"maxLength":255}},"required":["productId","quantity"],"description":"Only single, variant or assembly components. No self-reference/cycles; assembly BOM depth <=5. Parent, bundle and virtual cannot be components."},"ProductCustoms":{"type":"object","additionalProperties":false,"properties":{"noCustoms":{"type":"boolean"},"description":{"type":"string","minLength":0,"maxLength":200},"value":{"$ref":"#/components/schemas/DecimalAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"originCountry":{"$ref":"#/components/schemas/CountryCode"},"hsCode":{"type":"string","minLength":0,"maxLength":64}},"required":["noCustoms"]},"ProductCreate":{"type":"object","additionalProperties":false,"properties":{"type":{"$ref":"#/components/schemas/ProductType"},"sku":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","inactive"],"default":"active"},"description":{"type":"string","minLength":0,"maxLength":500},"barcode":{"type":"string","minLength":1,"maxLength":64},"upc":{"type":"string","minLength":1,"maxLength":64},"ean":{"type":"string","minLength":1,"maxLength":64},"gtin":{"type":"string","minLength":1,"maxLength":64},"brand":{"type":"string","minLength":0,"maxLength":120},"manufacturer":{"type":"string","minLength":0,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"salePrice":{"$ref":"#/components/schemas/DecimalAmount"},"trackInventory":{"type":"boolean"},"parentId":{"$ref":"#/components/schemas/ResourceId"},"variantOptions":{"type":"array","items":{"$ref":"#/components/schemas/VariantAxis"},"minItems":1,"maxItems":3},"variantSelection":{"$ref":"#/components/schemas/VariantSelection"},"components":{"type":"array","items":{"$ref":"#/components/schemas/ProductComponent"},"minItems":0,"maxItems":100},"shippingDefaults":{"$ref":"#/components/schemas/ProductShippingDefaults"},"customs":{"$ref":"#/components/schemas/ProductCustoms"},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"required":["type","name"],"allOf":[{"if":{"properties":{"type":{"const":"variant"}},"required":["type"]},"then":{"required":["parentId","variantSelection","sku"]},"else":{"not":{"anyOf":[{"required":["parentId"]},{"required":["variantSelection"]}]}}},{"if":{"properties":{"type":{"const":"parent"}},"required":["type"]},"then":{"required":["variantOptions"]},"else":{"not":{"required":["variantOptions"]}}},{"if":{"properties":{"type":{"enum":["bundle","assembly"]}},"required":["type"]},"then":{"required":["components"]},"else":{"not":{"required":["components"]}}},{"if":{"properties":{"type":{"enum":["parent","bundle","virtual"]}},"required":["type"]},"then":{"properties":{"trackInventory":{"const":false}}}},{"if":{"properties":{"type":{"enum":["parent","virtual"]}},"required":["type"]},"then":{"not":{"anyOf":[{"required":["barcode"]},{"required":["shippingDefaults"]}]}}}],"description":"Type is immutable. Single/variant/assembly may carry inventory; bundle is a sales shell expanded to components; parent is a non-sellable group; virtual is nonphysical. Variants use this same endpoint and own product ID. Parent changes do not overwrite children."},"ProductPatch":{"type":"object","additionalProperties":false,"properties":{"sku":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","inactive"],"default":"active"},"description":{"type":"string","minLength":0,"maxLength":500},"barcode":{"type":"string","minLength":1,"maxLength":64},"upc":{"type":"string","minLength":1,"maxLength":64},"ean":{"type":"string","minLength":1,"maxLength":64},"gtin":{"type":"string","minLength":1,"maxLength":64},"brand":{"type":"string","minLength":0,"maxLength":120},"manufacturer":{"type":"string","minLength":0,"maxLength":120},"currency":{"$ref":"#/components/schemas/Currency"},"salePrice":{"$ref":"#/components/schemas/DecimalAmount"},"trackInventory":{"type":"boolean"},"parentId":{"$ref":"#/components/schemas/ResourceId"},"variantOptions":{"type":"array","items":{"$ref":"#/components/schemas/VariantAxis"},"minItems":1,"maxItems":3},"variantSelection":{"$ref":"#/components/schemas/VariantSelection"},"components":{"type":"array","items":{"$ref":"#/components/schemas/ProductComponent"},"minItems":0,"maxItems":100},"shippingDefaults":{"$ref":"#/components/schemas/ProductShippingDefaults"},"customs":{"$ref":"#/components/schemas/ProductCustoms"},"metadata":{"$ref":"#/components/schemas/ClientMetadata"}},"minProperties":1,"description":"Type cannot be changed; parentId cannot reparent a saved variant. Server validates fields against the saved product type. components is a whole-list replacement (empty clears); omit to preserve. Existing barcode cannot be replaced here. Setting status=inactive archives availability without deleting referenced records; no hard-delete endpoint."},"Product":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"type":{"$ref":"#/components/schemas/ProductType"},"sku":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"name":{"type":"string","minLength":1,"maxLength":200},"status":{"type":"string","enum":["active","inactive"]},"description":{"type":"string","minLength":0,"maxLength":500},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"parentId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"variantOptions":{"type":"array","items":{"$ref":"#/components/schemas/VariantAxis"},"minItems":0,"maxItems":3},"variantSelection":{"anyOf":[{"$ref":"#/components/schemas/VariantSelection"},{"type":"null"}]},"components":{"type":"array","items":{"$ref":"#/components/schemas/ProductComponent"},"minItems":0,"maxItems":100},"trackInventory":{"type":"boolean"},"sellable":{"type":"boolean"},"purchasable":{"type":"boolean"},"shippable":{"type":"boolean"},"currency":{"$ref":"#/components/schemas/Currency"},"salePrice":{"$ref":"#/components/schemas/DecimalAmount"},"shippingDefaults":{"anyOf":[{"$ref":"#/components/schemas/ProductShippingDefaults"},{"type":"null"}]},"customs":{"anyOf":[{"$ref":"#/components/schemas/ProductCustoms"},{"type":"null"}]},"metadata":{"$ref":"#/components/schemas/ClientMetadata"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"},"upc":{"anyOf":[{"type":"string","minLength":0,"maxLength":64},{"type":"null"}]},"ean":{"anyOf":[{"type":"string","minLength":0,"maxLength":64},{"type":"null"}]},"gtin":{"anyOf":[{"type":"string","minLength":0,"maxLength":64},{"type":"null"}]},"brand":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]},"manufacturer":{"anyOf":[{"type":"string","minLength":0,"maxLength":120},{"type":"null"}]}},"required":["id","environment","type","sku","name","status","description","barcode","parentId","variantOptions","variantSelection","components","trackInventory","sellable","purchasable","shippable","currency","salePrice","shippingDefaults","customs","metadata","createdAt","updatedAt","version","upc","ean","gtin","brand","manufacturer"],"description":"All six types share this resource. Inventory is keyed to actual single/variant/assembly product IDs. Bundle availability may be derived from required components but is not physical bundle on-hand stock. Provider purchasing cost and account secrets are never included."},"Warehouse":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"name":{"anyOf":[{"type":"string","minLength":0,"maxLength":200},{"type":"null"}]},"timeZone":{"type":"string","minLength":1,"maxLength":100,"description":"IANA time-zone name."},"inventoryMode":{"type":"string","enum":["none","warehouse","location"]},"availableIncludesReceiving":{"type":"boolean"},"shipFrom":{"$ref":"#/components/schemas/AddressSnapshot"},"outboundWarehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","name","timeZone","inventoryMode","availableIncludesReceiving","shipFrom","outboundWarehouseId","updatedAt"],"description":"A shipping-address record may point to a different physical outbound warehouse. Use saved fulfillment warehouseId for stock; never infer it from address text. The full outbound warehouse link must be visible to the key; otherwise the address row is excluded before pagination. Draft ship-from addresses may be incomplete."},"Location":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"code":{"anyOf":[{"type":"string","minLength":0,"maxLength":100},{"type":"null"}]},"name":{"anyOf":[{"type":"string","minLength":0,"maxLength":200},{"type":"null"}]},"type":{"type":"string","enum":["storage","receiving","returns","hold"]},"pickable":{"type":"boolean"},"systemManaged":{"type":"boolean"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","warehouseId","code","name","type","pickable","systemManaged","updatedAt"]},"Stock":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"productId":{"$ref":"#/components/schemas/ResourceId"},"onHandQuantity":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"reservedQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"availableQuantity":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"awaitingPutawayQuantity":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"onOrderQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"inTransitQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"incomingQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"availableIncludesReceiving":{"type":"boolean"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp","description":"Timestamp of the persisted balance row; derived supply/pick changes may not advance it."},"version":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["id","warehouseId","productId","onHandQuantity","reservedQuantity","availableQuantity","awaitingPutawayQuantity","onOrderQuantity","inTransitQuantity","incomingQuantity","availableIncludesReceiving","updatedAt","version"],"description":"onHand=storage+hold+returns; awaitingPutaway=receiving physical stock; available=storage+(receiving if enabled)-reserved (may be negative); reserved=active fulfillment+manual remaining holds. incoming=onOrder+inTransit, excludes awaitingPutaway and does not increase available. Never simplify available to onHand-reserved. Existing rows only, no synthesized physical bundle/parent/virtual stock. Existing configured shipping-shortfall behavior can leave negative physical balances; reads report them faithfully and never clamp to zero. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering."},"LocationStock":{"type":"object","additionalProperties":false,"properties":{"locationId":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"productId":{"$ref":"#/components/schemas/ResourceId"},"onHandQuantity":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"pickAllocatedQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"movableQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp","description":"Timestamp of the persisted balance row; derived supply/pick changes may not advance it."}},"required":["locationId","warehouseId","productId","onHandQuantity","pickAllocatedQuantity","movableQuantity","updatedAt"],"description":"No location-level reservation. movable=max(0,onHand-pickAllocated) for normal move planning; other outbound workflows apply their extra in-progress guards. Picking does not yet decrement physical onHand. Incremental updatedAfter follows persisted balance-row changes. Derived supply or pick allocations are evaluated at read time and may change without advancing that row timestamp; periodically perform a full read for these derived quantities. Opaque version values support equality checks, not numeric ordering."},"InventoryTransaction":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"locationId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"productId":{"$ref":"#/components/schemas/ResourceId"},"movementType":{"type":"string","minLength":1,"maxLength":64},"quantityChange":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"quantityAfter":{"anyOf":[{"type":"integer","minimum":-2147483648,"maximum":2147483647},{"type":"null"}]},"reasonCode":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"sourceType":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"null"}]},"sourceId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"sourceNumber":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"lotNumber":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"reversalOfTransactionId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"occurredAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","warehouseId","locationId","productId","movementType","quantityChange","quantityAfter","reasonCode","sourceType","sourceId","sourceNumber","lotNumber","reversalOfTransactionId","occurredAt"],"description":"Append-only business ledger; read-only. Clients cannot create transactions or overwrite balances directly. movementType/reasonCode are documented extensible codes, not internal job state."},"DeltaAdjustmentLine":{"type":"object","additionalProperties":false,"properties":{"productId":{"$ref":"#/components/schemas/ResourceId"},"locationId":{"$ref":"#/components/schemas/ResourceId"},"mode":{"const":"delta","type":"string"},"quantityDelta":{"type":"integer","minimum":-2147483648,"maximum":2147483647},"expectedOnHand":{"type":"integer","minimum":-2147483648,"maximum":2147483647,"description":"Observed balance, including a legitimate existing negative shortfall; compared under lock. This is not a requested quantity."}},"required":["productId","mode","quantityDelta","expectedOnHand"],"allOf":[{"properties":{"quantityDelta":{"not":{"const":0}}}}]},"SetAdjustmentLine":{"type":"object","additionalProperties":false,"properties":{"productId":{"$ref":"#/components/schemas/ResourceId"},"locationId":{"$ref":"#/components/schemas/ResourceId"},"mode":{"const":"set","type":"string"},"quantity":{"type":"integer","minimum":0,"maximum":2147483647},"expectedOnHand":{"type":"integer","minimum":-2147483648,"maximum":2147483647,"description":"Observed balance, including a legitimate existing negative shortfall; compared under lock. This is not a requested quantity."}},"required":["productId","mode","quantity","expectedOnHand"]},"InventoryAdjustmentCreate":{"type":"object","additionalProperties":false,"properties":{"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"reasonCode":{"type":"string","enum":["correction","damage","loss"]},"reason":{"type":"string","minLength":1,"maxLength":255},"lines":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/DeltaAdjustmentLine"},{"$ref":"#/components/schemas/SetAdjustmentLine"}]},"minItems":1,"maxItems":100}},"required":["warehouseId","reasonCode","reason","lines"],"description":"Atomic batch through the shared adjustment service; any invalid/stale line rejects the entire batch. expectedOnHand is the location physical quantity checked under stock lock. location mode requires locationId on every line; warehouse mode resolves its system STOCK location; none mode rejects. No negative physical stock; product type/tracking, pick allocation, tenant, warehouse and mode guards apply. Not a substitute for receiving, transfer, return or assembly workflows. correction can increase/decrease; damage/loss only decrease. The reason text is retained as the audited correction note."},"InventoryAdjustment":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"transactionIds":{"type":"array","items":{"$ref":"#/components/schemas/ResourceId"},"minItems":1,"maxItems":100},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","warehouseId","transactionIds","createdAt"]},"ReservationCreate":{"type":"object","additionalProperties":false,"properties":{"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"productId":{"$ref":"#/components/schemas/ResourceId"},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"reason":{"type":"string","minLength":1,"maxLength":255},"expiresAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["warehouseId","productId","quantity","reason"],"description":"Manual warehouse-level hold only; <= current available checked atomically. Optional expiresAt must be in the future (UTC); expiry is eventual via scheduler. Does not change physical stock, become a fulfillment reservation or identify damaged stock."},"Reservation":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"warehouseId":{"$ref":"#/components/schemas/ResourceId"},"productId":{"$ref":"#/components/schemas/ResourceId"},"source":{"const":"manual","type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":2147483647},"releasedQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"remainingQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"reason":{"type":"string","minLength":1,"maxLength":255},"expiresAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["id","warehouseId","productId","source","quantity","releasedQuantity","remainingQuantity","reason","expiresAt","createdAt","updatedAt"],"description":"Active manual hold. Remaining=quantity-releasedQuantity. Fully released/expired rows are removed by the current model; replay receipts survive row removal."},"ReservationRelease":{"type":"object","additionalProperties":false,"properties":{"quantity":{"type":"integer","minimum":1,"maximum":1000000},"reason":{"type":"string","minLength":1,"maxLength":255}},"required":["reason"],"description":"Omitted quantity releases all remaining units. Only manual reservations owned by the current scope; fulfillment reservations are managed by their business lifecycle."},"ReservationReleaseResult":{"type":"object","additionalProperties":false,"properties":{"reservationId":{"$ref":"#/components/schemas/ResourceId"},"releasedQuantity":{"type":"integer","minimum":1,"maximum":2147483647},"remainingQuantity":{"type":"integer","minimum":0,"maximum":2147483647},"releasedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["reservationId","releasedQuantity","remainingQuantity","releasedAt"]},"WebhookEventType":{"type":"string","enum":["shipment.purchased","shipment.voided","shipment.refund_updated","tracking.updated","manifest.updated","order.created","order.updated","order.canceled","fulfillment.updated","fulfillment.shipped","product.created","product.updated","inventory.changed","operation.completed","operation.needs_review"]},"EventData":{"type":"object","additionalProperties":false,"properties":{"resourceType":{"type":"string","enum":["shipment","package","tracker","manifest","order","fulfillment","product","inventory_stock","operation"]},"resourceId":{"$ref":"#/components/schemas/ResourceId"},"resourceVersion":{"anyOf":[{"$ref":"#/components/schemas/ResourceVersion"},{"type":"null"}]},"resourceUrl":{"type":"string","minLength":1,"maxLength":4096,"format":"uri"},"operationId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"warehouseId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"productId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]}},"required":["resourceType","resourceId","resourceVersion","resourceUrl"],"description":"Reference event; retrieve current resource with the separately required read scope. References are scoped to the tenant/environment. resourceVersion is opaque: compare equality, never numeric order. On duplicate or out-of-order events retrieve the current resource before applying a change."},"Event":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"type":{"$ref":"#/components/schemas/WebhookEventType"},"environment":{"$ref":"#/components/schemas/Environment"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"data":{"$ref":"#/components/schemas/EventData"}},"required":["id","type","environment","createdAt","data"]},"WebhookEndpointCreate":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"format":"uri","pattern":"^https://"},"description":{"type":"string","minLength":0,"maxLength":255},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"minItems":1,"maxItems":15,"uniqueItems":true}},"required":["url","events"],"description":"HTTPS public endpoint only; validation must block private/local/reserved destinations, DNS rebinding and redirects to prohibited addresses. A test credential creates only test endpoints. Event subscriptions also require the corresponding resource read scope. The authorizing credential and creation-time scope/resource snapshot are bound internally; delivery follows x-webhook-contract.authorization. Revocation or expiry stops the subscription unless an administrator explicitly migrates it during an eligible key rotation."},"WebhookEndpointPatch":{"type":"object","additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048,"format":"uri","pattern":"^https://"},"description":{"type":"string","minLength":0,"maxLength":255},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"minItems":1,"maxItems":15,"uniqueItems":true},"enabled":{"type":"boolean"}},"minProperties":1,"description":"Same destination and scope validation as create. Changing destination does not expose or recycle the signing secret."},"WebhookEndpoint":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"environment":{"$ref":"#/components/schemas/Environment"},"url":{"type":"string","minLength":1,"maxLength":2048,"format":"uri"},"description":{"type":"string","minLength":0,"maxLength":255},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"},"minItems":1,"maxItems":15,"uniqueItems":true},"enabled":{"type":"boolean"},"createdAt":{"$ref":"#/components/schemas/UtcTimestamp"},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"}},"required":["id","environment","url","description","events","enabled","createdAt","updatedAt","version"],"description":"Owned by the current account, environment and stable integration. Delivery authority remains bound to the authorizing API key and creation-time constraint snapshot; no other key automatically takes over. See x-webhook-contract.authorization. These internal authorization fields are not public payload fields."},"WebhookEndpointCreated":{"type":"object","additionalProperties":false,"properties":{"endpoint":{"$ref":"#/components/schemas/WebhookEndpoint"},"signingSecret":{"anyOf":[{"type":"string","minLength":1,"maxLength":200,"description":"Returned only in the initial successful creation response. Generated with >=256 bits of randomness. Server signing storage is encrypted, but management APIs do not retrieve it; no plaintext secret is stored in ordinary idempotency receipts or logs."},{"type":"null"}]},"secretUnavailable":{"type":"boolean","description":"false on the initial response; true on replay, with signingSecret=null. Recover a lost secret through management-side rotation, not another endpoint creation. Public secret rotation is outside this version."}},"required":["endpoint","signingSecret","secretUnavailable"],"allOf":[{"if":{"properties":{"secretUnavailable":{"const":true}},"required":["secretUnavailable"]},"then":{"properties":{"signingSecret":{"type":"null"}}},"else":{"properties":{"signingSecret":{"type":"string","minLength":1,"maxLength":200}}}}],"description":"One-time secret delivery is an explicit exception to byte-identical replay: replay returns the same endpoint, signingSecret=null and secretUnavailable=true. It never creates another endpoint or returns an earlier signing secret."},"WebhookDelivery":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"eventId":{"$ref":"#/components/schemas/ResourceId"},"endpointId":{"$ref":"#/components/schemas/ResourceId"},"status":{"type":"string","enum":["pending","succeeded","failed"]},"attemptCount":{"type":"integer","minimum":0,"maximum":1000},"lastAttemptAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"nextAttemptAt":{"anyOf":[{"$ref":"#/components/schemas/UtcTimestamp"},{"type":"null"}]},"lastHttpStatus":{"anyOf":[{"type":"integer","minimum":100,"maximum":599},{"type":"null"}]}},"required":["id","eventId","endpointId","status","attemptCount","lastAttemptAt","nextAttemptAt","lastHttpStatus"]},"UsageMeter":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string","enum":["api_requests","label_purchases","external_trackers","address_verifications"]},"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991},"unit":{"type":"string","enum":["request","shipment","tracker","verification"]},"billableQuantity":{"type":"integer","minimum":0,"maximum":9007199254740991},"includedQuantity":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Confirmed included allowance when available; null means no allowance is reported. Do not interpret null as unlimited or infer a free trial."},"amount":{"anyOf":[{"$ref":"#/components/schemas/DecimalAmount"},{"type":"null"}],"description":"Aggregate amount for the requested interval, when known. Not a per-request unit price or permission to bill; null means no finalized/available amount is reported. No micro-unit pricing or rounding policy is specified by this field."},"currency":{"$ref":"#/components/schemas/Currency"}},"required":["name","quantity","unit","billableQuantity","includedQuantity","amount","currency"]},"Usage":{"type":"object","additionalProperties":false,"properties":{"environment":{"$ref":"#/components/schemas/Environment"},"periodStart":{"$ref":"#/components/schemas/UtcTimestamp"},"periodEnd":{"$ref":"#/components/schemas/UtcTimestamp"},"meters":{"type":"array","items":{"$ref":"#/components/schemas/UsageMeter"},"minItems":0,"maxItems":20},"updatedAt":{"$ref":"#/components/schemas/UtcTimestamp"}},"required":["environment","periodStart","periodEnd","meters","updatedAt"],"description":"Informational metering, not an invoice. Approved but unimplemented billing target is daily settlement with unsettled accrued fees reducing spendable wallet funds. Test usage is never debited from live funds. External tracker/address prices and included quotas remain undecided; new live actions stay disabled until confirmed. Existing usage remains readable. updatedAt is the report freshness timestamp, not a promise of a completed settlement or per-meter finalization watermark. Request counts cover authenticated V2 requests recorded by this deployment. Label purchases count unique persisted purchase shipments, including later voids. billableQuantity is zero until separate API billing is implemented; it does not remove existing postage charges. Amount/allowance null never means free or unlimited."},"ShippingAccountListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingAccount"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"RateQuoteResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/RateQuote"}},"required":["code","message","requestId","data"]},"PurchaseResultResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/PurchaseResult"}},"required":["code","message","requestId","data"]},"OperationResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Operation"}},"required":["code","message","requestId","data"]},"ShipmentListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"ShipmentResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Shipment"}},"required":["code","message","requestId","data"]},"DocumentListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"VoidResultResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/VoidResult"}},"required":["code","message","requestId","data"]},"TrackingSnapshotResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/TrackingSnapshot"}},"required":["code","message","requestId","data"]},"TrackerResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Tracker"}},"required":["code","message","requestId","data"]},"TrackerListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Tracker"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"ManifestCandidateListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ManifestCandidate"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"ManifestResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Manifest"}},"required":["code","message","requestId","data"]},"ManifestListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Manifest"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"AddressVerificationResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/AddressVerification"}},"required":["code","message","requestId","data"]},"OrderResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Order"}},"required":["code","message","requestId","data"]},"OrderListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"FulfillmentListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"FulfillmentResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Fulfillment"}},"required":["code","message","requestId","data"]},"SplitResultResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/SplitResult"}},"required":["code","message","requestId","data"]},"ProductResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Product"}},"required":["code","message","requestId","data"]},"ProductListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"WarehouseListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Warehouse"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"LocationListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"StockListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Stock"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"LocationStockListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/LocationStock"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"InventoryTransactionListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryTransaction"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"InventoryAdjustmentResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/InventoryAdjustment"}},"required":["code","message","requestId","data"]},"ReservationResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Reservation"}},"required":["code","message","requestId","data"]},"ReservationListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Reservation"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"ReservationReleaseResultResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/ReservationReleaseResult"}},"required":["code","message","requestId","data"]},"WebhookEndpointCreatedResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/WebhookEndpointCreated"}},"required":["code","message","requestId","data"]},"WebhookEndpointListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"WebhookEndpointResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/WebhookEndpoint"}},"required":["code","message","requestId","data"]},"EventListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"EventResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Event"}},"required":["code","message","requestId","data"]},"WebhookDeliveryListResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"},"minItems":0,"maxItems":100},"nextCursor":{"anyOf":[{"type":"string","minLength":1,"maxLength":2048},{"type":"null"}]},"hasMore":{"type":"boolean"},"snapshotAt":{"$ref":"#/components/schemas/UtcTimestamp"},"tombstones":{"type":"array","items":{"$ref":"#/components/schemas/SyncTombstone"},"minItems":0,"maxItems":100}},"required":["code","message","requestId","data","nextCursor","hasMore","snapshotAt","tombstones"],"description":"Cursor page; nextCursor is null iff hasMore=false. Stable ordering within the cursor. No unbounded all=true parameter. snapshotAt fixes the scan high-watermark; later changes appear in the next incremental scan. tombstones supports deletion/archive/filter exits; empty when not applicable. Both data and tombstones must be consumed before saving nextCursor."},"WebhookDeliveryResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/WebhookDelivery"}},"required":["code","message","requestId","data"]},"UsageResponse":{"type":"object","additionalProperties":false,"properties":{"code":{"const":"ok","type":"string"},"message":{"type":"string","minLength":0,"maxLength":255},"requestId":{"$ref":"#/components/schemas/ResourceId"},"data":{"$ref":"#/components/schemas/Usage"}},"required":["code","message","requestId","data"]},"ProductShippingDefaults":{"type":"object","additionalProperties":false,"properties":{"length":{"$ref":"#/components/schemas/DecimalMeasurement"},"width":{"$ref":"#/components/schemas/DecimalMeasurement"},"height":{"$ref":"#/components/schemas/DecimalMeasurement"},"weight":{"$ref":"#/components/schemas/DecimalMeasurement"},"dimensionUnit":{"type":"string","enum":["in","cm"]},"weightUnit":{"type":"string","enum":["lb","oz","kg","g"]},"packageTypeId":{"$ref":"#/components/schemas/ResourceId"},"carrierPackageType":{"type":"string","minLength":1,"maxLength":64},"insuredValue":{"$ref":"#/components/schemas/DecimalAmount"}},"minProperties":1,"description":"Optional product shipping defaults, not an actual package or inventory quantity. Partial defaults can be stored; incomplete dimensions/weight do not create a valid shipping plan automatically."},"NewOrderItemEdit":{"type":"object","additionalProperties":false,"properties":{"clientLineId":{"type":"string","minLength":1,"maxLength":100},"productId":{"$ref":"#/components/schemas/ResourceId"},"sku":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"unitPrice":{"$ref":"#/components/schemas/DecimalAmount"},"kind":{"type":"string","const":"new"}},"required":["clientLineId","quantity","unitPrice","kind"],"anyOf":[{"required":["productId"]},{"required":["sku","name"]}],"description":"productId is authoritative when provided; a conflicting SKU fails. Unmatched SKU lines follow the existing account matching policy and can block fulfillment readiness."},"ExistingOrderItemEdit":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","const":"existing"},"orderItemId":{"$ref":"#/components/schemas/ResourceId"},"productId":{"$ref":"#/components/schemas/ResourceId"},"sku":{"type":"string","minLength":1,"maxLength":64},"name":{"type":"string","minLength":1,"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":1000000},"unitPrice":{"$ref":"#/components/schemas/DecimalAmount"}},"required":["kind","orderItemId","quantity","unitPrice"],"description":"Identifies one existing line by stable orderItemId; it must belong to the path order. Omitted optional fields preserve that line field. Product rematching and reductions remain subject to current business guards. Duplicate orderItemId entries reject."},"SyncTombstone":{"type":"object","additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/ResourceId"},"removedAt":{"$ref":"#/components/schemas/UtcTimestamp"},"version":{"$ref":"#/components/schemas/ResourceVersion"},"reason":{"type":"string","enum":["deleted","archived","filter_exit"]}},"required":["id","removedAt","version","reason"],"description":"Incremental synchronization removal marker within retention, only for a previously visible resource. Does not reveal resources outside current tenant/environment authorization."},"AddressSnapshot":{"type":"object","additionalProperties":false,"properties":{"name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"company":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"street1":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"street2":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"state":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"postalCode":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"country":{"anyOf":[{"type":"string","maxLength":2},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"email":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}]},"residential":{"anyOf":[{"anyOf":[{"type":"boolean"},{"type":"null"}]},{"type":"null"}]}},"required":["name","company","street1","street2","city","state","postalCode","country","phone","email","residential"],"description":"Read-only address snapshot. Fields may be empty or null while an order is not ready; this is not a valid purchase input."},"PlannedParcel":{"type":"object","additionalProperties":false,"properties":{"packageNo":{"type":"integer","minimum":1,"maximum":100},"length":{"anyOf":[{"$ref":"#/components/schemas/DecimalMeasurement"},{"type":"null"}]},"width":{"anyOf":[{"$ref":"#/components/schemas/DecimalMeasurement"},{"type":"null"}]},"height":{"anyOf":[{"$ref":"#/components/schemas/DecimalMeasurement"},{"type":"null"}]},"weight":{"anyOf":[{"$ref":"#/components/schemas/DecimalMeasurement"},{"type":"null"}]},"dimensionUnit":{"anyOf":[{"type":"string","enum":["in","cm"]},{"type":"null"}]},"weightUnit":{"anyOf":[{"type":"string","enum":["lb","oz","kg","g"]},{"type":"null"}]},"shape":{"anyOf":[{"type":"string","enum":["box","envelope","irregular"],"default":"box"},{"type":"null"}]},"packageTypeId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"carrierPackageType":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"insuredValue":{"anyOf":[{"$ref":"#/components/schemas/DecimalAmount"},{"type":"null"}]}},"required":["packageNo","length","width","height","weight","dimensionUnit","weightUnit","shape","packageTypeId","carrierPackageType","insuredValue"],"description":"Saved parcel plan, including incomplete or zero-valued drafts. Quoting/purchasing still require valid positive measurements."},"ShippingOptionsSnapshot":{"type":"object","additionalProperties":false,"properties":{"shipDate":{"anyOf":[{"$ref":"#/components/schemas/CalendarDate"},{"type":"null"}]},"billingType":{"type":"string","enum":["sender","receiver","third_party"],"description":"Saved transportation payer. Defaults to sender for a legacy plan without a payer type; independent of customs.dutiesBillingType."},"billAccount":{"anyOf":[{"type":"string","maxLength":30},{"type":"null"}],"description":"Saved transportation payer account; null for sender. Historical incomplete external payer plans may also return null and must be corrected before quoting or buying."},"billCountry":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}],"description":"Saved transportation billing country; null for sender or an incomplete historical plan."},"billZip":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"Saved transportation billing postal code; null for sender or an incomplete historical plan."},"signature":{"anyOf":[{"type":"string","enum":["none","signature","adult_signature","delivery"]},{"type":"null"}]},"saturdayDelivery":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"labelReference1":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"labelReference2":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"fedex":{"anyOf":[{"$ref":"#/components/schemas/FedexOptions"},{"type":"null"}]}},"description":"Saved portable shipping options and typed FedEx Direct options. fedex is null when no FedEx options are set; absent optional fields inside that object are omitted. Transportation billing and customs duties billing are independent. A snapshot may preserve an incomplete historical external payer plan; it is not proof that the plan is ready for a quote or purchase.","required":["shipDate","billingType","billAccount","billCountry","billZip","signature","saturdayDelivery","labelReference1","labelReference2","fedex"]},"CustomsItemSnapshot":{"type":"object","additionalProperties":false,"properties":{"description":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"quantity":{"anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"unitValue":{"anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]{0,11})(\\.[0-9]{1,4})?$"},{"type":"null"}]},"currency":{"anyOf":[{"$ref":"#/components/schemas/Currency"},{"type":"null"}]},"hsCode":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}]},"originCountry":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"productId":{"anyOf":[{"$ref":"#/components/schemas/ResourceId"},{"type":"null"}]},"unitWeight":{"anyOf":[{"$ref":"#/components/schemas/DecimalAmount"},{"type":"null"}],"description":"Weight of one commodity unit, before multiplying by quantity."},"weightUnit":{"anyOf":[{"type":"string","enum":["lb","oz","kg","g"]},{"type":"null"}]},"commercialUnitPrice":{"anyOf":[{"$ref":"#/components/schemas/DecimalAmount"},{"type":"null"}]},"quantityUnits":{"anyOf":[{"type":"string","enum":["PCS","PC","EA"]},{"type":"null"}]},"numberOfPieces":{"anyOf":[{"type":"integer","minimum":0,"maximum":9999},{"type":"null"}]}},"required":["description","quantity","unitValue","currency","hsCode","originCountry","productId","unitWeight","weightUnit","commercialUnitPrice","quantityUnits","numberOfPieces"]},"CustomsSnapshot":{"type":"object","additionalProperties":false,"properties":{"contentsType":{"anyOf":[{"type":"string","enum":["merchandise","gift","documents","sample","returned_goods"]},{"type":"null"}]},"nonDeliveryOption":{"anyOf":[{"type":"string","enum":["return","abandon"]},{"type":"null"}]},"signer":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomsItemSnapshot"},"minItems":0,"maxItems":100},"dutiesBillingType":{"anyOf":[{"type":"string","enum":["sender","receiver","third_party"]},{"type":"null"}]},"dutiesBillAccount":{"anyOf":[{"type":"string","pattern":"^[0-9]{9}$"},{"type":"null"}]},"dutiesBillCountry":{"anyOf":[{"$ref":"#/components/schemas/CountryCode"},{"type":"null"}]},"dutiesBillZip":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"details":{"anyOf":[{"$ref":"#/components/schemas/CustomsDetails"},{"type":"null"}]}},"required":["contentsType","nonDeliveryOption","signer","items","dutiesBillingType","dutiesBillAccount","dutiesBillCountry","dutiesBillZip","details"],"description":"Required for shipments crossing a customs boundary; values are declared customer values, not shipping costs."},"ReadinessIssue":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string","minLength":1,"maxLength":100},"field":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"message":{"type":"string","maxLength":1000}},"required":["code","field","message"],"description":"A read-only reason why the current fulfillment is not ready; field may be absent for a whole-resource rule."}}}}