Cancel cards
Cancelling a card means that the (open) state of card will be changed to (closed) state of cancelled. A cancelled card will no longer show in your customer's card stream. Open state cards include those with a status of snoozed or embargoed. You can read more about card states in the Card lifecycle model guide.
There are 2 ways to cancel cards: from within the workbench, or by using the API. This guide explains both approaches.
Cancel cards from the workbench
The cancel cards tool is currently in beta and has the following limitations:
- the maximum number of cards that can be cancelled per request is 100,000
- trying to cancel over 100,000 cards in a single request might result in the cancellation task timing out or the workbench failing to load
Contact us if you have any feedback.
Who can cancel cards from the workbench?
Only workbench members with an admin-level permission on the card-instance resource will be able to use the new tool. This is a new permission level for this resource, so as a first step, you’ll need to make sure it is granted to those who require access to the tool. If you don't have the right permission, you can still see the cancel cards tool, but you won't be able to use it.
An overview of all available permissions on workbench resources can be found in this permissions overview table.
Setting up permissions for roles and groups is described in the workbench permissions guide.
Where can I find the cancel cards tool in the workbench?
The new Cancel cards feature is available in the Tools section of the workbench. Everyone can see the tool, but only those with the required permission (see previous paragraph) can use it.
How do I cancel cards in the workbench?
In the “Cancel cards” tool, you can apply 1 or more criteria to the cards you want to cancel. Cards must match all criteria to be cancelled.
Once you’ve added your criteria, click the Review before cancelling button. It will show you how many cards match the criteria, and will be cancelled once you click the Cancel cards now button.
After clicking Cancel cards now, you’ll see a new box appear in the right hand section of the Cancel cards tool, saying the cancellation is in progress. Once the cancellation job is complete, the cancel cards tool will show you the selected criteria, the number of cancelled cards and who cancelled the cards.
Cancel cards using the Cards API
It is also possible to cancel cards using the Cards API, as explained in the cancel cards section of the Cards API guide.
Set up Insomnia
If you prefer to use a third-party tool to interact with the Atomic API, look at the Using Insomnia guide.
To cancel cards, make sure you have followed the guide and sent yourself a card successfully using Insomnia. This means that you have correctly configured everything that's needed:
- you have configured all Insomnia environment variables correctly
- you have set up authentication controls
- you have an access token
- you have an Events scoped token
Cancel cards using Insomnia
- Select the request titled Cancel cards from your collection.
- Click on the 'query' tab. You can now see the URL preview and a list of possible query parameters. By default, none of these parameters has their checkbox ticked, which means the cancel request is not scoped in any way.
You can combine multiple parameters, or only use one. Always make sure you tick the checkbox, and provide a value next to the parameter name.
The screenshot above shows how to cancel all cards sent to a specific userId.
You must set the correct userId value before you hit Send. If your request is successful, you will receive a response containing a link to the cancel-status endpoint. This endpoint can then be called to view the status of the cancellation job.