> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypathiq.com/llms.txt > Use this file to discover all available pages before exploring further. # Record an immutable CreditNote > Record a CreditNote issued in the Source, which changes a Receivable's balance. Requires financial_corrections:write. The type must match the resource family. Credits and write-offs decrease balances; adjustments declare their direction. Exact retries are safe; changed identities and stale source revisions conflict. These operations do not collect money or initiate refunds. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/credit-notes/{externalEventId} openapi: 3.1.0 info: description: >- Send Customers, Receivables, and Payment observations and related financial evidence from your source system to PayPathIQ, one record at a time or as bounded asynchronous batches, and read back changes. Every operation listed here is implemented; capabilities that are not implemented are not listed. Start in sandbox with a sandbox key and synthetic data. Every error type links to a page at https://docs.paypathiq.com/problems/{code}. title: PayPathIQ Inbound Receivables API version: 1.0.0 servers: - description: Sandbox url: https://api.sandbox.paypathiq.com - description: Production url: https://api.paypathiq.com security: - BearerAuth: [] tags: - description: >- The people and businesses that owe a Client money. Start here: create each Customer before you send Receivables for them. name: Customers - description: >- Individual amounts a Customer owes, each recoverable on its own. Use these to create, read and update the Receivables your system owns. name: Receivables - description: >- Immutable records of payments, refunds and reversals that happened outside PayPathIQ. Use them to tell PayPathIQ when a Customer has paid. name: Payment observations - description: >- Commands that pause, resume, close or reopen recovery on a Receivable. Use them when the Source decides recovery should stop or restart. name: Receivable lifecycle - description: >- Ordered Source balances for up to 100 Receivables. Use them when your system reports balances rather than individual transactions. name: Balance snapshots - description: >- Asynchronous ingestion of up to 100 records in one request, with an exact outcome per record. Use them to load a large book, then poll for the result. name: Batches - description: >- A durable, resumable feed of committed Customer, Receivable and payment changes. Use it to keep your system in step, and to recover after downtime or missed webhooks. name: Changes - description: >- Optional signed notifications that something changed. Use them to know when to read the change feed; each one is a hint, not a copy of the data. name: Webhooks - description: >- Immutable credit notes, adjustments and write-offs issued in the Source. Use them to report a change in what a Customer owes that is not a payment. name: Financial events - description: >- Declarations that a set of batches carried the Source's complete book. Use them so PayPathIQ can hold Receivables that are missing from the book. name: Complete books - description: >- Explicit, revisioned instructions that let PayPathIQ begin recovery for a Receivable. Use them only if your connection starts recovery by instruction. name: Recovery instructions - description: >- Read-only working collection position, holds, commitments and action outcomes for Receivables. Use them to show collection status in your own system. name: Collection summaries - description: >- A read-only check on whether your source data is recent enough for PayPathIQ to act on. Use it to find out why recovery actions are held. name: Source freshness - description: >- Fixed-amount hosted payment pages through the Client's own payment provider merchant. Use them to let a Customer pay a set of Receivables by card. name: Payment requests - description: >- Confirmed Payments that a partner-owned connection delivers to accounting, kept separate from accounting acceptance. Use them if your connection owns receipt delivery. name: Payment delivery - description: >- Acknowledgements that Source receipt lines match a confirmed Payment, and the resolution of any differences. Use them to tell PayPathIQ that accounting has recorded a Payment. name: Payment reconciliation - description: >- PayPathIQ-owned delivery of receipts to the accounting Source, with acknowledgement kept separate. Use it to see or request delivery of a confirmed Payment's receipt. name: Receipt delivery - description: >- This machine-readable API contract. Use it to import the API into your tooling. name: Specification paths: /v1/clients/{clientCode}/credit-notes/{externalEventId}: put: tags: - Financial events summary: Record an immutable CreditNote description: >- Record a CreditNote issued in the Source, which changes a Receivable's balance. Requires financial_corrections:write. The type must match the resource family. Credits and write-offs decrease balances; adjustments declare their direction. Exact retries are safe; changed identities and stale source revisions conflict. These operations do not collect money or initiate refunds. operationId: putCreditNote parameters: - name: clientCode in: path required: true schema: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ - name: externalEventId in: path required: true schema: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ requestBody: description: One uncompressed resource representation, limited to 256 KiB. content: application/json: example: type: credit_note amount: amount: '10.00' currency: EUR externalReceivableId: REC_EXAMPLE sourceRevision: 2 effectiveAt: '2026-10-14T12:00:00Z' reason: billing_correction sourceReference: CREDIT_SOURCE schema: $ref: '#/components/schemas/CreditNote' required: true responses: '200': content: application/json: example: type: credit_note amount: amount: '10.00' currency: EUR externalReceivableId: REC_EXAMPLE sourceRevision: 2 effectiveAt: '2026-10-14T12:00:00Z' reason: billing_correction sourceReference: CREDIT_SOURCE externalEventId: EVENT_EXAMPLE acceptedAt: '2026-10-14T12:00:01Z' schema: $ref: '#/components/schemas/CreditNoteResponse' description: Identical safe retry. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '201': content: application/json: example: type: credit_note amount: amount: '10.00' currency: EUR externalReceivableId: REC_EXAMPLE sourceRevision: 2 effectiveAt: '2026-10-14T12:00:00Z' reason: billing_correction sourceReference: CREDIT_SOURCE externalEventId: EVENT_EXAMPLE acceptedAt: '2026-10-14T12:00:01Z' schema: $ref: '#/components/schemas/CreditNoteResponse' description: Evidence and balance committed atomically. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Location: description: Canonical URL of the created Integration-facing resource. schema: type: string format: uri '400': content: application/problem+json: examples: malformed_json: value: detail: Request body is not valid JSON. requestId: 29400000-0000-4000-8000-000000000001 status: 400 title: Request body is not valid JSON. type: https://docs.paypathiq.com/problems/malformed_json schema: $ref: '#/components/schemas/Problem' description: Request body is not valid JSON. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '401': content: application/problem+json: examples: invalid_api_key: value: detail: >- API key is invalid, inactive, revoked, or for another environment. requestId: 29400000-0000-4000-8000-000000000001 status: 401 title: >- API key is invalid, inactive, revoked, or for another environment. type: https://docs.paypathiq.com/problems/invalid_api_key schema: $ref: '#/components/schemas/Problem' description: API key is invalid, inactive, revoked, or for another environment. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '403': content: application/problem+json: examples: client_scope_denied: value: detail: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. requestId: 29400000-0000-4000-8000-000000000001 status: 403 title: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. type: https://docs.paypathiq.com/problems/client_scope_denied schema: $ref: '#/components/schemas/Problem' description: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '409': content: application/problem+json: examples: financial_operation_required: value: detail: >- The connection declares snapshot balance authority; event balance writes are unavailable. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The connection declares snapshot balance authority; event balance writes are unavailable. type: >- https://docs.paypathiq.com/problems/financial_operation_required financial_event_conflict: value: detail: Identity already has different immutable evidence. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: Identity already has different immutable evidence. type: >- https://docs.paypathiq.com/problems/financial_event_conflict source_revision_conflict: value: detail: Source revision is not newer than the accepted position. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: Source revision is not newer than the accepted position. type: >- https://docs.paypathiq.com/problems/source_revision_conflict dependency_missing: value: detail: The source Receivable must already exist. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: The source Receivable must already exist. type: https://docs.paypathiq.com/problems/dependency_missing balance_mismatch: value: detail: The financial effect exceeds the supported balance bounds. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: The financial effect exceeds the supported balance bounds. type: https://docs.paypathiq.com/problems/balance_mismatch schema: $ref: '#/components/schemas/Problem' description: >- The connection declares snapshot balance authority; event balance writes are unavailable. Identity already has different immutable evidence. Source revision is not newer than the accepted position. The source Receivable must already exist. The financial effect exceeds the supported balance bounds. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '413': content: application/problem+json: examples: request_too_large: value: detail: Request body exceeds the 256 KiB resource limit. requestId: 29400000-0000-4000-8000-000000000001 status: 413 title: Request body exceeds the 256 KiB resource limit. type: https://docs.paypathiq.com/problems/request_too_large schema: $ref: '#/components/schemas/Problem' description: Request body exceeds the 256 KiB resource limit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '415': content: application/problem+json: examples: unsupported_media_type: value: detail: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. requestId: 29400000-0000-4000-8000-000000000001 status: 415 title: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. type: https://docs.paypathiq.com/problems/unsupported_media_type schema: $ref: '#/components/schemas/Problem' description: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '422': content: application/problem+json: examples: validation_error: value: detail: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. errors: - code: invalid_format detail: Invalid ISO date pointer: /dueDate requestId: 29400000-0000-4000-8000-000000000001 status: 422 title: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. type: https://docs.paypathiq.com/problems/validation_error schema: $ref: '#/components/schemas/Problem' description: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '429': content: application/problem+json: examples: rate_limit_exceeded: value: detail: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. requestId: 29400000-0000-4000-8000-000000000001 status: 429 title: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. type: https://docs.paypathiq.com/problems/rate_limit_exceeded schema: $ref: '#/components/schemas/Problem' description: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Retry-After: description: >- Seconds until this unchanged request may be retried: 1 after a concurrency rejection, 60 after the per-minute limit. schema: minimum: 1 type: integer '503': content: application/problem+json: examples: projection_unavailable: value: detail: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. requestId: 29400000-0000-4000-8000-000000000001 status: 503 title: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. type: https://docs.paypathiq.com/problems/projection_unavailable schema: $ref: '#/components/schemas/Problem' description: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string security: - BearerAuth: [] components: schemas: CreditNote: type: object properties: amount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ sourceRevision: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effectiveAt: 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))$ reason: type: string enum: - billing_correction - contractual_credit sourceReference: type: string minLength: 1 maxLength: 200 type: type: string const: credit_note required: - amount - externalReceivableId - sourceRevision - effectiveAt - reason - sourceReference - type additionalProperties: false CreditNoteResponse: type: object properties: amount: type: object properties: amount: type: string pattern: ^(0|[1-9]\d{0,13})\.\d{2}$ currency: type: string const: EUR required: - amount - currency additionalProperties: false externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ sourceRevision: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effectiveAt: 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))$ reason: type: string enum: - billing_correction - contractual_credit sourceReference: type: string minLength: 1 maxLength: 200 type: type: string const: credit_note externalEventId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ acceptedAt: 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))$ required: - amount - externalReceivableId - sourceRevision - effectiveAt - reason - sourceReference - type - externalEventId - acceptedAt additionalProperties: false Problem: type: object properties: detail: type: string errors: maxItems: 20 type: array items: type: object properties: code: type: string detail: type: string pointer: type: string required: - code - detail - pointer additionalProperties: false requestId: 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)$ status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string format: uri required: - detail - requestId - status - title - type additionalProperties: false securitySchemes: BearerAuth: bearerFormat: ppiq_test__ or ppiq_live__ description: >- Integration-owned environment-specific API key. Never paste a production key into documentation tools. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.