> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thredfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Vendor Credit

> Create a vendor credit note with line items and optional allocations. Supports idempotency via external_id and can create vendors on-the-fly using vendor_external_id.



## OpenAPI

````yaml POST /v1/platform/businesses/{business_id}/vendor-credits/
openapi: 3.0.3
info:
  title: Thredfi Accounting Platform API
  version: 1.0.0
  description: >-
    Comprehensive API for accounting, invoice management, open banking, and
    intelligence services.
servers: []
security: []
paths:
  /v1/platform/businesses/{business_id}/vendor-credits/:
    post:
      tags:
        - Vendor Credits
      summary: Create Vendor Credit
      description: >-
        Create a vendor credit note with line items and optional allocations.
        Supports idempotency via external_id and can create vendors on-the-fly
        using vendor_external_id.
      operationId: create_vendor_credit
      parameters:
        - in: path
          name: business_id
          schema:
            type: string
            pattern: ^[0-9a-f-]+$
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVendorCreditRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateVendorCreditRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateVendorCreditRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorCredit'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
          description: Validation errors in request data
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication required - missing or invalid API key
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Permission denied - insufficient privileges
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Conflict - resource already exists or invalid state transition
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unprocessable entity - business logic validation failed
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      security:
        - PartnerJWT: []
        - BusinessScopedJWT: []
        - BasicAuth: []
        - BearerUnscoped: []
        - BearerBusinessScoped: []
components:
  schemas:
    CreateVendorCreditRequest:
      type: object
      description: |-
        Vendor credit creation serializer with line_items support.

        Creates vendor credits with line_items for flexible account allocation.
      properties:
        external_id:
          type: string
          minLength: 1
          description: External system identifier for this vendor credit
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/VendorCreditLineItemRequest'
          description: Array of line items for this vendor credit
        vendor_id:
          type: string
          format: uuid
          description: Existing vendor ID to assign credit to
        vendor_external_id:
          type: string
          description: External vendor ID. Will create vendor if not found
        source_bill_id:
          type: string
          format: uuid
          nullable: true
          description: >-
            Optional bill ID this credit note was created from (origin tracking,
            not allocation)
        received_at:
          type: string
          format: date-time
          description: When the credit was received (ISO 8601). Defaults to now if provided
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/VendorCreditAllocationRequest'
          description: Array of bill allocations for this credit
        tags:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Transaction tags for the credit
        document:
          allOf:
            - $ref: '#/components/schemas/VendorCreditDocumentUploadRequest'
          writeOnly: true
          description: Optional document upload
      required:
        - external_id
        - line_items
    VendorCredit:
      type: object
      description: Vendor credit serializer for API responses.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique vendor credit identifier
        external_id:
          type: string
          description: >-
            Your external system identifier for this credit (used for
            idempotency)
          maxLength: 255
        status:
          type: string
          description: >-
            Credit status: draft, received, partially_applied, applied, void
            (computed from allocations)
          readOnly: true
        received_at:
          type: string
          format: date-time
          readOnly: true
          description: When the credit was received
        vendor:
          allOf:
            - $ref: '#/components/schemas/VendorEmbedded'
          readOnly: true
          description: Vendor who issued the credit (inline details)
        source_bill_id:
          type: string
          format: uuid
          readOnly: true
          nullable: true
          description: >-
            Bill ID this credit was created from (origin tracking, not
            allocation)
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/VendorCreditLineItemResponse'
          readOnly: true
          description: Array of credit line items
        allocations:
          type: array
          items:
            $ref: '#/components/schemas/VendorCreditBillAllocationResponse'
          readOnly: true
          description: Array of bill allocations
        tags:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Transaction tags for the credit
          readOnly: true
        total_amount:
          type: integer
          description: Total credit amount in cents
          readOnly: true
        applied_amount:
          type: integer
          description: Applied credit amount in cents
          readOnly: true
        currency:
          enum:
            - EUR
            - GBP
            - USD
            - SEK
            - NOK
            - DKK
            - ISK
            - MYR
            - SGD
          type: string
          x-spec-enum-id: 7e6a70e4775b3009
          description: |-
            Credit currency (e.g., GBP, EUR, USD)

            * `EUR` - Euro
            * `GBP` - British Pound
            * `USD` - US Dollar
            * `SEK` - Swedish Krona
            * `NOK` - Norwegian Krone
            * `DKK` - Danish Krone
            * `ISK` - Icelandic Króna
            * `MYR` - Malaysian Ringgit
            * `SGD` - Singapore Dollar
        document:
          allOf:
            - $ref: '#/components/schemas/DocumentFileUrl'
          readOnly: true
          description: Latest document linked to this vendor credit
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: Credit creation timestamp
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: Last update timestamp
      required:
        - allocations
        - applied_amount
        - created_at
        - document
        - id
        - line_items
        - received_at
        - source_bill_id
        - status
        - tags
        - total_amount
        - updated_at
        - vendor
    ValidationErrorResponse:
      type: object
      description: Validation error response with field-specific errors
      properties:
        error_code:
          type: string
          description: Error code (e.g., 'validation_error')
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Contains field_errors and additional context
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - detail
        - error_code
        - message
    ErrorResponse:
      type: object
      description: Standard error response format
      properties:
        error_code:
          type: string
          description: Error code for programmatic handling
        message:
          type: string
          nullable: true
          description: Human-readable error message
        detail:
          type: object
          additionalProperties: {}
          description: Additional error details including field_errors and debug info
        request_id:
          type: string
          description: Request ID for tracing
      required:
        - error_code
        - message
    VendorCreditLineItemRequest:
      type: object
      description: Serializer for vendor credit line items.
      properties:
        amount:
          type: integer
          minimum: 1
          description: Credit amount in cents for this line item
        sales_taxes:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: >-
            Tax array: [{'amount': cents}]. Sum represents tax portion of line
            amount.
        expense_account_identifier:
          nullable: true
          description: Account identifier for expense reversal posting (optional)
        memo:
          type: string
          description: Line item memo/description
        metadata:
          type: object
          additionalProperties: {}
          description: Line item metadata (max 10kb)
        reference_number:
          type: string
          description: Line item reference number
        tags:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Line item transaction tags
      required:
        - amount
    VendorCreditAllocationRequest:
      type: object
      description: Serializer for vendor credit allocations to bills.
      properties:
        amount:
          type: integer
          minimum: 1
          description: Amount to allocate to bill in cents
        bill_id:
          type: string
          format: uuid
          description: Bill ID to allocate credit to
      required:
        - amount
        - bill_id
    VendorCreditDocumentUploadRequest:
      type: object
      description: Vendor credit specific document upload payload.
      properties:
        file:
          type: string
          format: binary
          writeOnly: true
        document_type:
          type: string
          default: vendor_credit
        upload_source:
          type: string
        metadata: {}
        tags: {}
    VendorEmbedded:
      type: object
      description: Vendor details embedded in credit note and other response objects.
      properties:
        id:
          type: string
          format: uuid
          description: Vendor UUID
        external_id:
          type: string
          description: External vendor identifier
        display_name:
          type: string
          description: Vendor display name
      required:
        - display_name
        - external_id
        - id
    VendorCreditLineItemResponse:
      type: object
      description: Serializer for vendor credit line items in API responses.
      properties:
        amount:
          type: integer
          description: Credit amount in cents
          readOnly: true
        expense_account_identifier:
          allOf:
            - $ref: '#/components/schemas/AccountIdentifier'
          nullable: true
          readOnly: true
          description: Account identifier for expense reversal posting
        memo:
          type: string
        metadata: {}
        tags:
          type: array
          items:
            type: string
          description: Line item transaction tags
          readOnly: true
      required:
        - amount
        - expense_account_identifier
        - tags
    VendorCreditBillAllocationResponse:
      type: object
      description: >-
        Response serializer for vendor credit allocations to bills (for OpenAPI
        documentation).
      properties:
        bill_id:
          type: string
          format: uuid
          description: UUID of the bill this credit is allocated to
        bill_number:
          type: string
          description: Bill number (e.g., BILL-00019)
        amount_cents:
          type: integer
          description: Amount allocated to this bill in cents
        bill_outstanding_balance_cents:
          type: integer
          description: >-
            Current outstanding balance on the bill in cents (after all
            allocations)
        applied_at:
          type: string
          format: date-time
          description: When the allocation was applied
      required:
        - amount_cents
        - applied_at
        - bill_id
        - bill_number
        - bill_outstanding_balance_cents
    DocumentFileUrl:
      type: object
      description: Serializer for document file URL with metadata.
      properties:
        url:
          type: string
          format: uri
          description: Presigned URL for document download
        expires_in:
          type: integer
          description: Seconds until URL expires
        document_id:
          type: string
          format: uuid
          description: Document UUID
        file_name:
          type: string
          description: Original document filename
        file_size:
          type: integer
          description: File size in bytes
        mime_type:
          type: string
          description: MIME type of the document
      required:
        - document_id
        - expires_in
        - file_name
        - file_size
        - mime_type
        - url
    AccountIdentifier:
      type: object
      description: Standard account identifier format used across the API.
      properties:
        type:
          type: string
          default: AccountId
          description: Account identifier type (always 'AccountId')
        id:
          type: string
          format: uuid
          description: Account UUID
      required:
        - id
  securitySchemes:
    PartnerJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner-level JWT token (unscoped). Token payload includes `partner_id`.
        Business access is validated via partner ownership. Format: `Bearer
        <your-jwt-token>`


        **Use this for**: Multi-business operations where the business_id is
        specified in the URL and partner has access to multiple businesses.
    BusinessScopedJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT token. Token payload includes `business_id` to
        automatically scope requests. Format: `Bearer <your-jwt-token>`


        **Use this for**: Business-specific operations where the business
        context is embedded in the token.
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication for OAuth2 token endpoint. Use partner_uuid:api_key
        as username:password. Example: Authorization: Basic
        base64(partner_uuid:api_key)
    BearerUnscoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner (unscoped) JWT Bearer token. Obtain via POST
        /v1/platform/oauth2/token with Basic auth (partner_uuid:api_key). Use
        header: Authorization: Bearer {access_token}
    BearerBusinessScoped:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Business-scoped JWT Bearer token. Obtain via POST
        /v1/platform/{business_id}/oauth2/token/ using a partner Bearer token.
        Only valid for endpoints whose URL contains that business_id.

````