{
  "openapi": "3.0.3",
  "info": {
    "title": "ShipCove Operations API",
    "version": "1.0.0",
    "description": "Owner-only, server-side API over saved ShipCove records. The only write is a text reply to an existing open support conversation. No UPS, financial, reward approval, account editing, or scheduling actions. Browser Origin requests are rejected. Store the sc_ops_ bearer secret in a secure vault; never include it in URLs, prompts, or chat.",
    "termsOfService": "https://shipcove.net/terms"
  },
  "servers": [{"url":"https://shipcove.net/api/ops/v1"}],
  "security": [{"OperationsKey":[]}],
  "tags": [{"name":"Connection"},{"name":"Records"},{"name":"Monitoring"},{"name":"Support"}],
  "paths": {
    "/me": {"get":{"tags":["Connection"],"operationId":"getOperationsConnection","summary":"Verify the key and available capabilities","description":"Reports key metadata, scopes, expiry, and that schedules must be created by an external agent. Accepts no query parameters.","x-required-scope":"any valid operations key","responses":{"200":{"description":"Connection metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connection"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/customers": {"get":{"tags":["Records"],"operationId":"listOperationsCustomers","summary":"List saved customer summaries","x-required-scope":"customers:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/RecordsCursor"}],"responses":{"200":{"description":"Customer page","content":{"application/json":{"schema":{"type":"object","required":["customers","nextCursor"],"properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/customers/{id}": {"get":{"tags":["Records"],"operationId":"getOperationsCustomer","summary":"Read one saved customer summary","x-required-scope":"customers:read","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"customer":{"$ref":"#/components/schemas/Customer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/shipments": {"get":{"tags":["Records"],"operationId":"listOperationsShipments","summary":"List saved shipment snapshots","description":"Tracking fields are saved snapshots, not live carrier requests or guaranteed delivery evidence.","x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/RecordsCursor"}],"responses":{"200":{"description":"Shipment page","content":{"application/json":{"schema":{"type":"object","required":["shipments","nextCursor"],"properties":{"shipments":{"type":"array","items":{"$ref":"#/components/schemas/Shipment"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/shipments/{id}": {"get":{"tags":["Records"],"operationId":"getOperationsShipment","summary":"Read one saved shipment snapshot","x-required-scope":"shipments:read","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Shipment","content":{"application/json":{"schema":{"type":"object","required":["shipment"],"properties":{"shipment":{"$ref":"#/components/schemas/Shipment"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/payments": {"get":{"tags":["Records"],"operationId":"listOperationsPayments","summary":"List saved wallet and PayPal payment summaries","description":"Wallet deposits are funding movements, not label revenue. No payment write is available.","x-required-scope":"payments:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/RecordsCursor"}],"responses":{"200":{"description":"Payment page","content":{"application/json":{"schema":{"type":"object","required":["payments","nextCursor"],"properties":{"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/report": {"get":{"tags":["Records"],"operationId":"getOperationsReport","summary":"Read a bounded sales and cost summary","description":"Defaults to the past 24 hours. The to timestamp is exclusive. Maximum span is 31 days. Sales use the active customer live label cohort; owner, test, voided and refunded labels are excluded. Gross profit is an incomplete estimate when costs or fees are unknown; wallet deposits are separate funding.","x-required-scope":"reports:read","parameters":[{"name":"from","in":"query","description":"Inclusive start in Unix milliseconds; defaults to 24 hours before to.","schema":{"type":"integer","format":"int64","minimum":0}},{"name":"to","in":"query","description":"Exclusive end in Unix milliseconds; defaults to current time.","schema":{"type":"integer","format":"int64","minimum":0}}],"responses":{"200":{"description":"Report for the selected range","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Report"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/alerts": {"get":{"tags":["Monitoring"],"operationId":"getOperationsAlerts","summary":"Read counts of saved exceptions","description":"Stored ShipCove exception counts and up to 50 item references, plus sampled server error evidence; not live UPS or complete infrastructure logs. The caller supplies scheduling and notifications. Accepts no query parameters.","x-required-scope":"monitoring:read","responses":{"200":{"description":"Saved exception summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alerts"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/rewards": {"get":{"tags":["Records"],"operationId":"listOperationsRewards","summary":"Read pending reward review records","description":"Eligibility is a saved, read-only policy projection. Owner approval is still required.","x-required-scope":"rewards:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/RecordsCursor"}],"responses":{"200":{"description":"Reward page and current policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rewards"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/support": {"get":{"tags":["Support"],"operationId":"listOperationsSupport","summary":"List saved support conversations","x-required-scope":"support:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","schema":{"type":"string","enum":["open","resolved","declined"]}},{"$ref":"#/components/parameters/SupportCursor"}],"responses":{"200":{"description":"Ticket page","content":{"application/json":{"schema":{"type":"object","required":["tickets","nextCursor"],"properties":{"tickets":{"type":"array","items":{"$ref":"#/components/schemas/Ticket"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},
    "/support/{id}/messages": {
      "get":{"tags":["Support"],"operationId":"getOperationsSupportMessages","summary":"Read a support conversation","description":"Returns up to 100 messages in ascending creation order. Pass nextCursor as cursor to continue. The ticket updatedAt is the compare-and-set token for a reply.","x-required-scope":"support:read","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/MessagesCursor"}],"responses":{"200":{"description":"Conversation page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},
      "post":{"tags":["Support"],"operationId":"postOperationsSupportMessage","summary":"Send an AI-identified text reply to an open ticket","description":"Requires both support:read and support:reply. Does not resolve the ticket, send notifications, change money or account state. A matching replay of the same UUID and body returns the saved reply; a changed reuse conflicts. On a stale ticket version, reread and reassess before any new reply.","x-required-scopes":["support:read","support:reply"],"parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReplyInput"}}}},"responses":{"200":{"description":"Reply saved or idempotently replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportReplyResult"}}}},"400":{"$ref":"#/components/responses/InvalidRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}
    }
  },
  "components": {
    "securitySchemes":{"OperationsKey":{"type":"http","scheme":"bearer","bearerFormat":"sc_ops_ key"}},
    "parameters":{
      "Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},
      "Limit":{"name":"limit","in":"query","description":"Page size; default 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},
      "RecordsCursor":{"name":"cursor","in":"query","description":"Opaque nextCursor from the preceding records page; currently timestamp:id. Do not construct it.","schema":{"type":"string"}},
      "SupportCursor":{"name":"cursor","in":"query","description":"Opaque nextCursor from the preceding support page; currently updatedAt|id. Do not construct it.","schema":{"type":"string"}},
      "MessagesCursor":{"name":"cursor","in":"query","description":"Opaque nextCursor from the preceding conversation page; currently createdAt|message-id. Do not construct it.","schema":{"type":"string"}}
    },
    "responses":{
      "InvalidRequest":{"description":"Invalid field, range, or parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Unauthorized":{"description":"Missing, expired, or revoked key.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Forbidden":{"description":"Access or scope denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "NotFound":{"description":"Resource not found or unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "Conflict":{"description":"Stale support version, closed/full conversation, or reused reply ID with different details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},
      "RateLimited":{"description":"Request rate limited. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}
    },
    "schemas":{
      "NullableCursor":{"type":"string","nullable":true},
      "Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}},
      "Connection":{"type":"object","required":["service","version","principal","capabilities","monitoring"],"properties":{"service":{"type":"string","example":"ShipCove Operations API"},"version":{"type":"string","example":"1"},"principal":{"type":"object","required":["keyId","name","scopes","expiresAt"],"properties":{"keyId":{"type":"string","format":"uuid"},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["customers:read","shipments:read","payments:read","reports:read","monitoring:read","support:read","support:reply","rewards:read"]}},"expiresAt":{"type":"integer","format":"int64"}}},"capabilities":{"type":"object","required":["financialWrites","customerAccountWrites","carrierRequests","supportReplies"],"properties":{"financialWrites":{"type":"boolean","enum":[false]},"customerAccountWrites":{"type":"boolean","enum":[false]},"carrierRequests":{"type":"boolean","enum":[false]},"supportReplies":{"type":"boolean"}}},"monitoring":{"type":"object","required":["source","scheduledBy","shipcoveSchedulesCreated"],"properties":{"source":{"type":"string","enum":["saved_shipcove_records"]},"scheduledBy":{"type":"string","enum":["external_agent"]},"shipcoveSchedulesCreated":{"type":"boolean","enum":[false]}}}}},
      "Customer":{"type":"object","required":["id","name","status","balanceCents","archivedAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","description":"Archived accounts are reported as archived."},"balanceCents":{"type":"integer","description":"Saved available credit in cents."},"archivedAt":{"type":"integer","format":"int64","nullable":true},"createdAt":{"type":"integer","format":"int64"}}},
      "Shipment":{"type":"object","required":["id","customerId","customerName","accountType","service","amountCents","currency","mode","status","billingState","voidState","tracking","trackingStage","lastTrackingCheckAt","refundDueAt","refundCompletedAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"customerName":{"type":"string","nullable":true},"service":{"type":"string"},"amountCents":{"type":"integer","nullable":true},"currency":{"type":"string"},"mode":{"type":"string","description":"Saved shipping mode; test records are not live postage."},"status":{"type":"string"},"billingState":{"type":"string","description":"Saved billing state. The value none is expected for owner/test flows and is not by itself evidence of an unpaid customer purchase."},"voidState":{"type":"string","description":"Saved carrier void state. A confirmed void does not by itself establish a customer refund obligation; inspect accountType, mode, refund fields, and payment records. Preserve genuine pending customer refund alerts."},"tracking":{"type":"string","nullable":true},"trackingStage":{"type":"string","nullable":true},"lastTrackingCheckAt":{"type":"integer","format":"int64","nullable":true},"refundDueAt":{"type":"integer","format":"int64","nullable":true},"refundCompletedAt":{"type":"integer","format":"int64","nullable":true},"createdAt":{"type":"integer","format":"int64"},"accountType":{"type":"string","enum":["owner","customer"],"description":"Whether the saved shipment belongs to the site owner or a customer. Exclude owner and test-mode shipments from customer billing incident alerts."}}},
      "Payment":{"type":"object","required":["id","customerId","kind","amountCents","shipmentId","status","dueAt","createdAt"],"properties":{"id":{"type":"string"},"customerId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["wallet_deposit","wallet_refund","paypal_capture","paypal_refund","checkout_status","refund_pending"],"description":"checkout_status is informational and does not prove capture."},"amountCents":{"type":"integer","nullable":true},"shipmentId":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string"},"dueAt":{"type":"integer","format":"int64","nullable":true},"createdAt":{"type":"integer","format":"int64"}}},
      "Report":{"type":"object","required":["from","to","currency","sales","walletDepositsCents","walletRefundsCents","paypalRefundsCents","newCustomers","promotionCreditCents"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"},"currency":{"type":"string","enum":["USD"]},"sales":{"type":"object","required":["basis","labelCount","labelRevenueCents","carrierKnownCostCents","knownPaymentFeesCents","recordedCustomerAdjustmentsCents","recordedCarrierAdjustmentsCents","estimatedGrossProfitCents","incomplete","unknownCarrierCostLabels","unknownPaymentFeeCaptures","note"],"properties":{"basis":{"type":"string","enum":["active_customer_label_cohort"],"description":"Customer live labels created in this range; excludes owner, test, voided and refunded labels."},"labelCount":{"type":"integer"},"labelRevenueCents":{"type":"integer"},"carrierKnownCostCents":{"type":"integer"},"knownPaymentFeesCents":{"type":"integer"},"recordedCustomerAdjustmentsCents":{"type":"integer"},"recordedCarrierAdjustmentsCents":{"type":"integer"},"estimatedGrossProfitCents":{"type":"integer","description":"Incomplete cohort estimate, not settled net profit."},"incomplete":{"type":"boolean","enum":[true]},"unknownCarrierCostLabels":{"type":"integer"},"unknownPaymentFeeCaptures":{"type":"integer"},"note":{"type":"string"}}},"walletDepositsCents":{"type":"integer","description":"Funding, not label revenue."},"walletRefundsCents":{"type":"integer"},"paypalRefundsCents":{"type":"integer"},"newCustomers":{"type":"integer"},"promotionCreditCents":{"type":"integer"}}},
      "Alerts":{"type":"object","required":["asOf","source","counts","items","itemsTruncated","runtimeErrors"],"properties":{"asOf":{"type":"integer","format":"int64"},"source":{"type":"string","enum":["stored_records"]},"counts":{"type":"object","required":["uncertainShipments","stuckShipments","pendingVoids","uncertainPayments","pendingRefunds","trackingExceptions","browserSecurityReports","failedNotifications","runtimeErrors"],"properties":{"uncertainShipments":{"type":"integer"},"stuckShipments":{"type":"integer"},"pendingVoids":{"type":"integer"},"uncertainPayments":{"type":"integer"},"pendingRefunds":{"type":"integer"},"trackingExceptions":{"type":"integer"},"browserSecurityReports":{"type":"integer"},"failedNotifications":{"type":"integer"},"runtimeErrors":{"type":"integer","description":"Sampled application 5xx errors in the last 24 hours; not full infrastructure logs."}}},"items":{"type":"array","maxItems":50,"items":{"type":"object","required":["kind","resourceType","resourceId","customerId","status","createdAt"],"properties":{"kind":{"type":"string"},"resourceType":{"type":"string"},"resourceId":{"type":"string"},"customerId":{"type":"string","nullable":true},"status":{"type":"string"},"createdAt":{"type":"integer","format":"int64"}}}},"itemsTruncated":{"type":"boolean"},"runtimeErrors":{"type":"object","required":["source","windowHours","sampledCount","recent"],"properties":{"source":{"type":"string","enum":["sampled_app_audit"]},"windowHours":{"type":"integer","enum":[24]},"sampledCount":{"type":"integer"},"recent":{"type":"array","items":{"type":"object","required":["routeCategory","status","method","createdAt"],"properties":{"routeCategory":{"type":"string"},"status":{"type":"integer"},"method":{"type":"string"},"createdAt":{"type":"integer","format":"int64"}}}}}}}},
      "Reward":{"type":"object","required":["id","kind","customerId","referrerCustomerId","amountCents","status","eligible","eligibilitySource","createdAt"],"properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["welcome","referral"]},"customerId":{"type":"string","format":"uuid"},"referrerCustomerId":{"type":"string","format":"uuid","nullable":true},"amountCents":{"type":"integer"},"status":{"type":"string"},"eligible":{"type":"boolean"},"eligibilitySource":{"type":"string","enum":["current_policy_sql"]},"createdAt":{"type":"integer","format":"int64"}}},
      "Rewards":{"type":"object","required":["rewards","nextCursor","policy"],"properties":{"rewards":{"type":"array","items":{"$ref":"#/components/schemas/Reward"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"},"policy":{"type":"object","required":["welcomeCents","referralCents","depositCents","holdDays","approvalRequired"],"properties":{"welcomeCents":{"type":"integer"},"referralCents":{"type":"integer"},"depositCents":{"type":"integer"},"holdDays":{"type":"integer"},"approvalRequired":{"type":"boolean","enum":[true]}}}}},
      "Ticket":{"type":"object","required":["id","customerId","customerName","status","updatedAt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"customerId":{"type":"string"},"customerName":{"type":"string"},"status":{"type":"string","enum":["open","resolved","declined"]},"updatedAt":{"type":"integer","format":"int64"},"createdAt":{"type":"integer","format":"int64"}}},
      "Message":{"type":"object","required":["id","role","authorLabel","message","createdAt"],"properties":{"id":{"type":"string"},"role":{"type":"string"},"authorLabel":{"type":"string"},"message":{"type":"string"},"createdAt":{"type":"integer","format":"int64"}}},
      "Conversation":{"type":"object","required":["ticketId","status","updatedAt","messages","nextCursor"],"properties":{"ticketId":{"type":"string","format":"uuid"},"status":{"type":"string"},"updatedAt":{"type":"integer","format":"int64"},"messages":{"type":"array","maxItems":100,"items":{"$ref":"#/components/schemas/Message"}},"nextCursor":{"$ref":"#/components/schemas/NullableCursor"}}},
      "SupportReplyInput":{"type":"object","additionalProperties":false,"required":["id","message","expectedUpdatedAt"],"properties":{"id":{"type":"string","format":"uuid","description":"New idempotency UUID. Preserve this ID and exact body on uncertain retry."},"message":{"type":"string","minLength":1,"maxLength":1900},"expectedUpdatedAt":{"type":"integer","format":"int64","minimum":0,"description":"Latest ticket updatedAt from GET /support/{id}/messages."}}},
      "SupportReplyResult":{"type":"object","required":["saved","id","message","updatedAt"],"properties":{"saved":{"type":"boolean","enum":[true]},"id":{"type":"string","format":"uuid"},"message":{"$ref":"#/components/schemas/Message"},"updatedAt":{"type":"integer","format":"int64"}}}
    }
  }
}