> ## 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.

# Attach a receipt to a card account activity

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

Attaches an uploaded file to a card transaction as a receipt.

**Before you attach**

- Upload the file with [Upload a file](/api-reference/files/upload-a-file) and wait until its `status` is `ready`.
- Attach it within 24 hours of the upload.

**Limits**

- A card transaction holds up to 3 receipts.
- Each file can be attached once, even after you delete its receipt. To attach it again, upload it again.

**Retries**

Send an `Idempotency-Key` header. If you get a `502` or `ATTACH_IN_PROGRESS`, send the same request again every minute, for up to 10 minutes. It never creates a second receipt.

| Error | When |
| --- | --- |
| `FILE_NOT_READY` | The file is still being scanned. |
| `FILE_BLOCKED` | The scan blocked the file or failed. Upload a different file. |
| `FILE_NOT_FOUND` | The file doesn't exist, has expired or belongs to another business. |
| `FILE_ALREADY_ATTACHED` | The file is already attached. `details.receiptId` has the receipt. |
| `RECEIPT_LIMIT_REACHED` | The transaction already has 3 receipts. |
| `ACTIVITY_NO_CHARGE` | The activity isn't a card transaction. |
| `ACTIVITY_CARD_TERMINATED` | The card is terminated. |
| `FEATURE_NOT_ENABLED` | Receipts aren't enabled for your business. |
| `404` | The activity doesn't exist or is voided. |

See [Attach receipts to card transactions](/guides/attach-receipts-to-card-transactions).



## OpenAPI

````yaml /openapi/2026-11-16.json post /2026-11-16/cards/activities/{activityId}/receipts
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-11-16/...`).


    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-11-16'
  contact: {}
servers:
  - url: https://api.global.direct.reap.global
security: []
tags: []
paths:
  /2026-11-16/cards/activities/{activityId}/receipts:
    post:
      tags:
        - Cards
      summary: Attach a receipt to a card account activity
      description: >-
        Required API-key scope: `card_activities:write`.


        Attaches an uploaded file to a card transaction as a receipt.


        **Before you attach**


        - Upload the file with [Upload a
        file](/api-reference/files/upload-a-file) and wait until its `status` is
        `ready`.

        - Attach it within 24 hours of the upload.


        **Limits**


        - A card transaction holds up to 3 receipts.

        - Each file can be attached once, even after you delete its receipt. To
        attach it again, upload it again.


        **Retries**


        Send an `Idempotency-Key` header. If you get a `502` or
        `ATTACH_IN_PROGRESS`, send the same request again every minute, for up
        to 10 minutes. It never creates a second receipt.


        | Error | When |

        | --- | --- |

        | `FILE_NOT_READY` | The file is still being scanned. |

        | `FILE_BLOCKED` | The scan blocked the file or failed. Upload a
        different file. |

        | `FILE_NOT_FOUND` | The file doesn't exist, has expired or belongs to
        another business. |

        | `FILE_ALREADY_ATTACHED` | The file is already attached.
        `details.receiptId` has the receipt. |

        | `RECEIPT_LIMIT_REACHED` | The transaction already has 3 receipts. |

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

        | `ACTIVITY_CARD_TERMINATED` | The card is terminated. |

        | `FEATURE_NOT_ENABLED` | Receipts aren't enabled for your business. |

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


        See [Attach receipts to card
        transactions](/guides/attach-receipts-to-card-transactions).
      operationId: attachCardActivityReceipt
      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).
        - name: Idempotency-Key
          in: header
          description: >-
            A unique value for this attach, for example
            `attach-{activityId}-{fileId}`. Sending the same key and body again
            returns the first result. Reusing the key with a different body
            returns `IDEMPOTENCY_KEY_REUSED`.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttachReceipt'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Receipt'
              examples:
                attached:
                  summary: Receipt attached
                  value:
                    id: 0a0a0a0a-0000-4000-8000-000000000001
                    activityId: txn_00000000-0000-0000-0000-00000000f001
                    fileName: invoice-INV-20431.pdf
                    contentType: application/pdf
                    createdAt: '2026-10-29T01:02:03.000Z'
        '400':
          description: '`FILE_NOT_READY`, `FILE_BLOCKED`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BAD_REQUEST:
                  summary: BAD_REQUEST
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    message: Bad request.
                FILE_NOT_READY:
                  summary: FILE_NOT_READY
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    code: FILE_NOT_READY
                    message: >-
                      The file is still being checked. Get the file until its
                      status is ready, then try again.
                FILE_BLOCKED:
                  summary: FILE_BLOCKED
                  value:
                    statusCode: 400
                    type: INVALID_REQUEST_ERROR
                    code: FILE_BLOCKED
                    message: >-
                      The file can't be used because its malware scan blocked it
                      or failed. Upload a different file.
        '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: '`FEATURE_NOT_ENABLED`'
          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.
                FEATURE_NOT_ENABLED:
                  summary: FEATURE_NOT_ENABLED
                  value:
                    statusCode: 403
                    type: PERMISSION_ERROR
                    code: FEATURE_NOT_ENABLED
                    message: This feature is not enabled for your account.
        '404':
          description: '`NOT_FOUND`, `FILE_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.
                FILE_NOT_FOUND:
                  summary: FILE_NOT_FOUND
                  value:
                    statusCode: 404
                    type: INVALID_REQUEST_ERROR
                    code: FILE_NOT_FOUND
                    message: A file is no longer available. Upload it again.
        '409':
          description: >-
            `FILE_ALREADY_ATTACHED`, `ATTACH_IN_PROGRESS`,
            `IDEMPOTENCY_KEY_IN_FLIGHT`, `IDEMPOTENCY_KEY_OUTCOME_UNKNOWN`
          headers:
            Retry-After:
              description: >-
                Sent with `ATTACH_IN_PROGRESS`: the number of seconds to wait
                before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                FILE_ALREADY_ATTACHED:
                  summary: FILE_ALREADY_ATTACHED
                  value:
                    statusCode: 409
                    type: INVALID_REQUEST_ERROR
                    code: FILE_ALREADY_ATTACHED
                    message: This file is already attached as a receipt.
                ATTACH_IN_PROGRESS:
                  summary: ATTACH_IN_PROGRESS
                  value:
                    statusCode: 409
                    type: INVALID_REQUEST_ERROR
                    code: ATTACH_IN_PROGRESS
                    message: >-
                      An earlier attempt to attach this file may still be
                      running. Send the same request again every minute, for up
                      to 10 minutes.
                IDEMPOTENCY_KEY_IN_FLIGHT:
                  summary: IDEMPOTENCY_KEY_IN_FLIGHT
                  value:
                    statusCode: 409
                    type: INVALID_REQUEST_ERROR
                    code: IDEMPOTENCY_KEY_IN_FLIGHT
                    message: >-
                      A request with this Idempotency-Key is still being
                      processed. Retry shortly.
                IDEMPOTENCY_KEY_OUTCOME_UNKNOWN:
                  summary: IDEMPOTENCY_KEY_OUTCOME_UNKNOWN
                  value:
                    statusCode: 409
                    type: INVALID_REQUEST_ERROR
                    code: IDEMPOTENCY_KEY_OUTCOME_UNKNOWN
                    message: >-
                      The first request with this Idempotency-Key may have
                      completed. Check its outcome before you retry with a new
                      Idempotency-Key.
        '422':
          description: >-
            `ACTIVITY_NO_CHARGE`, `ACTIVITY_CARD_TERMINATED`,
            `RECEIPT_LIMIT_REACHED`, `IDEMPOTENCY_KEY_REUSED`
          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.
                RECEIPT_LIMIT_REACHED:
                  summary: RECEIPT_LIMIT_REACHED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: RECEIPT_LIMIT_REACHED
                    message: >-
                      This card transaction already has 3 receipts. Delete one
                      before you attach another.
                IDEMPOTENCY_KEY_REUSED:
                  summary: IDEMPOTENCY_KEY_REUSED
                  value:
                    statusCode: 422
                    type: INVALID_REQUEST_ERROR
                    code: IDEMPOTENCY_KEY_REUSED
                    message: >-
                      This Idempotency-Key was already used with a different
                      request body.
        '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.
        '502':
          description: '`UPSTREAM_ERROR`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UPSTREAM_ERROR:
                  summary: UPSTREAM_ERROR
                  value:
                    statusCode: 502
                    type: UPSTREAM_ERROR
                    message: >-
                      An error occurred while communicating with an upstream
                      service.
        '503':
          description: '`SERVICE_UNAVAILABLE`, `IDEMPOTENCY_UNAVAILABLE`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                SERVICE_UNAVAILABLE:
                  summary: SERVICE_UNAVAILABLE
                  value:
                    statusCode: 503
                    type: UPSTREAM_ERROR
                    message: The service is temporarily unavailable.
                IDEMPOTENCY_UNAVAILABLE:
                  summary: IDEMPOTENCY_UNAVAILABLE
                  value:
                    statusCode: 503
                    type: API_ERROR
                    code: IDEMPOTENCY_UNAVAILABLE
                    message: >-
                      The idempotent request outcome could not be safely
                      determined.
        '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:
    AttachReceipt:
      type: object
      properties:
        fileId:
          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: >-
            The `id` of a file you uploaded with [Upload a
            file](/api-reference/files/upload-a-file). Its status must be
            `ready`.
      required:
        - fileId
      additionalProperties: false
    Receipt:
      type: object
      properties:
        id:
          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: >-
            The receipt ID. Use it to retrieve or delete the receipt on this
            card transaction.
        activityId:
          type: string
          description: The `id` of the card transaction the receipt is attached to.
        fileName:
          type: string
          description: The file name. Spaces are replaced with `_`.
        contentType:
          type: string
          description: The file type, for example `application/pdf`.
        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 receipt was added to the card transaction, in UTC.
      required:
        - id
        - activityId
        - fileName
        - contentType
        - createdAt
    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.