Modifying existing transaction rules

ⓘ Reading Time: 10 mins

This guide demonstrates how to get, update, and delete existing transaction rules.

⚠

Transaction rules are not enabled by default. To request access, please contact us at [email protected].

We recommend working along as you go, using your API key for our sandbox environment.

⚠

For simplicity, the examples in this guide show you how to send requests to Spade directly. However, you will likely want to build transaction rules into client applications. Because client-side code is public and your API key is secret, you will need to proxy merchant search and transaction rule requests through your backend to Spade's servers. The Merchant Search Guide demonstrates how to proxy requests through your backend to Spade's API.

⚠ NEVER send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc...).

Updating an existing transaction rule

You can use the same endpoint (PUT) to create a transaction rule or to update an existing transaction rule. Because PUT is an idempotent operation, identical calls will produce the same result. Each userId + cardId pair must be unique and can only have one transaction rule, so if you call the PUT endpoint twice with the same userId + cardId pair, the second call will update the existing transaction rule.

For instance, to modify the transaction rule you created as part of the Transaction Rules Guide to allow purchases not just at Walmart, but also at Apple, you would make the following request:

import requests

transaction_rule = {
    "userId": "user123",
    "cardId": "card123",
    "type": "allow",
    "condition": "counterparty_id in @allowed_counterparty_ids",
    "parameters": {
      "allowed_counterparty_ids": [
        "d730906b-f1a8-49f1-9939-f27390170a6d",
        "2b838cce-6565-4632-a53e-efbd2fb4b083"
      ]
    }
}

response = requests.put("https://east.sandbox.spade.com/merchants", json=transaction_rule, headers={"X-Api-Key": "<Your API Key Here>"})
transaction_rule_response = response.json()

print(transaction_rule_response)

Sending the above request returns:

{
  "userId": "user123",
  "cardId": "card123",
  "type": "allow",
  "condition": "counterparty_id in @allowed_counterparty_ids",
  "parameters": {
    "allowed_counterparty_ids": [
      "d730906b-f1a8-49f1-9939-f27390170a6d",
      "2b838cce-6565-4632-a53e-efbd2fb4b083"
    ]
  }
}

The response object contains the new transaction rule for the card card123 associated with user user123. Because transaction rules are unique for a given userId + cardId pair, this request overwrites the existing transaction rule.

Getting an existing transaction rule

To get the existing transaction rule (if it exists) for user123 and card123, you can call the GET endpoint, specifying the user and card IDs as query parameters:

import requests

response = requests.get("https://east.sandbox.spade.com/transaction-rules", params={"userId": "user123", "cardId": "card123"}, headers={"X-Api-Key": "<Your API Key Here>"})
transaction_rules = response.json()

print(transaction_rules)

Sending the above request returns:

[
  {
    "userId": "user123",
    "cardId": "card123",
    "type": "allow",
    "condition": "counterparty_id in @allowed_counterparty_ids",
    "parameters": {
      "allowed_counterparty_ids": [
        "d730906b-f1a8-49f1-9939-f27390170a6d",
        "2b838cce-6565-4632-a53e-efbd2fb4b083"
      ]
    }
  }
]

Deleting an existing transaction rule

To delete the existing transaction rule (if it exists) for user123 and card123, you can call the DELETE endpoint, specifying the user and card IDs as query parameters:

import requests

response = requests.delete("https://east.sandbox.spade.com/transaction-rules", params={"userId": "user123", "cardId": "card123"}, headers={"X-Api-Key": "<Your API Key Here>"})
transaction_rules = response.json()

print(transaction_rules)

Sending the above request returns either:

• 204 - No content; the transaction rule has been deleted
• 404 - Not found; no such transaction rule exists

Conclusion

Congratulations! You've now learned how you can get, update, and delete existing transaction rules. If you have any further questions, make sure to check out the FAQs page.

Next steps

Transaction Rules Language Guide

Transaction Rules FAQ