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.
You can read more about card states in the Card lifecycle model guide.
The only way you can cancel a card, is by using the Atomic API, more specifically the Cards API.
The Atomic API overview is a great place to start when you're new to making requests to the Atomic API. It contains information about where to find the latest API spec and how to set up authentication when you want to make curl
requests.
Set up Insomnia
If you prefer to use a third party tool to interact with the Atomic API, have a look at the Using Insomnia guide. This is the recommended approach for non-developers.
In order to cancel cards, make sure you have followed the guide and sent yourself a card successfully. 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 have their checkbox ticked, which means the cancel request is not scoped in any way.
- To cancel more than 1 card in 1 request, you'll need to check the 'multiple' parameter and write a
1
next to it. Otherwise you'll receive a400 Bad request
error code. - By default you can only cancel 500 cards at a time, that can be increased to 1000 by using the
limit
parameter. If there are more than 1,000 cards that need cancelling, you can make multiple requests until there are no cards left. - You can combine multiple parameters, or only use one. Always make sure you tick the checkbox and you provide a value next to the parameter name.
The screenshot above shows how you can cancel all cards sent to a specific userId.
You need to set the correct userId value, and pass a 1 value to the multiple parameter, before you hit Send
. If your request is successful, you see a list of cancelled card instances in the 'preview' pane. At the bottom of this pane, you see the number of cards that were cancelled, in the summary
section.