> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Update card account activity

> Required API-key scope: `card_activities:write`.

Changes the note, the transaction category, or both on a card transaction. Fields you leave out don't change.

| To | Send |
| --- | --- |
| Set or change the note | `{ "note": "PO-1042" }` |
| Clear the note | `{ "note": null }` |
| Change the category | `{ "categoryId": "<category id>" }` |
| Change both | `{ "note": "PO-1042", "categoryId": "<category id>" }` |

- Only card transactions (`type: CHARGE`) can be updated, including refunds.
- Sending the same values again returns `200` and changes nothing, so retries are safe.
- `card_activities:write` doesn't include read access. Listing activities and categories needs their own scopes.

| Error | When |
| --- | --- |
| `ACTIVITY_NO_CHARGE` | The activity isn't a card transaction. |
| `ACTIVITY_CARD_TERMINATED` | The card is terminated. |
| `TRANSACTION_CATEGORY_NOT_FOUND` | `categoryId` isn't a transaction category in this environment. |
| `CATEGORY_NOT_APPLIED` | The category wasn't saved. A note sent with it may be saved, so list the activity to check. |
| `NOTE_NOT_APPLIED` | The note wasn't saved. A category sent with it may be saved, so list the activity to check. |
| `404` | The activity doesn't exist or is voided. |

See [Activities](/concepts/activities).



## OpenAPI

````yaml /openapi/2026-07-13.json patch /2026-07-13/cards/activities/{activityId}
openapi: 3.1.0
info:
  title: Reap Business Account API
  description: >

    # Introduction


    The Reap Business Account API lets you manage cards, spend and Treasury

    funding for your Business Account from your own systems. Every endpoint is

    authenticated with an API key sent in the `x-api-key` header and versioned

    with a date in the URL (`/2026-07-13/...`).


    Guides, concepts and the full setup reference live on the docs site:

    [direct-api.reap.global](https://direct-api.reap.global).



    ## Errors


    All errors share a single JSON envelope:


    ```json

    {
      "statusCode": 400,
      "type": "INVALID_REQUEST_ERROR",
      "code": "SPEND_CAP_TOO_LOW",
      "message": "Spend cap cannot be lower than the amount already spent on this card.",
      "param": "spendCap",
      "requestId": "01H..."
    }

    ```


    - `statusCode`: HTTP status, duplicated in the body.

    - `type`: coarse category, **always present**. Branch on this for
    retry/re-auth decisions.

    - `code`: stable, machine-readable identifier. Present only for
    programmatically-actionable errors.

    - `message`: human-readable explanation, safe to surface to users.

    - `param`: offending field for validation errors (optional).

    - `details`: structured extra context such as validation issues or required
    API-key scopes (optional).

    - `requestId`: correlation id; include it when contacting support
    (optional).


    The specific error codes each endpoint can return are documented on that

    endpoint's responses below.


    ### Error types


    | Type | Description |

    | --- | --- |

    | `INVALID_REQUEST_ERROR` | The request was rejected due to invalid input, a
    missing resource, or a business-rule violation (HTTP 400/404/409/422). |

    | `AUTHENTICATION_ERROR` | Authentication is missing or invalid (HTTP 401).
    |

    | `PERMISSION_ERROR` | The caller is authenticated but not permitted to
    perform the action (HTTP 403). |

    | `RATE_LIMIT_ERROR` | Too many requests; retry after a delay (HTTP 429). |

    | `API_ERROR` | An unexpected error occurred on our side (HTTP 5xx). |

    | `UPSTREAM_ERROR` | An upstream service returned an error (HTTP 502/503). |
  version: '2026-07-13'
  contact: {}
servers:
  - url: https://api.global.direct.reap.global
security: []
tags: []
paths:
  /2026-07-13/cards/activities/{activityId}:
    patch:
      tags:
        - Cards
      summary: Update card account activity
      description: >-
        Required API-key scope: `card_activities:write`.


        Changes the note, the transaction category, or both on a card
        transaction. Fields you leave out don't change.


        | To | Send |

        | --- | --- |

        | Set or change the note | `{ "note": "PO-1042" }` |

        | Clear the note | `{ "note": null }` |

        | Change the category | `{ "categoryId": "<category id>" }` |

        | Change both | `{ "note": "PO-1042", "categoryId": "<category id>" }` |


        - Only card transactions (`type: CHARGE`) can be updated, including
        refunds.

        - Sending the same values again returns `200` and changes nothing, so
        retries are safe.

        - `card_activities:write` doesn't include read access. Listing
        activities and categories needs their own scopes.


        | Error | When |

        | --- | --- |

        | `ACTIVITY_NO_CHARGE` | The activity isn't a card transaction. |

        | `ACTIVITY_CARD_TERMINATED` | The card is terminated. |

        | `TRANSACTION_CATEGORY_NOT_FOUND` | `categoryId` isn't a transaction
        category in this environment. |

        | `CATEGORY_NOT_APPLIED` | The category wasn't saved. A note sent with
        it may be saved, so list the activity to check. |

        | `NOTE_NOT_APPLIED` | The note wasn't saved. A category sent with it
        may be saved, so list the activity to check. |

        | `404` | The activity doesn't exist or is voided. |


        See [Activities](/concepts/activities).
      operationId: updateActivity
      parameters:
        - name: activityId
          required: true
          in: path
          description: >-
            The activity's `id`, as returned by [List card account
            activities](/api-reference/cards/list-card-account-activities).
          schema:
            type: string
            minLength: 1
            maxLength: 255
            description: >-
              The activity's `id`, as returned by [List card account
              activities](/api-reference/cards/list-card-account-activities).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateActivity'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
              examples:
                activity:
                  summary: Updated activity
                  value:
                    id: txn_00000000-0000-0000-0000-00000000f001
                    chargeId: tid_0uWewrFOTL
                    type: CHARGE
                    status: CLEARED
                    declineReason: null
                    createdAt: '2026-07-13T08:00:00.000Z'
                    clearedAt: '2026-07-14T08:00:00.000Z'
                    isCredit: false
                    billAmount:
                      amount: '100.00'
                      currency: USD
                    transactionAmount:
                      amount: '100.00'
                      currency: USD
                    conversionRate: '1'
                    merchant: Example merchant
                    card:
                      id: 3db05d6f-97a9-4c06-a578-087b14b4f859
                      title: Travel card
                      last4: '4242'
                    category:
                      id: d022bf27-0f9c-457a-a06f-d8e301f6944b
                      name: Travel
                    note: Campaign 4471 – Meta ads, PO-20431
                    hasReceipt: false
        '400':
          description: '`BAD_REQUEST`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BAD_REQUEST:
                  summary: BAD_REQUEST
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    message: Bad request.
        '401':
          description: '`UNAUTHORIZED`, `AUTH_CREDENTIAL_MISSING`, `API_KEY_INVALID`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UNAUTHORIZED:
                  summary: UNAUTHORIZED
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    message: Authentication required.
                AUTH_CREDENTIAL_MISSING:
                  summary: AUTH_CREDENTIAL_MISSING
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: AUTH_CREDENTIAL_MISSING
                    message: Authentication is required.
                API_KEY_INVALID:
                  summary: API_KEY_INVALID
                  value:
                    statusCode: 401
                    type: AUTHENTICATION_ERROR
                    code: API_KEY_INVALID
                    message: API key is invalid.
        '403':
          description: >-
            `FORBIDDEN`, `API_KEY_IP_NOT_ALLOWED`,
            `AUTH_INSUFFICIENT_PERMISSIONS`, `AUTH_METHOD_NOT_ALLOWED`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FORBIDDEN:
                  summary: FORBIDDEN
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    message: You do not have permission to perform this action.
                API_KEY_IP_NOT_ALLOWED:
                  summary: API_KEY_IP_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: API_KEY_IP_NOT_ALLOWED
                    message: Request IP is not allowed for this API key.
                AUTH_INSUFFICIENT_PERMISSIONS:
                  summary: AUTH_INSUFFICIENT_PERMISSIONS
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_INSUFFICIENT_PERMISSIONS
                    message: Insufficient permissions.
                    details:
                      requiredScopes:
                        - <required-scope>
                AUTH_METHOD_NOT_ALLOWED:
                  summary: AUTH_METHOD_NOT_ALLOWED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: AUTH_METHOD_NOT_ALLOWED
                    message: >-
                      This endpoint does not accept the credential type
                      provided.
        '404':
          description: '`NOT_FOUND`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NOT_FOUND:
                  summary: NOT_FOUND
                  value:
                    statusCode: 404
                    type: INVALID_REQUEST_ERROR
                    message: The requested resource was not found.
        '422':
          description: >-
            `ACTIVITY_NO_CHARGE`, `ACTIVITY_CARD_TERMINATED`,
            `TRANSACTION_CATEGORY_NOT_FOUND`, `CATEGORY_NOT_APPLIED`,
            `NOTE_NOT_APPLIED`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ACTIVITY_NO_CHARGE:
                  summary: ACTIVITY_NO_CHARGE
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: ACTIVITY_NO_CHARGE
                    message: This activity has no associated charge.
                ACTIVITY_CARD_TERMINATED:
                  summary: ACTIVITY_CARD_TERMINATED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: ACTIVITY_CARD_TERMINATED
                    message: This action is unavailable for a terminated card.
                TRANSACTION_CATEGORY_NOT_FOUND:
                  summary: TRANSACTION_CATEGORY_NOT_FOUND
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: TRANSACTION_CATEGORY_NOT_FOUND
                    message: >-
                      Transaction category not found. List transaction
                      categories to get valid IDs for this environment.
                CATEGORY_NOT_APPLIED:
                  summary: CATEGORY_NOT_APPLIED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: CATEGORY_NOT_APPLIED
                    message: >-
                      The category was not applied to this transaction. Contact
                      support if this keeps happening.
                NOTE_NOT_APPLIED:
                  summary: NOTE_NOT_APPLIED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: NOTE_NOT_APPLIED
                    message: >-
                      The note was not saved to this transaction. Contact
                      support if this keeps happening.
        '429':
          description: '`API_KEY_RATE_LIMITED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                API_KEY_RATE_LIMITED:
                  summary: API_KEY_RATE_LIMITED
                  value:
                    statusCode: 429
                    type: RATE_LIMIT_ERROR
                    code: API_KEY_RATE_LIMITED
                    message: API key rate limit exceeded.
        '500':
          description: '`INTERNAL_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                INTERNAL_ERROR:
                  summary: INTERNAL_ERROR
                  value:
                    statusCode: 500
                    type: API_ERROR
                    message: An unexpected error occurred.
        '504':
          description: '`UPSTREAM_TIMEOUT`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_TIMEOUT:
                  summary: UPSTREAM_TIMEOUT
                  value:
                    statusCode: 504
                    type: UPSTREAM_ERROR
                    code: UPSTREAM_TIMEOUT
                    message: >-
                      An upstream service did not respond in time. If this
                      request changes data, it may still have been applied, so
                      fetch the resource before you retry.
      security:
        - apiKey: []
components:
  schemas:
    UpdateActivity:
      type: object
      properties:
        note:
          description: >-
            The note, for example a PO number. Spaces at the start and end are
            removed, then it must be 1 to 500 characters. Send `null` to clear
            it.
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 500
        categoryId:
          type: string
          format: uuid
          pattern: >-
            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
          description: >-
            An `id` from [List transaction
            categories](/concepts/activities#transaction-categories). IDs differ
            between environments. You can't clear a category.
      additionalProperties: false
      minProperties: 1
    Activity:
      type: object
      properties:
        id:
          type: string
          description: Reap's unique ID for this activity.
        chargeId:
          description: >-
            The transaction ID (TID) of a card transaction, the same one shown
            in the dashboard. Give it to Reap Support when asking about a card
            transaction. Null for other activity types.
          type:
            - string
            - 'null'
        type:
          type: string
          enum:
            - CHARGE
            - REPAYMENT
            - ADJUSTMENT
            - REBATE
            - INTEREST
          description: >-
            What kind of activity this is: `CHARGE` (a card transaction),
            `REPAYMENT` (a repayment of your card balance), `ADJUSTMENT` (a
            correction made by Reap), `REBATE` (a rebate credited to your card
            account) or `INTEREST` (interest charged on an unpaid balance).
        status:
          description: >-
            Where a card transaction is in its lifecycle: `PENDING` (authorised,
            not yet settled by the merchant), `CLEARED` (settled), `DECLINED`
            (not approved) or `VOIDED` (cancelled before settling). Null for
            other activity types.
          type:
            - string
            - 'null'
          enum:
            - PENDING
            - CLEARED
            - DECLINED
            - VOIDED
            - null
        declineReason:
          description: >-
            Why a card transaction was declined. Null for card transactions that
            weren't declined and for other activity types.
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              description: The decline code, for example `51` for insufficient balance.
            description:
              type: string
              description: >-
                A plain-English explanation of the decline, which you can show
                to the cardholder.
          required:
            - code
            - description
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
          description: When the activity happened, in UTC.
        clearedAt:
          description: >-
            When a card transaction settled, in UTC. Null while it's still
            pending, or if it never settles.
          type:
            - string
            - 'null'
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        isCredit:
          description: >-
            `true` when funds come back to the card account (such as a refund,
            repayment or rebate), and `false` when they go out.
          type:
            - boolean
            - 'null'
        billAmount:
          description: >-
            The amount applied to your card account, in your card's currency
            (`USD` or `HKD`). Use this for accounting and reconciliation.
          type:
            - object
            - 'null'
          properties:
            amount:
              type: string
              description: The amount as a string with two decimals, for example `100.00`.
            currency:
              type: string
              description: The three-letter currency code, for example `USD`.
          required:
            - amount
            - currency
        transactionAmount:
          description: >-
            The amount in the merchant's own currency. It differs from
            `billAmount` when the merchant charges in another currency.
          type:
            - object
            - 'null'
          properties:
            amount:
              type: string
              description: The amount as a string with two decimals, for example `100.00`.
            currency:
              type: string
              description: The three-letter currency code, for example `USD`.
          required:
            - amount
            - currency
        conversionRate:
          description: >-
            The exchange rate used to convert `transactionAmount` into
            `billAmount`, as a string. It's `1` when both are in the same
            currency.
          type:
            - string
            - 'null'
        merchant:
          description: The merchant's name as it appears on the card transaction.
          type:
            - string
            - 'null'
        card:
          description: >-
            The card the activity happened on. Null for activity that isn't tied
            to a card, such as a repayment.
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              description: >-
                The card's ID, which you can use with [Retrieve a
                card](/api-reference/cards/retrieve-a-card) and the other card
                endpoints.
            title:
              description: The card's nickname, for example `Ada – Marketing tools`.
              type:
                - string
                - 'null'
            last4:
              description: >-
                The last four digits of the card number. To see the full card
                details, use [Reveal card
                details](/api-reference/cards/reveal-card-details).
              type:
                - string
                - 'null'
          required:
            - id
            - title
            - last4
        category:
          description: >-
            The card transaction's transaction category, mapped automatically by
            Reap from the card network's merchant data, or corrected by your
            team. Null if it hasn't been categorised yet.
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
              description: >-
                The transaction category's ID, which you can use as the
                `categoryId` filter.
            name:
              type: string
              description: The transaction category's display name, for example `Travel`.
          required:
            - id
            - name
        note:
          description: >-
            A free-text note your team added to the card transaction in the
            dashboard or through [Update card account
            activity](/api-reference/cards/update-card-account-activity). Null
            if there is none.
          type:
            - string
            - 'null'
        hasReceipt:
          type: boolean
          description: Whether a receipt has been attached to this card transaction.
      required:
        - id
        - chargeId
        - type
        - status
        - declineReason
        - createdAt
        - clearedAt
        - isCredit
        - billAmount
        - transactionAmount
        - conversionRate
        - merchant
        - card
        - category
        - note
        - hasReceipt
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          minimum: 100
          maximum: 599
          description: The HTTP status code, repeated in the body for convenience.
        type:
          type: string
          enum:
            - INVALID_REQUEST_ERROR
            - AUTHENTICATION_ERROR
            - PERMISSION_ERROR
            - RATE_LIMIT_ERROR
            - API_ERROR
            - UPSTREAM_ERROR
          description: >-
            The broad kind of error, for example `RATE_LIMIT_ERROR`. It's always
            present: use it to decide whether to retry, re-authenticate or fix
            the request.
        code:
          description: >-
            A stable, machine-readable error code, for example
            `CARD_CREATION_REQUIRES_DEPOSIT`. It's present when there's a
            specific action you can take, and each endpoint lists the codes it
            can return.
          type: string
        message:
          type: string
          description: >-
            A plain-English explanation of the error that's safe to show to your
            users.
        param:
          description: >-
            The request field that caused a validation error, for example
            `spendCap`.
          type: string
        details:
          description: >-
            Extra structured information, such as the list of validation issues
            or the API-key scopes your key is missing.
        requestId:
          description: >-
            A unique ID for this request. Include it when you contact Reap
            Support so the team can find it.
          type: string
      required:
        - statusCode
        - type
        - message
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Enter your API key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.