Skip to main content

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

  1. Select the request titled ‘Cancel cards’ from your collection.
  2. 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 a 400 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.