{"openapi":"3.1.0","info":{"title":"TrackShip Tracking API","description":"The TrackShip Tracking API lets you create, retrieve, and delete shipment trackers and list supported shipping providers. All authenticated requests must send the `trackship-api-key` and `app-name` headers. See the human documentation at https:\/\/docs.trackship.com\/docs\/tracking-api\/ .\n\n## Versioning & deprecation\n\nThis API is versioned in the URL path (for example `\/v1`). Backwards-incompatible changes are released under a new version; the previous version stays available during the transition.\n\nWhen an API version or endpoint is deprecated, TrackShip signals it with the standard `Deprecation` and `Sunset` HTTP response headers (RFC 8594) on the affected responses and announces it in the API documentation at https:\/\/docs.trackship.com at least 6 months before the removal date.","version":"1.0.0","contact":{"name":"TrackShip Support","url":"https:\/\/docs.trackship.com\/docs\/tracking-api\/"},"license":{"name":"Proprietary"},"x-deprecation-policy":{"versioning":"url-path","signals":["Deprecation","Sunset"],"specification":"RFC 8594","minimumNoticePeriod":"P6M","documentation":"https:\/\/docs.trackship.com"}},"servers":[{"url":"https:\/\/api.trackship.com\/v1","description":"TrackShip production API"}],"externalDocs":{"description":"TrackShip Tracking API documentation","url":"https:\/\/docs.trackship.com\/docs\/tracking-api\/"},"tags":[{"name":"Shipments","description":"Create, retrieve, and delete shipment trackers."},{"name":"Shipping providers","description":"Reference data for supported carriers."}],"security":[{"TrackShipApiKey":[],"AppName":[]}],"paths":{"\/shipment\/create\/":{"post":{"operationId":"createShipment","summary":"Create a tracking","description":"Create a shipment tracker. Returns the account's remaining tracker balance and plan.","tags":["Shipments"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateShipmentRequest"},"example":{"tracking_number":"1Z4937W56728755212","tracking_provider":"ups","order_id":"13","postal_code":"98012","destination_country":"US"}}}},"responses":{"200":{"description":"Tracker created (or a status message explaining why it could not be).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateShipmentResponse"},"example":{"status":"ok","status_msg":"pending_trackship","trackers_balance":"98","user_plan":"Mini"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/InvalidRoute"},"500":{"$ref":"#\/components\/responses\/ServerError"}}}},"\/shipment\/get\/":{"post":{"operationId":"getShipmentStatus","summary":"Get a shipment status","description":"Retrieve the current tracking status and event history of a shipment.","tags":["Shipments"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/GetShipmentRequest"},"example":{"tracking_number":"6860010537552","tracking_provider":"delhivery"}}}},"responses":{"200":{"description":"Shipment tracking data, or an error object when the tracking does not exist.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShipmentStatusResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/InvalidRoute"},"500":{"$ref":"#\/components\/responses\/ServerError"}}}},"\/shipment\/by-order-id":{"post":{"operationId":"getShipmentsByOrderId","summary":"Get shipments by order id","description":"Retrieve the tracking status of all shipments associated with a specific order id.","tags":["Shipments"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ByOrderIdRequest"},"example":{"order_id":"141"}}}},"responses":{"200":{"description":"A list of shipments for the order, or an error object when the order id is not found.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ByOrderIdResponse"}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/InvalidRoute"},"500":{"$ref":"#\/components\/responses\/ServerError"}}}},"\/shipment\/delete\/":{"post":{"operationId":"deleteShipment","summary":"Delete a shipment tracker","description":"Delete a shipment tracker for the given tracking number, provider, and order id.","tags":["Shipments"],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DeleteShipmentRequest"},"example":{"tracking_number":"1Z4937W56728755212","tracking_provider":"ups","order_id":"10"}}}},"responses":{"200":{"description":"Deletion result.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/DeleteShipmentResponse"},"examples":{"success":{"value":{"status":"success","message":"Shipment deleted successfully"}},"error":{"value":{"status":"error","message":"app name not found"}}}}}},"400":{"$ref":"#\/components\/responses\/BadRequest"},"401":{"$ref":"#\/components\/responses\/Unauthorized"},"404":{"$ref":"#\/components\/responses\/InvalidRoute"},"500":{"$ref":"#\/components\/responses\/ServerError"}}}},"\/shipping_carriers\/supported":{"get":{"operationId":"getSupportedShippingProviders","summary":"Get all shipping providers","description":"List all shipping providers (carriers) supported by TrackShip. This endpoint does not require authentication.","tags":["Shipping providers"],"security":[],"responses":{"200":{"description":"The full list of supported shipping providers.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ShippingProvidersResponse"},"example":{"success":true,"data":[{"label":"Australia Post","slug":"australia-post"},{"label":"CouriersPlease","slug":"couriersplease"}]}}}},"500":{"$ref":"#\/components\/responses\/ServerError"}}}}},"components":{"securitySchemes":{"TrackShipApiKey":{"type":"apiKey","in":"header","name":"trackship-api-key","description":"Your TrackShip API key. Found under Account Setting > API Key."},"AppName":{"type":"apiKey","in":"header","name":"app-name","description":"Your app name. Found under Stores > settings > Webhook."}},"responses":{"BadRequest":{"description":"The requested parameter is missing (e.g. order id, tracking number, or shipping provider not found).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"status":"error","message":"Order id not found"}}}},"Unauthorized":{"description":"Unauthorized API access. Causes include `ssl_error` (store URL is not HTTPS) or `unauthorized` (invalid API key or the store does not exist).","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"status":"error","message":"unauthorized"}}}},"InvalidRoute":{"description":"The API route does not exist. Check the URL and try again.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"status":"error","message":"Invalid route"}}}},"ServerError":{"description":"The server encountered an unexpected condition that prevented it from fulfilling the request.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"status":"error","message":"Internal Server Error"}}}}},"schemas":{"CreateShipmentRequest":{"type":"object","required":["tracking_number","tracking_provider","order_id"],"properties":{"tracking_number":{"type":"string","description":"Tracking number for the package."},"tracking_provider":{"type":"string","description":"Unique code of the tracking provider. See the shipping provider reference."},"order_id":{"type":"string","description":"Respective order id."},"postal_code":{"type":"string","description":"Postal code of the receiver's address. Required for some couriers, such as postnl-3s."},"destination_country":{"type":"string","description":"Destination country of the receiver's address (e.g. NL). Required for some couriers, such as postnl-3s."}}},"CreateShipmentResponse":{"type":"object","properties":{"status":{"type":"string","description":"Response status (e.g. ok\/error)."},"status_msg":{"type":"string","description":"Status message explaining the state of the shipment (e.g. pending_trackship, ssl_error, Order id not found)."},"trackers_balance":{"type":"string","description":"Available tracker balance of the TrackShip account."},"user_plan":{"type":"string","description":"Active subscription plan of the TrackShip account (e.g. Free 50, Mini, Small)."}}},"GetShipmentRequest":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Tracking number for the package."},"tracking_provider":{"type":"string","description":"Unique code of the tracking provider for that tracking."}}},"ByOrderIdRequest":{"type":"object","required":["order_id"],"properties":{"order_id":{"type":"string","description":"The unique id of the order."}}},"DeleteShipmentRequest":{"type":"object","required":["tracking_number","tracking_provider","order_id"],"properties":{"tracking_number":{"type":"string","description":"Tracking number for the package."},"tracking_provider":{"type":"string","description":"Unique code of the tracking provider for that tracking."},"order_id":{"type":"string","description":"Respective order id."}}},"ShipmentStatusResponse":{"type":"object","properties":{"status":{"type":"string","description":"success or error."},"data":{"$ref":"#\/components\/schemas\/ShipmentData"},"message":{"type":"string","description":"Response message (present on error, e.g. \"tracking information is not exist\")."}}},"ByOrderIdResponse":{"type":"object","properties":{"status":{"type":"string","description":"success or error."},"data":{"type":"array","description":"Shipment tracking data for every shipment on the order.","items":{"$ref":"#\/components\/schemas\/ShipmentData"}},"message":{"type":"string","description":"Response message (present on error, e.g. \"Order ID not found\")."}}},"ShipmentData":{"type":"object","properties":{"order_id":{"type":"string"},"tracking_number":{"type":"string"},"tracking_provider":{"type":"string"},"tracking_event_status":{"type":"string","description":"Current tracking status (e.g. pre_transit, in_transit, delivered)."},"tracking_est_delivery_date":{"type":["string","null"]},"origin_country":{"type":["string","null"]},"destination_country":{"type":["string","null"]},"delivery_number":{"type":["string","null"]},"delivery_provider":{"type":["string","null"]},"shipping_service":{"type":["string","null"]},"last_event_time":{"type":["string","null"]},"events":{"type":"array","items":{"$ref":"#\/components\/schemas\/TrackingEvent"}},"destination_events":{"type":["array","null"],"items":{"$ref":"#\/components\/schemas\/TrackingEvent"}}}},"TrackingEvent":{"type":"object","properties":{"object":{"type":"string","description":"Object type, e.g. TrackingDetail."},"message":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"},"status_detail":{"type":"string"},"datetime":{"type":"string"},"source":{"type":"string"},"tracking_location":{"$ref":"#\/components\/schemas\/TrackingLocation"}}},"TrackingLocation":{"type":"object","properties":{"object":{"type":"string","description":"Object type, e.g. TrackingLocation."},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"zip":{"type":"string"}}},"DeleteShipmentResponse":{"type":"object","properties":{"status":{"type":"string","description":"success or error."},"message":{"type":"string","description":"Response message."}}},"ShippingProvidersResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the API response succeeded."},"data":{"type":"array","description":"Supported shipping providers.","items":{"$ref":"#\/components\/schemas\/ShippingProvider"}}}},"ShippingProvider":{"type":"object","properties":{"label":{"type":"string","description":"Human-readable carrier name (e.g. Australia Post)."},"slug":{"type":"string","description":"Unique provider code used as tracking_provider (e.g. australia-post)."}}},"Error":{"type":"object","description":"Standard error object returned by the TrackShip API.","properties":{"status":{"type":"string","description":"Always \"error\" for error responses."},"message":{"type":"string","description":"Human-readable error message."}}}}}}