Delete

Tracr provides an API endpoint to delete diamonds. Upon deletion, a diamond is permanently removed from the inventory and cannot be restored.

The intention of this endpoint is to give participants the ability to correct data errors with diamonds they've uploaded to Tracr simply by deleting the diamond and re-uploading it with the corrected information.

It is not available to retailers and cannot be used on diamonds that have been unlocked (either manually via the portal or automatically via another action, such as transferring to another participant), or diamonds with descendants (children of that diamond, or children of those children and so on...) that have been unlocked.

Delete diamond without descendants

Call POST /bulk/diamonds/delete

{
  "diamonds": [
    {
      "diamond_id": "clmkgill50000ps17ogi4d2yu"
    }
  ]
}

If the diamond was successfully deleted this will be marked in the response:

{
  "results": [
    {
      "diamond_id": "clmkgill50000ps17ogi4d2yu",
      "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9",
      "status": "success",
      "descendants": []
    }
  ]
}

If it could not be deleted, the reason will be given:

{
  "results": [
    {
      "diamond_id": "clmkgill50000ps17ogi4d2yu",
      "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9",
      "status": "diamond_transferred",
      "error": "The diamond could not be deleted because it has been transferred.",
      "descendants": []
    }
  ]
}

Delete diamond with descendants

A diamond with descendants cannot be deleted unless those descendants are deleted simultaneously (for example, a rough diamond that was split into two roughs that were subsequently polished cannot be deleted unless those polished diamonds are also deleted).

To delete the descendants in addition to the diamond, add a delete_descendants flag to the diamond in the request body:

call POST /bulk/diamonds/delete

{
  "diamonds": [
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "delete_descendants": true
    }
  ]
}

If the delete succeeds then the diamond's descendants are returned:

{
  "results": [
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050",
      "status": "success",
      "descendants": [
        {
          "diamond_id": "clmkh5ln90000mv17o65tslpo",
          "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf"
        },
        {
          "diamond_id": "clmkh74z40001mv17em0uu3tz",
          "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a"
        }
      ]
    }
  ]
}

If one of the descendants cannot be deleted then the diamond and all its descendants remain in the inventory, and the diamonds that could not be deleted are marked in the response:

{
  "results": [
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050",
      "status": "descendants_in_active_shipment",
      "error": "The diamond could not be deleted because one or more of its descendants are in an active shipment.",
      "descendants": [
        {
          "diamond_id": "clmkh74z40001mv17em0uu3tz",
          "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a"
        }
      ]
    }
  ]
}

Likewise if the request is made with delete_descendants set to false, or not set at all, deletion fails and the diamonds remain in the inventory:

call POST /bulk/diamonds/delete

Request

{
  "diamonds": [
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
    }
  ]
}

Response

{
  "results": [
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050",
      "status": "diamond_has_descendants",
      "error": "The diamond could not be deleted because it has descendants.",
      "descendants": [
        {
          "diamond_id": "clmkh5ln90000mv17o65tslpo",
          "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf"
        },
        {
          "diamond_id": "clmkh74z40001mv17em0uu3tz",
          "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a"
        }
      ]
    }
  ]
}

Delete multiple diamonds

The endpoint can handle deletion requests for multiple diamonds (up to 1,000) simultaneously. When sending multiple diamond IDs, each diamond is treated in isolation:

call POST /bulk/diamonds/delete

Request

{
  "diamonds": [
    {
      "diamond_id": "clmkgill50000ps17ogi4d2yu",
    },
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "delete_descendants": false
    },
    {
      "diamond_id": "clmkhq91j0003mv176jo5ir3z",
      "delete_descendants": true
    }
  ]
}

Response

{
  "results": [
    {
      "diamond_id": "clmkgill50000ps17ogi4d2yu",
      "participant_id":"cb482ea8-5a95-431b-88df-84fc363ebda9",
      "status": "diamond_in_active_shipment",
      "error": "The diamond could not be deleted because it is in an active shipment.",
    },
    {
      "diamond_id": "clmkhpl870002mv17475ur906",
      "participant_id": "71a2e460-902f-4bf2-8fa1-5c226847d050",
      "status": "diamond_has_descendants",
      "error": "The diamond could not be deleted because it has descendants.",
      "descendants": [
        {
          "diamond_id": "clmkh5ln90000mv17o65tslpo",
          "participant_id": "dc7d63ea-df23-4d21-a04a-c611f5f483cf"
        },
        {
          "diamond_id": "clmkh74z40001mv17em0uu3tz",
          "participant_id": "951bf2f2-1c49-43c9-a51e-518c62186b2a"
        }
      ]
    },
    {
      "diamond_id": "clmkhq91j0003mv176jo5ir3z",
      "participant_id": "f2eccb09-c4a7-405e-8bda-4cd8fbbf9e8e",
      "status": "success",
      "descendants": []
    }
  ]
}