diff --git a/docs/topics/cards/index.mdx b/docs/topics/cards/index.mdx
index 64ea948d2e..2795dffa35 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 5776b23cd5..e975074c79 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 960078ac90..f5a4d23b62 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.