---
title: "Create Vendor Credit"
method: POST
path: "/v1/platform/businesses/{business_id}/vendor-credits/"
tags: ["Vendor Credits"]
---

# Create Vendor Credit

`POST /v1/platform/businesses/{business_id}/vendor-credits/`

## Request

- Base URL: `https://docs.thredfi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.thredfi.com/v1/platform/businesses/{business_id}/vendor-credits/`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP basic
  - HTTP bearer
  - HTTP bearer

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.

## Path parameters

- `business_id` string, required

## Request body

- CreateVendorCreditRequest: Vendor credit creation serializer with line_items support. Creates vendor credits with line_items for flexible account allocation.
  - `external_id` string, required: External system identifier for this vendor credit
  - `line_items` VendorCreditLineItemRequest[], required: Array of line items for this vendor credit
    - `amount` integer, required: Credit amount in cents for this line item
    - `sales_taxes` object[]: Tax array: [{'amount': cents}]. Sum represents tax portion of line amount.
    - `expense_account_identifier` unknown
    - `memo` string: Line item memo/description
    - `metadata` object: Line item metadata (max 10kb)
    - `reference_number` string: Line item reference number
    - `tags` object[]: Line item transaction tags
  - `vendor_id` string, uuid: Existing vendor ID to assign credit to
  - `vendor_external_id` string: External vendor ID. Will create vendor if not found
  - `source_bill_id` string, uuid, nullable: Optional bill ID this credit note was created from (origin tracking, not allocation)
  - `received_at` string, date-time: When the credit was received (ISO 8601). Defaults to now if provided
  - `allocations` VendorCreditAllocationRequest[]: Array of bill allocations for this credit
    - `amount` integer, required: Amount to allocate to bill in cents
    - `bill_id` string, uuid, required: Bill ID to allocate credit to
  - `tags` object[]: Transaction tags for the credit
  - `document` VendorCreditDocumentUploadRequest: Vendor credit specific document upload payload.
    - `file` string, binary
    - `document_type` string
    - `upload_source` string
    - `metadata` unknown
    - `tags` unknown

## Response `201`

- VendorCredit: Vendor credit serializer for API responses.
  - `id` string, uuid, required: Unique vendor credit identifier
  - `external_id` string: Your external system identifier for this credit (used for idempotency)
  - `status` string, required: Credit status: draft, received, partially_applied, applied, void (computed from allocations)
  - `received_at` string, date-time, required: When the credit was received
  - `vendor` VendorEmbedded, required: Vendor details embedded in credit note and other response objects.
    - `id` string, uuid, required: Vendor UUID
    - `external_id` string, required: External vendor identifier
    - `display_name` string, required: Vendor display name
  - `source_bill_id` string, uuid, nullable, required: Bill ID this credit was created from (origin tracking, not allocation)
  - `line_items` VendorCreditLineItemResponse[], required: Array of credit line items
    - `amount` integer, required: Credit amount in cents
    - `expense_account_identifier` AccountIdentifier, required: Standard account identifier format used across the API.
      - `type` string: Account identifier type (always 'AccountId')
      - `id` string, uuid, required: Account UUID
    - `memo` string
    - `metadata` unknown
    - `tags` string[], required: Line item transaction tags
  - `allocations` VendorCreditBillAllocationResponse[], required: Array of bill allocations
    - `bill_id` string, uuid, required: UUID of the bill this credit is allocated to
    - `bill_number` string, required: Bill number (e.g., BILL-00019)
    - `amount_cents` integer, required: Amount allocated to this bill in cents
    - `bill_outstanding_balance_cents` integer, required: Current outstanding balance on the bill in cents (after all allocations)
    - `applied_at` string, date-time, required: When the allocation was applied
  - `tags` object[], required: Transaction tags for the credit
  - `total_amount` integer, required: Total credit amount in cents
  - `applied_amount` integer, required: Applied credit amount in cents
  - `currency` 'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD': 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` DocumentFileUrl, required: Serializer for document file URL with metadata.
    - `url` string, uri, required: Presigned URL for document download
    - `expires_in` integer, required: Seconds until URL expires
    - `document_id` string, uuid, required: Document UUID
    - `file_name` string, required: Original document filename
    - `file_size` integer, required: File size in bytes
    - `mime_type` string, required: MIME type of the document
  - `created_at` string, date-time, required: Credit creation timestamp
  - `updated_at` string, date-time, required: Last update timestamp

## Other responses

- `400`: Validation errors in request data
- `401`: Authentication required - missing or invalid API key
- `403`: Permission denied - insufficient privileges
- `404`: Resource not found
- `409`: Conflict - resource already exists or invalid state transition
- `422`: Unprocessable entity - business logic validation failed
- `500`: Internal server error

---

[API](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api.md) - [All operations](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thredfi/apis/thredfi-accounting-platform-api/revisions/0c1918254db3?raw)