> For the complete documentation index, see [llms.txt](https://docs.tracr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tracr.com/api-reference/tracr-api/references/shipments.md). # Shipments ## List inbound shipments > Return all inbound shipments matching the filters defined by the query\ > parameters. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/inbound":{"get":{"description":"Return all inbound shipments matching the filters defined by the query\nparameters.","operationId":"list_shipments_v2_shipment_inbound_get","parameters":[{"description":"Filter to shipments created on or after the given timestamp. Must be an ISO-8601 compliant timestamp.","in":"query","name":"created_at__gte","required":false,"schema":{"description":"Filter to shipments created on or after the given timestamp. Must be an ISO-8601 compliant timestamp.","format":"date-time","title":"Created At Gte","type":"string"}},{"description":"Filter to shipments created after the before timestamp. Must be an ISO-8601 compliant timestamp.","in":"query","name":"created_at__lt","required":false,"schema":{"description":"Filter to shipments created after the before timestamp. Must be an ISO-8601 compliant timestamp.","format":"date-time","title":"Created At Lt","type":"string"}},{"description":"Filter to shipments with the given shipment IDs.","in":"query","name":"id__in","required":false,"schema":{"description":"Filter to shipments with the given shipment IDs.","title":"Id In","type":"string"}},{"description":"Filter to shipments with an exact match on the given name.","in":"query","name":"name","required":false,"schema":{"description":"Filter to shipments with an exact match on the given name.","title":"Name","type":"string"}},{"description":"Filter to shipments where the name contains the given value (case sensitive).","in":"query","name":"name__contains","required":false,"schema":{"description":"Filter to shipments where the name contains the given value (case sensitive).","title":"Name Contains","type":"string"}},{"description":"Filter to shipments where the name contains the given value (case insensitive).","in":"query","name":"name__icontains","required":false,"schema":{"description":"Filter to shipments where the name contains the given value (case insensitive).","title":"Name Icontains","type":"string"}},{"description":"Filter to shipments with the given shipment type.","in":"query","name":"shipment_type","required":false,"schema":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Filter to shipments with the given shipment type.","title":"Shipment Type"}},{"description":"Unified search for shipments. This will return any shipments where the given value is contained within their name, ID, or sender.","in":"query","name":"search","required":false,"schema":{"description":"Unified search for shipments. This will return any shipments where the given value is contained within their name, ID, or sender.","title":"Search","type":"string"}},{"in":"query","name":"order_by","required":false,"schema":{"default":"created_at,id","title":"Order By","type":"string"}},{"description":"Filter to shipments with an exact match on the given sender.","in":"query","name":"sender","required":false,"schema":{"description":"Filter to shipments with an exact match on the given sender.","title":"Sender","type":"string"}},{"description":"Filter to shipments where the sender contains the given value (case sensitive).","in":"query","name":"sender__contains","required":false,"schema":{"description":"Filter to shipments where the sender contains the given value (case sensitive).","title":"Sender Contains","type":"string"}},{"description":"Filter to shipments where the sender contains the given value.(case sensitive).","in":"query","name":"sender__icontains","required":false,"schema":{"description":"Filter to shipments where the sender contains the given value.(case sensitive).","title":"Sender Icontains","type":"string"}},{"description":"Filter to shipments with the given status.","in":"query","name":"status","required":false,"schema":{"$ref":"#/components/schemas/InboundShipmentStatus","description":"Filter to shipments with the given status.","title":"Status"}},{"description":"Filter to shipments with the given status.","in":"query","name":"status__in","required":false,"schema":{"description":"Filter to shipments with the given status.","title":"Status In","type":"string"}},{"description":"The diamond's globally unique Tracr ID.","in":"query","name":"diamonds__diamond_id","required":false,"schema":{"description":"The diamond's globally unique Tracr ID.","title":"Diamonds Diamond Id","type":"string"}},{"description":"The diamond's globally unique Tracr ID.","in":"query","name":"diamonds__diamond_id__in","required":false,"schema":{"description":"The diamond's globally unique Tracr ID.","title":"Diamonds Diamond Id In","type":"string"}},{"in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"title":"Page","type":"integer"}},{"in":"query","name":"size","required":false,"schema":{"default":100,"maximum":1000,"minimum":1,"title":"Size","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentV2ListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List inbound shipments","tags":["Shipments"]}}},"components":{"schemas":{"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"InboundShipmentStatus":{"description":"Derived statuses for inbound shipments.","enum":["action_required","cancelled","complete","empty","incomplete","processing","rejected"],"title":"InboundShipmentStatus","type":"string"},"InboundShipmentV2ListResponse":{"description":"A paginated response containing zero or more inbound shipments.","properties":{"next":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The URL for the next page.","title":"Next"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"The number of the current page.","title":"Page"},"pages":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"description":"The total number of pages.","title":"Pages"},"previous":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The URL of the previous page.","title":"Previous"},"results":{"description":"The results for the current page.","items":{"$ref":"#/components/schemas/InboundShipmentV2"},"title":"Results","type":"array"},"total":{"description":"The total number of results across all pages.","minimum":0,"title":"Total","type":"integer"}},"required":["page","results","total"],"title":"InboundShipmentV2ListResponse","type":"object"},"InboundShipmentV2":{"description":"An inbound shipment containing diamonds that can be transferred to this Tracr instance.\n\nInbound diamonds can be accepted or rejected using the transfer API collection.\n\nThis schema is specific to the /v2/shipment collection.","properties":{"created_at":{"description":"The time at which this Tracr instance was first notified of the shipment.","format":"date-time","title":"Created At","type":"string"},"diamonds":{"description":"A list of all diamonds contained within this shipment.","items":{"$ref":"#/components/schemas/InboundShipmentDiamondV2"},"title":"Diamonds","type":"array"},"id":{"description":"The shipment's globally unique identifier.","title":"Id","type":"string"},"name":{"description":"The shipment's name, populated by the sender.","title":"Name","type":"string"},"sender":{"description":"The API URL of the participant who created this shipment.","title":"Sender","type":"string"},"shipment_type":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Whether the shipment contains rough or polished diamonds."},"status":{"$ref":"#/components/schemas/InboundShipmentStatus","description":"Aggregated status of the diamonds within a shipment."},"total_diamonds":{"description":"The total number of diamonds in the shipment. This can be larger than the count of diamonds in the shipment if the shipment is still being received.","title":"Total Diamonds","type":"integer"}},"required":["id","name","sender","diamonds","created_at","shipment_type","status","total_diamonds"],"title":"InboundShipmentV2","type":"object"},"InboundShipmentDiamondV2":{"description":"A diamond within an inbound shipment.\n\nThis schema is specific to the /v2/shipment API collection.","properties":{"created_at":{"description":"The time at which this Tracr instance was notified of the diamond being part of an inbound shipment. Not all diamonds are sent at the same time, so this timestamp will differ between diamonds in the shipment.","format":"date-time","title":"Created At","type":"string"},"diamond_id":{"description":"The diamond's globally unique Tracr ID.","pattern":"^[a-z\\d]{20,98}$","title":"Diamond Id","type":"string"},"lifecycle_state":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"The diamond's lifecycle state. Shipments can only contain diamonds in states rough or polished."},"polished":{"anyOf":[{"$ref":"#/components/schemas/InboundShipmentDiamondV2Polished"},{"type":"null"}],"description":"A summary of the diamond's polished attributes. If the diamond is rough, this field will be null."},"rough":{"anyOf":[{"$ref":"#/components/schemas/InboundShipmentDiamondV2Rough"},{"type":"null"}],"description":"A summary of the diamond's rough attributes. If the diamond is polished, this field will be null."},"transfer_state":{"$ref":"#/components/schemas/InboundDiamondState","description":"The stage of transfer that the diamond is currently in. The terminal states are transferred, cancelled, and rejected. All intermediate states mean the transfer is in progress."},"updated_at":{"description":"The last time this diamond was updated. At present, diamonds in a shipment cannot be updated through the API. All changes occur due to automated background processes.","format":"date-time","title":"Updated At","type":"string"}},"required":["created_at","diamond_id","lifecycle_state","polished","rough","transfer_state","updated_at"],"title":"InboundShipmentDiamondV2","type":"object"},"InboundShipmentDiamondV2Polished":{"description":"Summary of an inbound diamond's polished attributes.","properties":{"carats":{"title":"Carats","type":"string"},"clarity":{"anyOf":[{"$ref":"#/components/schemas/Clarity"},{"type":"null"}]},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"cut_grade":{"anyOf":[{"$ref":"#/components/schemas/CutGrade"},{"type":"null"}]},"inscription_numbers":{"items":{"type":"string"},"title":"Inscription Numbers","type":"array"},"report_numbers":{"items":{"type":"string"},"title":"Report Numbers","type":"array"},"shape":{"$ref":"#/components/schemas/Shape"}},"required":["carats","inscription_numbers","report_numbers","shape"],"title":"InboundShipmentDiamondV2Polished","type":"object"},"Clarity":{"enum":["FL","IF","LC","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3","P1","P2","P3"],"title":"Clarity","type":"string"},"CutGrade":{"enum":["I","EX","VG","G","F","P","NA"],"title":"CutGrade","type":"string"},"Shape":{"description":"An enum of the possible values for the shape of a diamond.","enum":["Asscher","Baguette","Briolette","Bullets","Calf","Cushion","Cushion Modified Brilliant","Emerald","European Cut","Flanders","Half Moon","Heart","Hexagonal","Kite","Lozenge","Marquise","Octagonal","Old Miner","Oval","Pear","Pentagonal","Princess","Radiant","Rectangle","Rose","Round","Shield","Square","Square Emerald","Square Radiant","Star","Tapered Baguette","Tapered Bullet","Trapezoid","Triangle","Trilliant","Other"],"title":"Shape","type":"string"},"InboundShipmentDiamondV2Rough":{"description":"Summary of an inbound diamond's rough attributes.","properties":{"box_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Box Id"},"carats":{"title":"Carats","type":"string"},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"sight_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Number"},"sight_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Year"},"stress":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stress"}},"required":["carats"],"title":"InboundShipmentDiamondV2Rough","type":"object"},"InboundDiamondState":{"enum":["accepted","cancelled","owned","pending_reject","pending_verification","rejected","transferred","transfer_in_confirmed","transfer_in_pending","verification_failed","verified"],"title":"InboundDiamondState","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` ## Get inbound shipment filters > Return the discrete filter values that can be used to filter inbound\ > shipments. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/inbound/filter":{"get":{"description":"Return the discrete filter values that can be used to filter inbound\nshipments.","operationId":"filters_v2_shipment_inbound_filter_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentV2FiltersResponse"}}},"description":"Successful Response"}},"summary":"Get inbound shipment filters","tags":["Shipments"]}}},"components":{"schemas":{"InboundShipmentV2FiltersResponse":{"description":"Dynamically populated values for inbound shipment filters.","properties":{"shipment_type":{"items":{"$ref":"#/components/schemas/ShipmentLifecycleState"},"title":"Shipment Type","type":"array"},"status":{"items":{"$ref":"#/components/schemas/InboundShipmentStatus"},"title":"Status","type":"array"}},"required":["shipment_type","status"],"title":"InboundShipmentV2FiltersResponse","type":"object"},"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"InboundShipmentStatus":{"description":"Derived statuses for inbound shipments.","enum":["action_required","cancelled","complete","empty","incomplete","processing","rejected"],"title":"InboundShipmentStatus","type":"string"}}}} ``` ## Get inbound shipment > Retrieve the details of a given inbound shipment. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/inbound/{shipment_id}":{"get":{"description":"Retrieve the details of a given inbound shipment.","operationId":"detail_v2_shipment_inbound__shipment_id__get","parameters":[{"description":"The ID of the shipment to return.","in":"path","name":"shipment_id","required":true,"schema":{"description":"The ID of the shipment to return.","title":"Shipment Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InboundShipmentV2DetailResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get inbound shipment","tags":["Shipments"]}}},"components":{"schemas":{"InboundShipmentV2DetailResponse":{"description":"A response containing a single inbound shipment.","properties":{"created_at":{"description":"The time at which this Tracr instance was first notified of the shipment.","format":"date-time","title":"Created At","type":"string"},"diamonds":{"description":"A list of all diamonds contained within this shipment.","items":{"$ref":"#/components/schemas/InboundShipmentDiamondV2"},"title":"Diamonds","type":"array"},"id":{"description":"The shipment's globally unique identifier.","title":"Id","type":"string"},"name":{"description":"The shipment's name, populated by the sender.","title":"Name","type":"string"},"sender":{"description":"The API URL of the participant who created this shipment.","title":"Sender","type":"string"},"shipment_type":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Whether the shipment contains rough or polished diamonds."},"status":{"$ref":"#/components/schemas/InboundShipmentStatus","description":"Aggregated status of the diamonds within a shipment."},"total_diamonds":{"description":"The total number of diamonds in the shipment. This can be larger than the count of diamonds in the shipment if the shipment is still being received.","title":"Total Diamonds","type":"integer"}},"required":["id","name","sender","diamonds","created_at","shipment_type","status","total_diamonds"],"title":"InboundShipmentV2DetailResponse","type":"object"},"InboundShipmentDiamondV2":{"description":"A diamond within an inbound shipment.\n\nThis schema is specific to the /v2/shipment API collection.","properties":{"created_at":{"description":"The time at which this Tracr instance was notified of the diamond being part of an inbound shipment. Not all diamonds are sent at the same time, so this timestamp will differ between diamonds in the shipment.","format":"date-time","title":"Created At","type":"string"},"diamond_id":{"description":"The diamond's globally unique Tracr ID.","pattern":"^[a-z\\d]{20,98}$","title":"Diamond Id","type":"string"},"lifecycle_state":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"The diamond's lifecycle state. Shipments can only contain diamonds in states rough or polished."},"polished":{"anyOf":[{"$ref":"#/components/schemas/InboundShipmentDiamondV2Polished"},{"type":"null"}],"description":"A summary of the diamond's polished attributes. If the diamond is rough, this field will be null."},"rough":{"anyOf":[{"$ref":"#/components/schemas/InboundShipmentDiamondV2Rough"},{"type":"null"}],"description":"A summary of the diamond's rough attributes. If the diamond is polished, this field will be null."},"transfer_state":{"$ref":"#/components/schemas/InboundDiamondState","description":"The stage of transfer that the diamond is currently in. The terminal states are transferred, cancelled, and rejected. All intermediate states mean the transfer is in progress."},"updated_at":{"description":"The last time this diamond was updated. At present, diamonds in a shipment cannot be updated through the API. All changes occur due to automated background processes.","format":"date-time","title":"Updated At","type":"string"}},"required":["created_at","diamond_id","lifecycle_state","polished","rough","transfer_state","updated_at"],"title":"InboundShipmentDiamondV2","type":"object"},"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"InboundShipmentDiamondV2Polished":{"description":"Summary of an inbound diamond's polished attributes.","properties":{"carats":{"title":"Carats","type":"string"},"clarity":{"anyOf":[{"$ref":"#/components/schemas/Clarity"},{"type":"null"}]},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"cut_grade":{"anyOf":[{"$ref":"#/components/schemas/CutGrade"},{"type":"null"}]},"inscription_numbers":{"items":{"type":"string"},"title":"Inscription Numbers","type":"array"},"report_numbers":{"items":{"type":"string"},"title":"Report Numbers","type":"array"},"shape":{"$ref":"#/components/schemas/Shape"}},"required":["carats","inscription_numbers","report_numbers","shape"],"title":"InboundShipmentDiamondV2Polished","type":"object"},"Clarity":{"enum":["FL","IF","LC","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3","P1","P2","P3"],"title":"Clarity","type":"string"},"CutGrade":{"enum":["I","EX","VG","G","F","P","NA"],"title":"CutGrade","type":"string"},"Shape":{"description":"An enum of the possible values for the shape of a diamond.","enum":["Asscher","Baguette","Briolette","Bullets","Calf","Cushion","Cushion Modified Brilliant","Emerald","European Cut","Flanders","Half Moon","Heart","Hexagonal","Kite","Lozenge","Marquise","Octagonal","Old Miner","Oval","Pear","Pentagonal","Princess","Radiant","Rectangle","Rose","Round","Shield","Square","Square Emerald","Square Radiant","Star","Tapered Baguette","Tapered Bullet","Trapezoid","Triangle","Trilliant","Other"],"title":"Shape","type":"string"},"InboundShipmentDiamondV2Rough":{"description":"Summary of an inbound diamond's rough attributes.","properties":{"box_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Box Id"},"carats":{"title":"Carats","type":"string"},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"sight_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Number"},"sight_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Year"},"stress":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stress"}},"required":["carats"],"title":"InboundShipmentDiamondV2Rough","type":"object"},"InboundDiamondState":{"enum":["accepted","cancelled","owned","pending_reject","pending_verification","rejected","transferred","transfer_in_confirmed","transfer_in_pending","verification_failed","verified"],"title":"InboundDiamondState","type":"string"},"InboundShipmentStatus":{"description":"Derived statuses for inbound shipments.","enum":["action_required","cancelled","complete","empty","incomplete","processing","rejected"],"title":"InboundShipmentStatus","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` ## List outbound shipments > Return all outbound shipments matching the filters defined by the query\ > parameters. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/outbound":{"get":{"description":"Return all outbound shipments matching the filters defined by the query\nparameters.","operationId":"list_v2_shipment_outbound_get","parameters":[{"description":"Filter to shipments created on or after the given timestamp. Must be an ISO-8601 compliant timestamp.","in":"query","name":"created_at__gte","required":false,"schema":{"description":"Filter to shipments created on or after the given timestamp. Must be an ISO-8601 compliant timestamp.","format":"date-time","title":"Created At Gte","type":"string"}},{"description":"Filter to shipments created after the before timestamp. Must be an ISO-8601 compliant timestamp.","in":"query","name":"created_at__lt","required":false,"schema":{"description":"Filter to shipments created after the before timestamp. Must be an ISO-8601 compliant timestamp.","format":"date-time","title":"Created At Lt","type":"string"}},{"description":"Filter to shipments with the given shipment IDs.","in":"query","name":"id__in","required":false,"schema":{"description":"Filter to shipments with the given shipment IDs.","title":"Id In","type":"string"}},{"description":"Filter to shipments with an exact match on the given name.","in":"query","name":"name","required":false,"schema":{"description":"Filter to shipments with an exact match on the given name.","title":"Name","type":"string"}},{"description":"Filter to shipments where the name contains the given value (case sensitive).","in":"query","name":"name__contains","required":false,"schema":{"description":"Filter to shipments where the name contains the given value (case sensitive).","title":"Name Contains","type":"string"}},{"description":"Filter to shipments where the name contains the given value (case insensitive).","in":"query","name":"name__icontains","required":false,"schema":{"description":"Filter to shipments where the name contains the given value (case insensitive).","title":"Name Icontains","type":"string"}},{"description":"Filter to shipments with the given shipment type.","in":"query","name":"shipment_type","required":false,"schema":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Filter to shipments with the given shipment type.","title":"Shipment Type"}},{"description":"Unified search for shipments. This will return any shipments where the given value is contained within their name, ID, or recipient.","in":"query","name":"search","required":false,"schema":{"description":"Unified search for shipments. This will return any shipments where the given value is contained within their name, ID, or recipient.","title":"Search","type":"string"}},{"in":"query","name":"order_by","required":false,"schema":{"default":"created_at,id","title":"Order By","type":"string"}},{"description":"Filter to shipments with an exact match on the given receiver.","in":"query","name":"receiver","required":false,"schema":{"description":"Filter to shipments with an exact match on the given receiver.","title":"Receiver","type":"string"}},{"description":"Filter to shipments where the receiver contains the given value (case sensitive).","in":"query","name":"receiver__contains","required":false,"schema":{"description":"Filter to shipments where the receiver contains the given value (case sensitive).","title":"Receiver Contains","type":"string"}},{"description":"Filter to shipments where the receiver contains the given value.(case sensitive).","in":"query","name":"receiver__icontains","required":false,"schema":{"description":"Filter to shipments where the receiver contains the given value.(case sensitive).","title":"Receiver Icontains","type":"string"}},{"description":"Filter to shipments with the given status.","in":"query","name":"status","required":false,"schema":{"$ref":"#/components/schemas/OutboundShipmentStatus","description":"Filter to shipments with the given status.","title":"Status"}},{"description":"Filter to shipments with the given status.","in":"query","name":"status__in","required":false,"schema":{"description":"Filter to shipments with the given status.","title":"Status In","type":"string"}},{"description":"The diamond's globally unique Tracr ID.","in":"query","name":"diamonds__diamond_id","required":false,"schema":{"description":"The diamond's globally unique Tracr ID.","title":"Diamonds Diamond Id","type":"string"}},{"description":"The diamond's globally unique Tracr ID.","in":"query","name":"diamonds__diamond_id__in","required":false,"schema":{"description":"The diamond's globally unique Tracr ID.","title":"Diamonds Diamond Id In","type":"string"}},{"in":"query","name":"page","required":false,"schema":{"default":1,"minimum":1,"title":"Page","type":"integer"}},{"in":"query","name":"size","required":false,"schema":{"default":100,"maximum":1000,"minimum":1,"title":"Size","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundShipmentV2ListResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"List outbound shipments","tags":["Shipments"]}}},"components":{"schemas":{"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"OutboundShipmentStatus":{"description":"Derived statuses for outbound shipments.","enum":["accepting","cancelled","cancelling","complete","empty","in_progress","rejected","rejecting","sending","sent"],"title":"OutboundShipmentStatus","type":"string"},"OutboundShipmentV2ListResponse":{"description":"A paginated response containing zero or more outbound shipments.","properties":{"next":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The URL for the next page.","title":"Next"},"page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"The number of the current page.","title":"Page"},"pages":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"description":"The total number of pages.","title":"Pages"},"previous":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The URL of the previous page.","title":"Previous"},"results":{"description":"The results for the current page.","items":{"$ref":"#/components/schemas/OutboundShipmentV2"},"title":"Results","type":"array"},"total":{"description":"The total number of results across all pages.","minimum":0,"title":"Total","type":"integer"}},"required":["page","results","total"],"title":"OutboundShipmentV2ListResponse","type":"object"},"OutboundShipmentV2":{"description":"An outbound shipment containing diamonds that are being transferred from this Tracr instance.\n\nOutbound shipments can be created using the transfer API collection.\nSimilarly the transfer of a diamond within an outbound shipment can be\ncancelled using the transfer API collection.\n\nThis schema is specific to the /v2/shipment collection.","properties":{"created_at":{"description":"The time at which the shipment was created.","format":"date-time","title":"Created At","type":"string"},"diamonds":{"description":"A list of all diamonds contained within this shipment.","items":{"$ref":"#/components/schemas/OutboundShipmentDiamondV2"},"title":"Diamonds","type":"array"},"id":{"description":"The shipment's globally unique identifier.","title":"Id","type":"string"},"name":{"description":"The shipment's name.","title":"Name","type":"string"},"receiver":{"description":"The API URL of the participant to whom this shipment will be sent.","title":"Receiver","type":"string"},"shipment_type":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Whether the shipment contains rough or polished diamonds."},"status":{"$ref":"#/components/schemas/OutboundShipmentStatus","description":"Aggregated status of the diamonds within a shipment."}},"required":["created_at","diamonds","id","name","receiver","shipment_type","status"],"title":"OutboundShipmentV2","type":"object"},"OutboundShipmentDiamondV2":{"description":"A diamond within an outbound shipment.\n\nThis schema is specific to the /v2/shipment API collection.","properties":{"created_at":{"description":"The time at which the diamond was added to the shipment.","format":"date-time","title":"Created At","type":"string"},"diamond_id":{"description":"The diamond's globally unique Tracr ID.","pattern":"^[a-z\\d]{20,98}$","title":"Diamond Id","type":"string"},"lifecycle_state":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"The diamond's lifecycle state. Shipments can only contain diamonds in states rough or polished."},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID.","title":"Participant Id"},"polished":{"anyOf":[{"$ref":"#/components/schemas/OutboundShipmentDiamondV2Polished"},{"type":"null"}],"description":"A summary of the diamond's polished attributes. If the diamond is rough, this field will be null."},"rough":{"anyOf":[{"$ref":"#/components/schemas/OutboundShipmentDiamondV2Rough"},{"type":"null"}],"description":"A summary of the diamond's rough attributes. If the diamond is polished, this field will be null."},"transfer_state":{"$ref":"#/components/schemas/OutboundDiamondState"},"updated_at":{"description":"The last time this diamond was updated. At present, diamonds in a shipment cannot be updated through the API. All changes occur due to automated background processes.","format":"date-time","title":"Updated At","type":"string"}},"required":["created_at","diamond_id","lifecycle_state","participant_id","rough","transfer_state","updated_at","polished"],"title":"OutboundShipmentDiamondV2","type":"object"},"OutboundShipmentDiamondV2Polished":{"description":"Summary of an outbound diamond's polished attributes.","properties":{"carats":{"title":"Carats","type":"string"},"clarity":{"anyOf":[{"$ref":"#/components/schemas/Clarity"},{"type":"null"}]},"colour":{"anyOf":[{"$ref":"#/components/schemas/Colour"},{"type":"null"}]},"cut_grade":{"anyOf":[{"$ref":"#/components/schemas/CutGrade"},{"type":"null"}]},"display_colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Colour"},"inscription_numbers":{"items":{"type":"string"},"title":"Inscription Numbers","type":"array"},"report_numbers":{"items":{"type":"string"},"title":"Report Numbers","type":"array"},"shape":{"$ref":"#/components/schemas/Shape"}},"required":["carats","shape","inscription_numbers","report_numbers"],"title":"OutboundShipmentDiamondV2Polished","type":"object"},"Clarity":{"enum":["FL","IF","LC","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3","P1","P2","P3"],"title":"Clarity","type":"string"},"Colour":{"enum":["D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z"],"title":"Colour","type":"string"},"CutGrade":{"enum":["I","EX","VG","G","F","P","NA"],"title":"CutGrade","type":"string"},"Shape":{"description":"An enum of the possible values for the shape of a diamond.","enum":["Asscher","Baguette","Briolette","Bullets","Calf","Cushion","Cushion Modified Brilliant","Emerald","European Cut","Flanders","Half Moon","Heart","Hexagonal","Kite","Lozenge","Marquise","Octagonal","Old Miner","Oval","Pear","Pentagonal","Princess","Radiant","Rectangle","Rose","Round","Shield","Square","Square Emerald","Square Radiant","Star","Tapered Baguette","Tapered Bullet","Trapezoid","Triangle","Trilliant","Other"],"title":"Shape","type":"string"},"OutboundShipmentDiamondV2Rough":{"description":"Summary of an outbound diamond's rough attributes.","properties":{"box_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Box Id"},"carats":{"title":"Carats","type":"string"},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"display_colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Colour"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"sight_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Number"},"sight_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Year"},"stress":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stress"}},"required":["carats"],"title":"OutboundShipmentDiamondV2Rough","type":"object"},"OutboundDiamondState":{"enum":["accepted","cancelled","rejected","pending_cancel","transferred","transfer_out_confirmed","transfer_out_pending","pending_reject","receiver_informed_of_cancel"],"title":"OutboundDiamondState","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` ## Get outbound shipment filters > Return the discrete filter values that can be used to filter outbound\ > shipments. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/outbound/filter":{"get":{"description":"Return the discrete filter values that can be used to filter outbound\nshipments.","operationId":"filters_v2_shipment_outbound_filter_get","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundShipmentV2FiltersResponse"}}},"description":"Successful Response"}},"summary":"Get outbound shipment filters","tags":["Shipments"]}}},"components":{"schemas":{"OutboundShipmentV2FiltersResponse":{"description":"Dynamically populated values for outbound shipment filters.","properties":{"shipment_type":{"items":{"$ref":"#/components/schemas/ShipmentLifecycleState"},"title":"Shipment Type","type":"array"},"status":{"items":{"$ref":"#/components/schemas/OutboundShipmentStatus"},"title":"Status","type":"array"}},"required":["shipment_type","status"],"title":"OutboundShipmentV2FiltersResponse","type":"object"},"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"OutboundShipmentStatus":{"description":"Derived statuses for outbound shipments.","enum":["accepting","cancelled","cancelling","complete","empty","in_progress","rejected","rejecting","sending","sent"],"title":"OutboundShipmentStatus","type":"string"}}}} ``` ## Get outbound shipment > Retrieve the details of a given outbound shipment. ```json {"openapi":"3.1.0","info":{"title":"Platform Application API","version":"1.34.0"},"servers":[{"description":"Live","url":"https://api..tracr.network"},{"description":"Sandbox","url":"https://api..uat.tracr.network"}],"paths":{"/v2/shipment/outbound/{shipment_id}":{"get":{"description":"Retrieve the details of a given outbound shipment.","operationId":"detail_v2_shipment_outbound__shipment_id__get","parameters":[{"description":"The ID of the shipment to fetch.","in":"path","name":"shipment_id","required":true,"schema":{"description":"The ID of the shipment to fetch.","title":"Shipment Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundShipmentV2DetailResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Get outbound shipment","tags":["Shipments"]}}},"components":{"schemas":{"OutboundShipmentV2DetailResponse":{"description":"A response containing a single outbound shipment.","properties":{"created_at":{"description":"The time at which the shipment was created.","format":"date-time","title":"Created At","type":"string"},"diamonds":{"description":"A list of all diamonds contained within this shipment.","items":{"$ref":"#/components/schemas/OutboundShipmentDiamondV2"},"title":"Diamonds","type":"array"},"id":{"description":"The shipment's globally unique identifier.","title":"Id","type":"string"},"name":{"description":"The shipment's name.","title":"Name","type":"string"},"receiver":{"description":"The API URL of the participant to whom this shipment will be sent.","title":"Receiver","type":"string"},"shipment_type":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"Whether the shipment contains rough or polished diamonds."},"status":{"$ref":"#/components/schemas/OutboundShipmentStatus","description":"Aggregated status of the diamonds within a shipment."}},"required":["created_at","diamonds","id","name","receiver","shipment_type","status"],"title":"OutboundShipmentV2DetailResponse","type":"object"},"OutboundShipmentDiamondV2":{"description":"A diamond within an outbound shipment.\n\nThis schema is specific to the /v2/shipment API collection.","properties":{"created_at":{"description":"The time at which the diamond was added to the shipment.","format":"date-time","title":"Created At","type":"string"},"diamond_id":{"description":"The diamond's globally unique Tracr ID.","pattern":"^[a-z\\d]{20,98}$","title":"Diamond Id","type":"string"},"lifecycle_state":{"$ref":"#/components/schemas/ShipmentLifecycleState","description":"The diamond's lifecycle state. Shipments can only contain diamonds in states rough or polished."},"participant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User supplied identifier for the diamond, specific to this Tracr instance. Synonymous with ERP ID and Stock ID.","title":"Participant Id"},"polished":{"anyOf":[{"$ref":"#/components/schemas/OutboundShipmentDiamondV2Polished"},{"type":"null"}],"description":"A summary of the diamond's polished attributes. If the diamond is rough, this field will be null."},"rough":{"anyOf":[{"$ref":"#/components/schemas/OutboundShipmentDiamondV2Rough"},{"type":"null"}],"description":"A summary of the diamond's rough attributes. If the diamond is polished, this field will be null."},"transfer_state":{"$ref":"#/components/schemas/OutboundDiamondState"},"updated_at":{"description":"The last time this diamond was updated. At present, diamonds in a shipment cannot be updated through the API. All changes occur due to automated background processes.","format":"date-time","title":"Updated At","type":"string"}},"required":["created_at","diamond_id","lifecycle_state","participant_id","rough","transfer_state","updated_at","polished"],"title":"OutboundShipmentDiamondV2","type":"object"},"ShipmentLifecycleState":{"description":"The different diamond lifecycle states that can be transferred (unique per\nshipment).","enum":["rough","polished"],"title":"ShipmentLifecycleState","type":"string"},"OutboundShipmentDiamondV2Polished":{"description":"Summary of an outbound diamond's polished attributes.","properties":{"carats":{"title":"Carats","type":"string"},"clarity":{"anyOf":[{"$ref":"#/components/schemas/Clarity"},{"type":"null"}]},"colour":{"anyOf":[{"$ref":"#/components/schemas/Colour"},{"type":"null"}]},"cut_grade":{"anyOf":[{"$ref":"#/components/schemas/CutGrade"},{"type":"null"}]},"display_colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Colour"},"inscription_numbers":{"items":{"type":"string"},"title":"Inscription Numbers","type":"array"},"report_numbers":{"items":{"type":"string"},"title":"Report Numbers","type":"array"},"shape":{"$ref":"#/components/schemas/Shape"}},"required":["carats","shape","inscription_numbers","report_numbers"],"title":"OutboundShipmentDiamondV2Polished","type":"object"},"Clarity":{"enum":["FL","IF","LC","VVS1","VVS2","VS1","VS2","SI1","SI2","SI3","I1","I2","I3","P1","P2","P3"],"title":"Clarity","type":"string"},"Colour":{"enum":["D","E","F","G","H","I","J","K","L","M","N","O","P","Q","R","S","T","U","V","W","X","Y","Z"],"title":"Colour","type":"string"},"CutGrade":{"enum":["I","EX","VG","G","F","P","NA"],"title":"CutGrade","type":"string"},"Shape":{"description":"An enum of the possible values for the shape of a diamond.","enum":["Asscher","Baguette","Briolette","Bullets","Calf","Cushion","Cushion Modified Brilliant","Emerald","European Cut","Flanders","Half Moon","Heart","Hexagonal","Kite","Lozenge","Marquise","Octagonal","Old Miner","Oval","Pear","Pentagonal","Princess","Radiant","Rectangle","Rose","Round","Shield","Square","Square Emerald","Square Radiant","Star","Tapered Baguette","Tapered Bullet","Trapezoid","Triangle","Trilliant","Other"],"title":"Shape","type":"string"},"OutboundShipmentDiamondV2Rough":{"description":"Summary of an outbound diamond's rough attributes.","properties":{"box_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Box Id"},"carats":{"title":"Carats","type":"string"},"colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Colour"},"display_colour":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Colour"},"model":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model"},"quality":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Quality"},"sight_number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Number"},"sight_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sight Year"},"stress":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stress"}},"required":["carats"],"title":"OutboundShipmentDiamondV2Rough","type":"object"},"OutboundDiamondState":{"enum":["accepted","cancelled","rejected","pending_cancel","transferred","transfer_out_confirmed","transfer_out_pending","pending_reject","receiver_informed_of_cancel"],"title":"OutboundDiamondState","type":"string"},"OutboundShipmentStatus":{"description":"Derived statuses for outbound shipments.","enum":["accepting","cancelled","cancelling","complete","empty","in_progress","rejected","rejecting","sending","sent"],"title":"OutboundShipmentStatus","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tracr.com/api-reference/tracr-api/references/shipments.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.