Wise spend-limits API

openapi: 3.1.0
info:
  title: Wise Platform 3ds spend-limits API
  version: ''
  description: "The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: spend-limits
  x-displayName: Spend Limits
  description: 'Manage spending limits applied to profiles and cards. Profile limits are shared across all cards under the same profile, while card limits apply to individual cards.


    For more details on how profile and card limits interact, see the [card management guide](/guides/product/issue-cards/card-management#spend-limits).

    '
paths:
  /v4/spend/profiles/{profileId}/spend-limits:
    get:
      operationId: spendLimitsProfileGet
      summary: Retrieve profile limits
      description: 'Retrieves the spend limits that are configured for a profile.

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Profile spend limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  spendLimits:
                    type: array
                    items:
                      $ref: '#/components/schemas/profile-limits'
              example:
                spendLimits:
                - type: PURCHASE
                  aggregateWindow:
                    daily:
                      value:
                        amount: 20000
                        currency: GBP
                      usage:
                        amount: 0
                        currency: GBP
                      max:
                        amount: 30000
                        currency: GBP
                      resetAt: '2023-07-31T22:59:59.999999999Z'
                    monthly:
                      value:
                        amount: 20000
                        currency: GBP
                      usage:
                        amount: 0
                        currency: GBP
                      max:
                        amount: 30000
                        currency: GBP
                      resetAt: '2023-07-31T22:59:59.999999999Z'
                - type: ATM_WITHDRAWAL
                  aggregateWindow:
                    daily:
                      value:
                        amount: 1000
                        currency: GBP
                      usage:
                        amount: 0
                        currency: GBP
                      max:
                        amount: 4000
                        currency: GBP
                      resetAt: '2023-07-31T22:59:59.999999999Z'
                    monthly:
                      value:
                        amount: 1000
                        currency: GBP
                      usage:
                        amount: 0
                        currency: GBP
                      max:
                        amount: 4000
                        currency: GBP
                      resetAt: '2023-07-31T22:59:59.999999999Z'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
    patch:
      operationId: spendLimitsProfileUpdate
      summary: Update profile limits
      description: 'Update profile daily and monthly spend limits for `PURCHASE` or `ATM_WITHDRAWAL`. Both daily and monthly must be set.

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - PURCHASE
                  - ATM_WITHDRAWAL
                  description: The type of transaction.
                aggregateWindow:
                  type: object
                  properties:
                    daily:
                      type: object
                      properties:
                        value:
                          type: object
                          description: The amount allowed to be spent daily.
                          properties:
                            amount:
                              type: number
                            currency:
                              type: string
                    monthly:
                      type: object
                      properties:
                        value:
                          type: object
                          description: The amount allowed to be spent monthly.
                          properties:
                            amount:
                              type: number
                            currency:
                              type: string
            example:
              type: PURCHASE
              aggregateWindow:
                daily:
                  value:
                    amount: 20000
                    currency: GBP
                monthly:
                  value:
                    amount: 20000
                    currency: GBP
      responses:
        '200':
          description: Updated profile spend limits. See [Retrieve profile limits](/api-reference/spend-limits/spendlimitsprofileget).
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v4/spend/profiles/{profileId}/cards/{cardToken}/spend-limits:
    get:
      operationId: spendLimitsCardGet
      summary: Retrieve card limits
      description: 'Retrieves the spend limits that are configured for a card.

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Card spend limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/card-limits'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
    patch:
      operationId: spendLimitsCardUpdate
      summary: Create or update card limits
      description: 'Create or update card transaction, daily, monthly or lifetime spend limits.

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                transaction:
                  type: object
                  properties:
                    value:
                      type: object
                      description: The amount allowed per transaction.
                      properties:
                        amount:
                          type: number
                        currency:
                          type: string
                daily:
                  type: object
                  properties:
                    value:
                      type: object
                      description: The amount allowed to be spent daily.
                      properties:
                        amount:
                          type: number
                        currency:
                          type: string
                monthly:
                  type: object
                  properties:
                    value:
                      type: object
                      description: The amount allowed to be spent monthly.
                      properties:
                        amount:
                          type: number
                        currency:
                          type: string
                lifetime:
                  type: object
                  properties:
                    value:
                      type: object
                      description: The amount allowed to be spent over the lifetime of the card.
                      properties:
                        amount:
                          type: number
                        currency:
                          type: string
            example:
              daily:
                value:
                  amount: 1000
                  currency: GBP
              monthly:
                value:
                  amount: 1000
                  currency: GBP
      responses:
        '200':
          description: Updated card spend limits. See [Retrieve card limits](/api-reference/spend-limits/spendlimitscardget).
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v4/spend/profiles/{profileId}/cards/{cardToken}/spend-limits/{granularity}:
    delete:
      operationId: spendLimitsCardDelete
      summary: Delete card limits
      description: 'Delete card spend limits for a specific granularity.

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - name: cardToken
        in: path
        required: true
        description: The card token.
        schema:
          type: string
      - name: granularity
        in: path
        required: true
        description: The limit granularity to delete.
        schema:
          type: string
          enum:
          - transaction
          - daily
          - monthly
          - lifetime
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Updated card spend limits. See [Retrieve card limits](/api-reference/spend-limits/spendlimitscardget).
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v3/spend/profiles/{profileId}/spending-limits:
    get:
      operationId: spendControlsProfileLimitsGet
      summary: Retrieve profile spend limits
      deprecated: true
      description: 'Retrieves the spending limits that are configured for a profile.


        {% admonition type="warning" %}

        This endpoint has been deprecated. Use [Retrieve profile limits](/api-reference/spend-limits/spendlimitsprofileget) instead.

        {% /admonition %}

        '
      tags:
      - spend-limits
      security:
      - UserToken: []
      parameters:
      - name: profileId
        in: path
        required: true
        description: The profile ID.
        schema:
          type: integer
          format: int64
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: Profile spending limits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  spendings:
                    type: array
                    description: A collection of spending resources.
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The spending category.
                        limits:
                          type: array
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: The type of limit. One of `TRANSACTION`, `DAILY`, `MONTHLY`, `LIFETIME`.
                              usage:
                                type: number
                                description: The amount which has been captured for the specific type and limit up till now.
                              threshold:
                                type: number
                                description: The transaction limit configured for the spending limit.
                              currency:
                                type: string
                                description: The 3-digit currency code assigned to the spending limit.
                              expiresAt:
                                type:
                                - string
                                - 'null'
                                format: date-time
                                description: The timestamp at which the spending limit will expire, ISO-8601 with timezone.
              example:
                spendings:
                - type: ATM_WITHDRAWAL
                  limits:
                  - type: TRANSACTION
                    usage: 0
                    threshold: 1750
                    currency: SGD
                    expiresAt: null
                  - type: DAILY
                    usage: 0
                    threshold: 2700
                    currency: SGD
                    expiresAt: '2022-12-15T16:00:00Z'
                  - type: MONTHLY
                    usage: 0
                    threshold: 5250
                    currency: SGD
                    expiresAt: '2022-12-31T16:00:00Z'
                - type: ECOM_PURCHASE
                  limits:
                  - type: TRANSACTION
                    usage: 0
                    threshold: 17500
                    currency: SGD
                    expiresAt: null
                  - type: DAILY
                    usage: 0
                    threshold: 17500
                    currency: SGD
                    expiresAt: '2022-12-15T16:00:00Z'
                  - type: MONTHLY
                    usage: 0
                    threshold: 35000
                    currency: SGD
                    expiresAt: '2022-12-31T16:00:00Z'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
components:
  schemas:
    profile-limits:
      title: Profile Limits
      x-tags:
      - spend-limits
      type: object
      properties:
        type:
          type: string
          enum:
          - PURCHASE
          - ATM_WITHDRAWAL
          description: 'The type of transaction. `PURCHASE` is a combined limit that applies to contactless, magnetic, online purchase, chip and PIN/mobile wallet transactions.

            '
        aggregateWindow:
          type: object
          properties:
            daily:
              type: object
              properties:
                value:
                  type: object
                  description: Daily limit. The value should be between 0 and the max allowed.
                  properties:
                    amount:
                      type: number
                      example: 20000
                    currency:
                      type: string
                      example: GBP
                usage:
                  type: object
                  description: The total authorised amount to date.
                  properties:
                    amount:
                      type: number
                      example: 0
                    currency:
                      type: string
                      example: GBP
                max:
                  type: object
                  description: The max allowed limit for [daily](https://wise.com/help/articles/2899986/what-are-my-spending-limits).
                  properties:
                    amount:
                      type: number
                      example: 30000
                    currency:
                      type: string
                      example: GBP
                resetAt:
                  type: string
                  format: date-time
                  description: The time when the limit gets reset. ISO-8601 timestamp with timezone.
                  example: '2023-07-31T22:59:59.999999999Z'
            monthly:
              type: object
              properties:
                value:
                  type: object
                  description: Monthly limit. The value should be between 0 and the max allowed.
                  properties:
                    amount:
                      type: number
                      example: 20000
                    currency:
                      type: string
                      example: GBP
                usage:
                  type: object
                  description: The total authorised amount to date.
                  properties:
                    amount:
                      type: number
                      example: 0
                    currency:
                      type: string
                      example: GBP
                max:
                  type: object
                  description: The max allowed limit for [monthly](https://wise.com/help/articles/2899986/what-are-my-spending-limits).
                  properties:
                    amount:
                      type: number
                      example: 30000
                    currency:
                      type: string
                      example: GBP
                resetAt:
                  type: string
                  format: date-time
                  description: The time when the limit gets reset. ISO-8601 timestamp with timezone.
                  example: '2023-07-31T22:59:59.999999999Z'
    card-limits:
      title: Card Limits
      x-tags:
      - spend-limits
      type: object
      properties:
        transaction:
          type:
          - object
          - 'null'
          properties:
            value:
              type: object
              description: Transaction limit.
              properties:
                amount:
                  type: number
                  example: 100
                currency:
                  type: string
                  example: GBP
            usage:
              type: object
              description: The total authorised amount. Always 0 for transaction limit.
              properties:
                amount:
                  type: number
                  example: 0
                currency:
                  type: string
                  example: GBP
            resetAt:
              type:
              - string
              - 'null'
              format: date-time
              description: The time when the limit gets reset. Null for transaction limit.
              example: null
        daily:
          type:
          - object
          - 'null'
          properties:
            value:
              type: object
              description: Daily limit.
              properties:
                amount:
                  type: number
                  example: 2000
                currency:
                  type: string
                  example: GBP
            usage:
              type: object
              description: The total authorised amount during the daily window.
              properties:
                amount:
                  type: number
                  example: 100
                currency:
                  type: string
                  example: GBP
            resetAt:
              type:
              - string
              - 'null'
              format: date-time
              description: The time when the limit gets reset. ISO-8601 timestamp with timezone.
              example: '2023-09-29T22:59:59.999999999Z'
        monthly:
          type:
          - object
          - 'null'
          properties:
            value:
              type: object
              description: Monthly limit.
              properties:
                amount:
                  type: number
                  example: 3000
                currency:
                  type: string
                  example: GBP
            usage:
              type: object
              description: The total authorised amount during the monthly window.
              properties:
                amount:
                  type: number
                  example: 100
                currency:
                  type: string
                  example: GBP
            resetAt:
              type:
              - string
              - 'null'
              format: date-time
              description: The time when the limit gets reset. ISO-8601 timestamp with timezone.
              example: '2023-09-30T22:59:59.999999999Z'
        lifetime:
          type:
          - object
          - 'null'
          properties:
            value:
              type: object
              description: Lifetime limit.
              properties:
                amount:
                  type: number
                  example: 5000
                currency:
                  type: string
                  example: GBP
            usage:
              type: object
              description: The total authorised amount over the lifetime of the card.
              properties:
                amount:
                  type: number
                  example: 100
                currency:
                  type: string
                  example: GBP
            resetAt:
              type:
              - string
              - 'null'
              format: date-time
              description: The time when the limit gets reset. Null for lifetime limit.
              example: null
  parameters:
    X-External-Correlation-Id:
      x-global: true
      name: X-External-Correlation-Id
      in: header
      required: false
      description: 'Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

        '
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
  headers:
    X-External-Correlation-Id:
      x-global: true
      description: Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    x-trace-id:
      x-global: true
      description: Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
      schema:
        type: string
      example: fba501b6d453b96789f52338f019341f
  responses:
    '429':
      x-global: true
      description: Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
          example: 5
        X-Rate-Limited-By:
          description: Identifies the rate limiter that triggered the 429 response.
          schema:
            type: string
          example: wise-public-api
        X-External-Correlation-Id:
          $ref: '#/components/headers/X-External-Correlation-Id'
        x-trace-id:
          $ref: '#/components/headers/x-trace-id'
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    UserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User Access Token for making API calls on behalf of a Wise user.


        Can be obtained via two OAuth 2.0 flows:

        - **registration_code grant**: For partners creating users via API

        - **authorization_code grant**: For partners using Wise''s authorization page


        Access tokens are valid for 12 hours and can be refreshed using a refresh token.

        '
    PersonalToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Personal API Token for individual personal or small business users.

        Generated from Wise.com > Settings > Connect and manage apps > API tokens.

        Has limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).

        '
    ClientCredentialsToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Application-level token for partner operations that don''t require a specific user context, such as bulk settlement and card spend controls.


        Obtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.


        Valid for 12 hours. No refresh token — fetch a new token when expired.


        See [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.

        '
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic Authentication using your Client ID and Client Secret as the username and password.


        Client credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.

        '
x-tagGroups:
- name: Authentication
  tags:
  - oauth-token
- name: Enhanced Security
  tags:
  - jose
- name: Users
  tags:
  - user
  - claim-account
- name: Profiles
  tags:
  - profile
  - activity
  - address
- name: Verification
  tags:
  - kyc-review
  - verification
  - facetec
- name: Strong Customer Authentication
  tags:
  - sca-ott
  - sca-sessions
  - sca-pin
  - sca-facemaps
  - sca-device-fingerprints
  - sca-otp
  - user-security
- name: Balances
  tags:
  - balance
  - balance-statement
  - bank-account-details
  - multi-currency-account
- name: Cards
  tags:
  - card
  - card-sensitive-details
  - 3ds
  - card-kiosk-collection
  - card-order
  - card-transaction
  - spend-limits
  - spend-controls
  - digital-wallet
  - disputes
- name: Quotes
  tags:
  - quote
  - rate
  - comparison
- name: Recipients
  tags:
  - recipient
  - contact
- name: Transfers
  tags:
  - transfer
  - delivery-estimate
  - currencies
  - batch-group
- name: Funding
  tags:
  - payin-deposit-detail
  - direct-debit-account
  - bulk-settlement
  - payins
- name: Webhooks
  tags:
  - webhook
  - webhook-event
- name: Simulations
  tags:
  - simulation
- name: Partner Support
  tags:
  - case