Skip to main content

Deleting Releases

This guide explains how to safely delete a release item from your inventory.

You must delete all listings associated with a release before you can delete the release itself.

Prerequisites​

  • Admin API access with appropriate permissions
  • A release item with listings you want to delete

Overview​

In Common Ground, releases (items) can have multiple listings (variants). Delete all listings before deleting the release. This is a safety measure to prevent accidental data loss.

The process involves:

  1. Query the Release: Get the release item and identify all its listings
  2. Delete Listings: Delete each listing one by one
  3. Delete the Release: Once all listings are removed, delete the release item

Step-by-Step Instructions​

Step 1: Query the Release and Listings​

Query the release to get its details and list all associated listings.

GraphQL Query:

query GetItem($id: Float!) {
  item(id: $id) {
    _id
    id
    title
    listings {
      _id
      id
      status
      stock {
        quantity
      }
    }
  }
}

Variables:

{
  "id": 1234567890
}

Response:

{
  "data": {
    "item": {
      "_id": "68dbe59d99c2bb3a009b822e",
      "id": 1234567890,
      "title": "Example Release",
      "listings": [
        {
          "_id": "68dbe59d99c2bb3a009b8241",
          "id": 1234567890123,
          "status": "active",
          "stock": {
            "quantity": 5
          }
        },
        {
          "_id": "68dbe59d99c2bb3a009b8242",
          "id": 1234567890124,
          "status": "active",
          "stock": {
            "quantity": 0
          }
        }
      ]
    }
  }
}

Step 2: Delete Each Listing​

Delete each listing using the itemListingDelete mutation. You'll need the listingRef (the _id of each listing).

GraphQL Mutation:

mutation DeleteListing($listingRef: ID!) {
  itemListingDelete(listingRef: $listingRef) {
    _id
    id
    title
    listings {
      _id
      id
    }
  }
}

Variables:

{
  "listingRef": "68dbe59d99c2bb3a009b8241"
}

Response:

{
  "data": {
    "itemListingDelete": {
      "_id": "68dbe59d99c2bb3a009b822e",
      "id": 1234567890,
      "title": "Example Release",
      "listings": [
        {
          "_id": "68dbe59d99c2bb3a009b8241",
          "id": 1234567890123
        }
      ]
    }
  }
}

Repeat this step for each listing until all listings are deleted.

Step 3: Delete the Release​

Once all listings are deleted, you can delete the release item using the itemDelete mutation.

mutation DeleteItem($itemRef: ID!) {
  itemDelete(itemRef: $itemRef)
}

Variables:

{
  "itemRef": "68dbe59d99c2bb3a009b822e"
}

Response:

{
  "data": {
    "itemDelete": "Ok"
  }
}

Error Handling​

Common Errors​

"Item not found"

  • Verify the item ID is correct
  • Ensure you have permission to access the item
  • Check that the item hasn't already been deleted

"Listing not found"

  • Verify the listing reference (_id) is correct
  • Ensure the listing belongs to the item you're trying to delete

"Item not found" when trying to delete the release

  • This error occurs when the item still has listings
  • Ensure all listings have been deleted before attempting to delete the release
  • Re-query the item to verify it has no listings: item.listings.length === 0

"Cannot delete item with listings"

  • The API prevents deleting items that still have listings
  • Delete all listings before attempting to delete the release (Steps 1-2)

Deleting a release is permanent and cannot be undone. Always delete all listings before deleting the release—the API will reject deletion attempts if listings exist. Consider the impact on inventory when deleting listings with stock, and the impact on order history if the release has been ordered. For deleting multiple releases, consider using a job/bulk operation if available.

Next Steps​