# Apply credit to invoice

Apply credit memo amount to an invoice.

## What happens

- Creates credit application record
- Reduces credit memo remaining balance
- Reduces invoice open balance
- Updates order status if invoice is fully paid

## Constraints

- Amount must not exceed remaining balance
- Invoice must belong to same customer
- Invoice must have outstanding balance
- Currency must match

Endpoint: POST /credit-memos/{id}/apply
Version: 1.0.0
Security: BearerAuth

## Path parameters:

  - `id` (string, required)
    Resource ID (UUID) or client key
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Query parameters:

  - `by` (string)
    Specify lookup type for faster retrieval.
If omitted, defaults to looking up by ID first, then falls back to client key if not found.
Use by=key when you know you're providing a client key for best performance.
    Enum: "id", "key"

## Request fields (application/json):

  - `invoiceId` (string, required)
    Invoice to apply credit to

  - `amount` (number, required)
    Amount to apply

## Response 200 fields (application/json):

  - `application` (object, required)

  - `application.id` (string, required)

  - `application.invoiceId` (string, required)

  - `application.invoiceFriendlyId` (string,null)

  - `application.paymentId` (string)
    Payment through which this credit was applied

  - `application.paymentKey` (string,null)

  - `application.amount` (number, required)
    Amount applied

  - `application.appliedAt` (string)

  - `creditMemo` (object, required)

  - `creditMemo.key` (string,null)
    Client-defined key

  - `creditMemo.reference` (string,null)
    Reference number
    Example: "CM-00001"

  - `creditMemo.customer` (object)
    Enhanced reference to a customer resource (returned in responses).
Includes full customer details in addition to id/key.

Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `creditMemo.customer.id` (string, required)
    Customer UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `creditMemo.customer.key` (string,null)
    Client-defined reference ID if set
    Example: "ERP-CUSTOMER-ACME"

  - `creditMemo.customer.name` (string, required)
    Customer company name
    Example: "Acme Manufacturing Corp"

  - `creditMemo.customer.friendlyId` (string, required)
    Human-readable customer identifier
    Example: "A123456"

  - `creditMemo.customer.status` (string, required)
    Customer status
    Enum: "PROSPECT", "ACTIVE", "INACTIVE", "CHURNED"

  - `creditMemo.customer.phoneNumber` (string,null)
    Primary phone number
    Example: "+1-555-123-4567"

  - `creditMemo.customer.website` (string,null)
    Customer website URL
    Example: "https://acme-manufacturing.com"

  - `creditMemo.customer.createdAt` (string, required)
    When the customer was created
    Example: "2025-01-15T10:00:00Z"

  - `creditMemo.customer.updatedAt` (string, required)
    When the customer was last updated
    Example: "2025-01-15T14:30:00Z"

  - `creditMemo.customer.deletedAt` (string,null)
    When the customer was soft deleted (null if active)

  - `creditMemo.amount` (number, required)
    Original credit amount

  - `creditMemo.appliedAmount` (number)
    Total amount applied to invoices

  - `creditMemo.remainingBalance` (number, required)
    Available balance

  - `creditMemo.currency` (string,null)
    Currency code
    Example: "USD"

  - `creditMemo.status` (string, required)
    Current status of the credit memo (derived from remaining balance).
- OPEN: No applications, full balance available
- PARTIALLY_APPLIED: Some amount applied, balance remains
- APPLIED: Fully applied to invoices
- VOIDED: Credit memo cancelled
    Enum: "OPEN", "PARTIALLY_APPLIED", "APPLIED", "VOIDED"

  - `creditMemo.memoDate` (string, required)
    Credit memo date

  - `creditMemo.notes` (string,null)
    Notes or description

  - `creditMemo.sourcePaymentGroupId` (string,null)
    Payment that created this credit (if from overpayment)

  - `creditMemo.sourcePaymentKey` (string,null)

  - `creditMemo.applications` (array)
    Invoices this credit is applied to

  - `creditMemo.qboId` (string,null)
    QuickBooks Online credit memo ID

  - `creditMemo.createdAt` (string, required)

  - `creditMemo.updatedAt` (string,null)

  - `creditMemo.voidedAt` (string,null)

  - `creditMemo.voidReason` (string,null)

  - `creditMemo.createdBy` (object)
    Enhanced reference to a user resource (returned in responses).
Includes full user details in addition to id/key.

Note: Does NOT include nested references (teams, etc.) to prevent recursion.
Maximum nesting depth: 1 level.

  - `creditMemo.createdBy.id` (string, required)
    User UUID
    Example: "550e8400-e29b-41d4-a716-446655440000"

  - `creditMemo.createdBy.email` (string, required)
    User's email address
    Example: "john.doe@example.com"

  - `creditMemo.createdBy.name` (string,null)
    User's full name
    Example: "John Doe"

  - `creditMemo.createdBy.phone` (string,null)
    User's phone number
    Example: "+1-555-123-4567"

  - `creditMemo.createdBy.phoneExt` (string,null)
    Phone extension
    Example: "123"

  - `creditMemo.createdBy.status` (string, required)
    User account status
    Enum: "PENDING", "ACTIVE", "INACTIVE"

  - `creditMemo.createdBy.avatarId` (string,null)
    Profile avatar document ID
    Example: "7c9e6679-7425-40de-944b-e07fc1f90ae7"

  - `creditMemo.createdBy.createdAt` (string, required)
    When the user was created
    Example: "2025-01-15T10:00:00Z"

  - `creditMemo.createdBy.updatedAt` (string, required)
    When the user was last updated
    Example: "2025-01-15T14:30:00Z"

  - `creditMemo.createdBy.deletedAt` (string,null)
    When the user was soft deleted (null if active)

## Response 400 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 401 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 404 fields (application/json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 409 fields (application/problem+json):

  - `error` (string, required)
    Error code

  - `message` (string, required)
    Human-readable error message

## Response 422 fields (application/json):

  - `error` (string, required)
    Error code
    Example: "validation_error"

  - `message` (string, required)
    Human-readable error message

  - `details` (array, required)
    Validation error details

  - `details.field` (string, required)
    Field name that failed validation

  - `details.message` (string, required)
    Validation error message