From b742e47634e211584be81a8c2d42316add417671 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Thu, 15 Jan 2026 19:08:47 +0100 Subject: [PATCH 1/2] Reapply "DOC-1467/add-calendar-spending-limits-to-public-docs (#524)" (#536) This reverts commit 2b5309250c1486b7e5042624b487090949413baa. --- docs/topics/cards/index.mdx | 59 ++++++++++++------- docs/topics/cards/overview/guide-update.mdx | 5 ++ docs/topics/cards/virtual/guide-add.mdx | 63 +++++++++++++++++++++ 3 files changed, 108 insertions(+), 19 deletions(-) diff --git a/docs/topics/cards/index.mdx b/docs/topics/cards/index.mdx index 64ea948d2e5..2795dffa35e 100644 --- a/docs/topics/cards/index.mdx +++ b/docs/topics/cards/index.mdx @@ -155,24 +155,33 @@ You can (1) manage existing card products that are already validated, or (2) cre ## Spending limits {#limits} -A **spending limit** is the **maximum amount** a cardholder can spend within a certain **rolling period**. +A **spending limit** is the **maximum amount** a cardholder can spend within a certain period. Spending limits are imposed for several reasons. -1. Companies impose spending limits to reduce fraud risk. -1. Individual cardholders and companies might impose spending limits over a rolling period to protect their funds when issuing cards to other people. - - A company might impose a 100€ spending limits over 7 days rolling for travel expenses. +1. Companies impose spending limits to reduce fraud risk or to enforce expense rules and budgets. +1. Individual cardholders and companies might impose spending limits over a period to protect their funds when issuing cards to other people. + - A company might impose a 100€ spending limit over 7 days for travel expenses. - A parent might give a card to their child, imposing a 50€ spending limit to protect their own money. 1. Financial institutions (like Swan) impose spending limits to protect themselves from liability. -:::info Rolling spending limit -A rolling period doesn't depend on a determined date, day of the week, or time. -Instead, rolling spending limits consider the amount spent over period of time. -At Swan, some types of accounts can impose rolling limits of 1 month, 7 days, and 24 hours. +### Rolling vs. calendar periods {#limits-periods} + +Swan supports two types of spending limit periods: **rolling** and **calendar**. + +**Rolling periods** track the total spent over a moving window of time, such as the last 24 hours, 7 days, or 30 days. +Rolling is the default period type and is best suited for continuous fraud protection or when spending patterns don't follow a fixed schedule. + +**Calendar periods** reset at a fixed date and time, such as the 1st of every month or every Monday at a specific hour. +Calendar periods are best suited for budgeting cycles, expense management, or when spending needs to align with payroll or billing schedules. + +:::info Non-existent dates +If a calendar period's reset date doesn't exist in a given month, the limit resets on the next available day. +For example, if you set a monthly limit to reset on the 31st, the limit resets on March 1st in February (since February doesn't have a 31st). ::: ### Limits imposed by Swan {#limits-swan} -All spending limits are for a period of **1 month rolling**. +All spending limits imposed by Swan are for a rolling period of **1 month**. Note that **partners** (you) can define spending limits for all card types, while **account holders** can lower spending limits when creating cards. @@ -207,17 +216,29 @@ Note that you can set a lower monthly `spendingLimit` by [updating the card](./o Account holder spending limits **can't exceed** Swan spending limits. If a spending limit is set that exceeds Swan's spending limits, transactions are rejected. -Companies and individual account holders can impose spending limits over three possible periods: +Companies and individual account holders can impose spending limits over the following periods. + +**Rolling periods** (default if no mode is specified): -- 24 hours rolling (`Daily`) -- 7 days rolling (`Weekly`) -- 1 month rolling (`Monthly`) +- 24 hours (`Daily`). +- 7 days (`Weekly`). +- 1 month (`Monthly`). + +**Calendar periods** (specify start time and day): + +- Daily: Resets every day at a specified hour (0-23). +- Weekly: Resets on a specified day of the week at a specified hour. +- Monthly: Resets on a specified day of the month (1-31) at a specified hour. + +:::warning Compatibility +Each spending limit must be either rolling or calendar. You can't combine both period types on the same card. +::: ### Hour-level aggregation {#hour-level-aggregation} -Aggregate spending limits track the total amount spent within a rolling period. +Aggregate spending limits track the total amount spent within a defined period. Each new payment is added to the total spending for the defined period. -Swan computes these limits at the **hour level** for all cards with `daily`, `weekly` and `monthly` limits, ensuring more precise and consistent rolling period calculations. +Swan computes these limits at the **hour level** for all cards with `Daily`, `Weekly`, and `Monthly` limits (both rolling and calendar periods), ensuring more precise and consistent period calculations. :::info Hour-level aggregation impact Only spending limit calculations are affected; actual transaction timestamps and records remain unchanged. @@ -262,11 +283,11 @@ When a payment is processed, it's **rounded down** to the start of the hour (HH: #### Affected spending limit periods {#affected-spending-limit-periods} -Payments are timestamped to the hour for the following limit periods: +Payments are timestamped to the hour for the following periods (both rolling and calendar): -- 24 hours rolling (`Daily`) -- 7 days rolling (`Weekly`) -- 1 month rolling (`Monthly`) +- 24 hours (`Daily`) +- 7 days (`Weekly`) +- 1 month (`Monthly`) :::info Other limits Lifetime (`Always`) limits and **Swan-imposed** spending limits aren't impacted. diff --git a/docs/topics/cards/overview/guide-update.mdx b/docs/topics/cards/overview/guide-update.mdx index 5776b23cd58..e975074c794 100644 --- a/docs/topics/cards/overview/guide-update.mdx +++ b/docs/topics/cards/overview/guide-update.mdx @@ -27,6 +27,11 @@ import SuspicionOfFraud from '../../partials/_card-fraud-suspicion.mdx'; +### Spending limit updates {#spending-limit-updates} + +You can update spending limits with the `updateCard` mutation, including switching between [rolling and calendar periods](../index.mdx#limits-periods). +Use the `spendingLimit` field to set the period, amount, and mode. + ### Mutation {#mutation} Open in API Explorer diff --git a/docs/topics/cards/virtual/guide-add.mdx b/docs/topics/cards/virtual/guide-add.mdx index 960078ac904..f5a4d23b621 100644 --- a/docs/topics/cards/virtual/guide-add.mdx +++ b/docs/topics/cards/virtual/guide-add.mdx @@ -102,6 +102,69 @@ The cards are created asynchronously and then change to the `Enabled` status. Depending on how many cards you're creating, it can take up to several minutes to complete the process. For performance reasons, you can create up to **250 cards** per API call. +### Spending limit configuration {#spending-limit-config} + +When configuring the `spendingLimit` field, you can choose between [rolling and calendar periods](../index.mdx#limits-periods). + +Use the `mode` field to specify whether the limit follows a rolling period or resets on a calendar schedule. +If you don't specify a mode, the limit defaults to rolling. + +The following example sets a calendar-based monthly limit that resets on the 1st of each month at midnight (hour 0): + +```graphql {12-18} showLineNumbers +mutation AddCardsWithCalendarLimit { + addCards( + input: { + cards: [ + { + accountMembershipId: "$YOUR_ACCOUNT_MEMBERSHIP_ID" + withdrawal: true + international: true + nonMainCurrencyTransactions: true + eCommerce: true + spendingLimit: { + period: Monthly + amount: { value: "1000", currency: "EUR" } + mode: { + calendar: { + monthly: { startDay: 1, startHour: 0 } + } + } + } + } + ] + consentRedirectUrl: "$YOUR_REDIRECT_URL" + } + ) { + ... on AddCardsSuccessPayload { + __typename + cards { + id + spendingLimits { + period + amount { + value + currency + } + } + } + } + } +} +``` + +For a rolling period, you can either omit the `mode` field entirely (defaults to rolling) or specify it explicitly: + +```graphql {5-7} showLineNumbers +spendingLimit: { + period: Weekly + amount: { value: "500", currency: "EUR" } + mode: { + rolling: { rollingValue: 1 } + } +} +``` + ## Print physical cards when adding virtual cards {#print-with-virtual} Please refer to the guides in the **physical cards section** to learn more about creating virtual and physical cards at the same time. From 2a45c009a5296f889bc7ab06630c4aa50db32d05 Mon Sep 17 00:00:00 2001 From: Maxence Busson Date: Fri, 6 Mar 2026 08:23:32 +0100 Subject: [PATCH 2/2] Update index.mdx --- docs/topics/cards/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/topics/cards/index.mdx b/docs/topics/cards/index.mdx index 2795dffa35e..c1893182c83 100644 --- a/docs/topics/cards/index.mdx +++ b/docs/topics/cards/index.mdx @@ -175,8 +175,8 @@ Rolling is the default period type and is best suited for continuous fraud prote Calendar periods are best suited for budgeting cycles, expense management, or when spending needs to align with payroll or billing schedules. :::info Non-existent dates -If a calendar period's reset date doesn't exist in a given month, the limit resets on the next available day. -For example, if you set a monthly limit to reset on the 31st, the limit resets on March 1st in February (since February doesn't have a 31st). +If a calendar period's reset date doesn't exist in a given month, the limit resets on the closest available day in the same month. +For example, if you set a monthly limit to reset on the 31st of February, the limit resets on the 28th of February (since February doesn't have a 31st). ::: ### Limits imposed by Swan {#limits-swan}