Pleaxy

Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

Credit notes

Credit notes that reduce what a buyer owes, and applying them to invoices.

More about this resource

Credit notes are statements like invoices: ListInvoices, GetInvoice and CreateInvoice serve them too with documentType credit_note, and these routes are the credit note's own actions. A credit note lowers what a buyer owes a supplier, with its own lines and tax. A supplier issues one against the invoice it corrects or for the buyer in general (or sends it through SubmitFeedInvoice); a buyer may record one it received. One that names an invoice and is no more than its total is accepted at once; any other waits for the buyer to accept or reject it. Accepting a returned_goods or price_adjustment credit (or other with correctsBilling) gives its pre-tax amount back to the corrected invoice's PO line; service credits and rebates leave the PO alone. Who settles accepted credits is a buyer setting: Pleaxy, where they're applied to invoices and lower the amount due (an approved invoice credits cover in full is marked paid with method "credit"), or the accounting system, where accepted credit notes go out in the next payment export as negative rows. Rejecting an invoice gives the credits applied to it back to their credit notes. The invoice total and its tax never change. A credit memo AWS or Azure issues against a bill your cloud connection syncs is recorded as a credit note from that provider (source "cloud_sync", with cloudProvider), against the invoice it names when that invoice is in Pleaxy, once per memo.

Endpoints

List credit notes

Lists credit notes, with what's left of each.

GET/v1/workspaces/{regionId}/credit-notes

Returns

200 OK with the object shown in the response.

More details

The credit notes a buyer received or a supplier issued (across its buyers), oldest first, each with remaining: what's left to apply, never stored.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/credit-notes
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
[ {
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
} ]

Get credit note

Retrieves one credit note.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}

Parameters

  • creditNoteIdstringRequired

    The credit note, e.g. "CN-1A2B3C4D".

Returns

200 OK with the object shown in the response.

More details

One credit note: what it corrects, what acceptance did to the PO (poEffect), the invoices it was applied to or the export that carried it, and what's left of it.

Response fields

  • remainingnumber

    amount − what's applied to invoices − refunded. 0 once used up; an exported credit note is settled by the accounting system.

  • refundednumber

    What the supplier says was already refunded before it sent the credit note (UBL PrepaidAmount, cXML DepositAmount). Never left to apply.

  • poEffectobject

    Set on acceptance: the PO balance given back (kind release, before tax, with the quantity for returned goods), or why none was (not_a_correction, no_po, po_closed).

  • hasPdfboolean

    The credit note has its own PDF, attached when it was issued or the document it was recorded from: GetCreditNotePdf returns it.

  • source, cloudProviderstring, string

    source is "feed" for one sent through SubmitFeedInvoice (in submittedFormat) and "cloud_sync" for a provider's credit memo (cloudProvider aws or azure); absent when entered in Pleaxy or with CreateCreditNote.

Errors

  • 404 Not Found - No such credit note in this workspace ("Credit note <id> not found.").
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Get credit note PDF

Downloads a credit note's PDF.

GET/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf

Parameters

  • creditNoteIdstringRequired

    The credit note, e.g. "CN-1A2B3C4D".

Returns

200 OK with the object shown in the response.

More details

The credit note's own PDF: the one attached when it was issued (pdfBase64), or the document it was recorded from. Pleaxy doesn't generate one. Send Accept: application/pdf, or the body comes back base64-encoded.

Errors

  • 404 Not Found - No such credit note in this workspace, or code CREDIT_NOTE_NO_PDF: it has none (hasPdf is false).
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/pdf" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
application/pdf

Create credit note

Issues a credit note, or records one received.

POST/v1/workspaces/{regionId}/credit-notes

Body

  • invoiceIdstring

    The invoice it corrects. Not a rejected one. Give this or connectionId.

  • connectionIdstring

    The counterparty, when it corrects no one invoice.

  • externalCreditNoteNumberstringRequired

    Your number for it, 1–64 characters: letters, digits, '.', '_', '/' and '-', starting with a letter or digit. Unique per supplier within the buyer, case-insensitively.

  • issueDatestringRequired

    YYYY-MM-DD, not in the future and not more than 365 days back.

  • reasonstringRequired

    returned_goods, price_adjustment, service_credit, rebate or other. The first two give PO balance back once accepted.

  • correctsBillingboolean

    Reason other only: it corrects what was billed, so it gives PO balance back too.

  • notestring

    1–1000 characters, e.g. the return's RMA number.

  • currencystring

    ISO 4217. Required with connectionId; with invoiceId it must be the invoice's.

  • lineItemsArray<{ description, qty, unitPrice }>Required

    What is credited, before tax. 1–200 lines.

  • taxAmountnumber

    The tax credited, included in the total.

  • taxBreakdownArray<{ description, amount, rate? }>

    Tax by type, summing to taxAmount. At most 20.

  • pdfBase64string

    Base64-encoded PDF of the credit note as issued, up to 8MB. Kept with it (see GetCreditNotePdf).

  • sourceImportIdstring

    Buyer only: the invoice import (ID-…) the credit note was read from - the supplier's credit note document, uploaded and read by Pleaxy. Its document is kept with the credit note when it is a PDF under 8MB, and the import records the credit note. Never shown to the supplier.

Returns

201 Created with the object shown in the response.

More details

Issues a credit note (a supplier) or records one received (a buyer). Name exactly one of invoiceId (the invoice it corrects, whose buyer, supplier, currency, PO and PO line it takes) or connectionId (the counterparty, with currency). The total is computed from the lines and tax like CreateInvoice's. Accepted at once when it names an invoice and is no more than that invoice's total; it is then applied to that invoice when the buyer's credits are settled in Pleaxy and the invoice isn't exported or paid. The buyer is notified.

Errors

  • 400 Bad Request - CREDIT_NOTE_TARGET_REQUIRED (neither or both of invoiceId and connectionId), CREDIT_NOTE_INVALID (correctsBilling with another reason, a rejected invoice, a currency that isn't the invoice's, no currency without an invoice), ISSUE_DATE_INVALID, a pdfBase64 that isn't base64, is empty or over 8MB, or isn't a PDF ("pdfBase64 doesn't decode to a PDF document (missing %PDF- header)"), or a body that fails validation.
  • 404 Not Found - The invoice or the connection isn't yours.
  • 409 Conflict - CREDIT_NOTE_NUMBER_TAKEN: this number is already used between you and this buyer.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/credit-notes
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "invoiceId": "string",
   "connectionId": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": boolean,
   "note": "string",
   "currency": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number } ],
   "taxAmount": number,
   "pdfBase64": "string"
}
Response · 201 Created
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Accept credit note

Accepts a credit note.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept

Parameters

  • creditNoteIdstringRequired

    The credit note, e.g. "CN-1A2B3C4D".

Returns

200 OK with the object shown in the response.

More details

Accepts a credit note waiting for acceptance. In one write: its status, the PO balance a correction gives back (never more than the corrected invoice drew on the line, less earlier credits), and - when credits are settled in Pleaxy and the invoice it corrects can take it - its application there. The supplier is notified.

Errors

  • 400 Bad Request - CREDIT_OVER_RELEASES_PO: it would give back more than the invoice drew on its PO line.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING (already accepted, rejected or voided), or CREDIT_NOTE_CHANGED (it changed while being accepted; reload and retry).
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/accept" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Reject credit note

Rejects a credit note, with a reason.

POST/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject

Parameters

  • creditNoteIdstringRequired

    The credit note, e.g. "CN-1A2B3C4D".

Body

  • reasonstringRequired

    1–1000 characters.

Returns

200 OK with the object shown in the response.

More details

Rejects a credit note waiting for acceptance, with a reason the supplier reads. The supplier is notified.

Errors

  • 400 Bad Request - CREDIT_NOTE_INVALID: no reason.
  • 409 Conflict - CREDIT_NOTE_NOT_PENDING or CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/{creditNoteId}/reject" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "reason": "string" }
Response · 200 OK
{
   "documentType": "credit_note",
   "id": "string",
   "externalCreditNoteNumber": "string",
   "issueDate": "string",
   "buyerOrgId": "string",
   "buyerOrgName": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "supplierConnectionId": "string",
   "currency": "string",
   "reason": "returned_goods" | "price_adjustment" | "service_credit" | "rebate" | "other",
   "correctsBilling": true,
   "note": "string",
   "lineItems": [ { "description": "string", "qty": number, "unitPrice": number, "amount": number } ],
   "adjustments": [ { "type": "discount" | "charge", "description": "string", "amount": number } ],
   "taxAmount": number,
   "amount": number,
   "refunded": number,
   "remaining": number,
   "invoiceId": "string",
   "externalInvoiceNumber": "string",
   "po": "string",
   "poLineNo": number,
   "status": "pending_acceptance" | "accepted" | "rejected" | "void",
   "autoAccepted": true,
   "acceptedAt": "string",
   "rejection": { "at": "string", "reason": "string" },
   "poEffect": { "kind": "release", "po": "string", "poLineNo": number, "amount": number, "qty": number } | { "kind": "none", "why": "not_a_correction" | "no_po" | "po_closed" },
   "applications": [ { "id": "string", "invoiceId": "string", "externalInvoiceNumber": "string", "amount": number, "appliedAt": "string", "auto": true } ],
   "exports": [ { "exportId": "string", "exportedAt": "string" } ],
   "source": "feed" | "cloud_sync",
   "submittedFormat": "json" | "ubl" | "cxml",
   "cloudProvider": "aws" | "azure",
   "hasPdf": boolean,
   "createdAt": "string"
}

Get credit settlement

Returns where accepted credits are settled.

GET/v1/workspaces/{regionId}/credit-notes/settings

Returns

200 OK with the object shown in the response.

More details

Who settles accepted credits: pleaxy (applied to invoices here) or accounting_system (exported for your ERP). Until chosen (chosen: false), it's accounting_system for a workspace that has exported invoices for payment and pleaxy otherwise.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/credit-notes/settings
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

Set credit settlement

Chooses where accepted credits are settled.

PUT/v1/workspaces/{regionId}/credit-notes/settings

Body

  • creditSettlementstringRequired

    "pleaxy" or "accounting_system".

Returns

200 OK with the object shown in the response.

More details

Chooses who settles accepted credits. Moving to accounting_system is refused while credits sit on unpaid invoices; take them off first.

Errors

  • 400 Bad Request - CREDIT_SETTLEMENT_INVALID.
  • 409 Conflict - CREDITS_APPLIED_TO_UNPAID: credits are applied to unpaid invoices.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
PUT /v1/workspaces/{regionId}/credit-notes/settings
Request
curl -X PUT "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/credit-notes/settings" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "creditSettlement": "pleaxy" | "accounting_system" }
Response · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "chosen": boolean
}

List available credits

Lists the credits that can be applied to an invoice.

GET/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits

Parameters

  • invoiceIdstringRequired

    The invoice, e.g. "INV-1A2B3C4D".

Returns

200 OK with the object shown in the response.

More details

The accepted credits from the invoice's supplier in its currency, oldest first, each with what's left and a suggestion (up to what the invoice owes), and the supplier's credit notes still waiting for acceptance. locked says why the invoice can't take credits now.

Errors

  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/available-credits" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "creditSettlement": "pleaxy" | "accounting_system",
   "locked": "exported" | "paid" | "rejected" | "otherCurrency",
   "amountDue": number,
   "currency": "string",
   "credits": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "issueDate": "string", "amount": number, "remaining": number, "suggested": number } ],
   "pending": [ { "creditNoteId": "string", "externalCreditNoteNumber": "string", "reason": "string", "amount": number } ],
   "suggestedTotal": number
}

Apply credits

Applies credits to an invoice.

POST/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications

Parameters

  • invoiceIdstringRequired

    The invoice, e.g. "INV-1A2B3C4D".

Body

  • applicationsArray<{ creditNoteId, amount }>Required

    1–20, each credit note once, each amount at most what's left of it.

Returns

200 OK with the object shown in the response.

More details

Applies accepted credits to an invoice that isn't exported, paid, rejected or owed in another currency - all or none, in one write with each credit note. The amount due goes down; the total and its tax don't. Credits may cover at most what the invoice owes; an approved invoice they cover in full is marked paid with method "credit" (an unapproved one, once approved). The supplier is notified. Returns the invoice.

Errors

  • 400 Bad Request - CREDIT_APPLICATIONS_REQUIRED, CREDIT_APPLICATIONS_INVALID (a credit note listed twice, in another currency, or from another supplier), or CREDIT_OVER_APPLIED (more than is left of a credit note, or more than the invoice owes).
  • 409 Conflict - INVOICE_LOCKED (exported, paid, rejected or owed in another currency), CREDIT_NOTE_NOT_ACCEPTED, CREDITS_SETTLED_IN_ACCOUNTING (your accounting system settles credits), or CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{ "applications": [ { "creditNoteId": "string", "amount": number } ] }
Response · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}

Remove credit application

Removes a credit from an invoice.

DELETE/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}

Parameters

  • invoiceIdstringRequired

    The invoice, e.g. "INV-1A2B3C4D".

  • applicationIdstringRequired

    The application, from the invoice's creditApplications.

Returns

200 OK with the object shown in the response.

More details

Takes a credit back off an invoice that isn't exported or paid; it goes back to its credit note. Returns the invoice.

Errors

  • 404 Not Found - The invoice has no such application.
  • 409 Conflict - INVOICE_LOCKED (exported or paid), or CREDIT_NOTE_CHANGED.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
DELETE /v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}
Request
curl -X DELETE "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/invoices/{invoiceId}/credit-applications/{applicationId}" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "documentType": "invoice" | "debit_note",
   "amendsInvoiceId": "string",
   "amendsExternalInvoiceNumber": "string",
   "debitNoteIds": [ "string" ],
   "replacesInvoiceIds": [ "string" ],
   "replacedByInvoiceIds": [ "string" ],
   "replacement": { "creditedInFull": boolean, "uncredited": number },
   "uncreditedOriginals": [ { "invoiceId": "string", "externalInvoiceNumber": "string", "uncredited": number, "currency": "string" } ],
   "id": "string",
   "po": "string",
   "poLineNo": number,
   "billsNoPoLine": true,
   "buyerOrgId": "string",
   "supplierOrgId": "string",
   "supplier": "string",
   "amount": number,
   "currency": "string",
   "usageAmount": number,
   "usageCurrency": "string",
   "tolerancePct": number,
   "matchStatus": "pending" | "matched" | "discrepancy" | "unverified",
   "unverifiedReason": "no_purchase_order" | "no_billing_connection" | "debit_note",
   "discrepancyReason": "amount" | "currency",
   "paid": boolean,
   "dueInDays": number,
   "approval": {
      "requester": "string",
      "requesterEmployeeKey": "string",
      "groups": [
        {
          "id": "string",
          "mode": "sequential" | "parallel",
          "label": "string",
          "status": "pending" | "approved" | "rejected",
          "stages": [
            { "id": "string", "label": "string", "approverEmployeeKey": "string", "approverName": "string", "status": "pending" | "approved" | "rejected" }
          ]
        }
      ],
      "groupIndex": number,
      "status": "pending" | "approved" | "rejected",
      "history": [
        { "stage": "string", "by": "string", "at": "string", "action": "approved" | "rejected" | "limit_exceeded" | "reassigned" | "skipped" }
      ],
      "autonomy": boolean,
      "selfApproved": boolean
    },
   "createdAt": "string",
   "lastRemindedAt": "string",
   "rejection": { "reasonCode": "amount_incorrect" | "not_ordered_or_not_received" | "duplicate" | "missing_or_wrong_po" | "wrong_billing_entity" | "other", "reason": "string", "at": "string" },
   "replacesInvoiceId": "string",
   "source": "po-flip" | "direct" | "manual" | "feed",
   "submittedFormat": "json" | "cxml" | "ubl",
   "submittedBy": "string",
   "externalInvoiceNumber": "string",
   "lineItems": [
      { "description": "string", "qty": number, "unitPrice": number, "discount": number, "charge": number, "amount": number }
   ],
   "adjustments": [
      { "type": "discount" | "charge", "description": "string", "amount": number }
   ],
   "taxAmount": number,
   "taxBreakdown": [ { "description": "string", "rate": number, "amount": number } ],
   "paymentCurrencyAmount": { "currencyCode": "string", "totalAmount": number, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "taxCurrencyAmount": { "currencyCode": "string", "amountBreakdown": { "taxes": { "totalAmount": number } }, "currencyExchangeDetails": { "rate": number, "rateDate": "string", "rateSource": "string" } },
   "baseCurrencyAmount": { "currencyCode": "string", "totalAmount": number },
   "rateWarnings": [
      { "object": "payment" | "tax", "currency": "string", "statedRate": number, "referenceRate": number, "source": "provider" | "override", "asOf": "string", "deviationPct": number }
   ],
   "withholdings": [ { "description": "string", "rate": number, "amount": number } ],
   "deductions": [ { "kind": "prepayment" | "credit", "description": "string", "amount": number, "reference": "string", "paidOn": "string", "sourceInvoiceId": "string", "stated": true } ],
   "invoiceKind": "prepayment",
   "creditNoteIds": [ "string" ],
   "creditApplications": [ { "id": "string", "creditNoteId": "string", "externalCreditNoteNumber": "string", "amount": number, "appliedAt": "string", "appliedByName": "string", "auto": true } ],
   "payment": { "status": "recorded", "method": "ach" | "wire" | "check" | "card" | "other" | "credit", "paymentDate": "string", "reference": "string", "paidAmount": { "amount": number, "currency": "string", "rate": number, "rateDate": "string" } },
   "remittances": [ { "id": "string", "sentAt": "string", "sentByName": "string", "note": "string", "file": { "fileName": "string", "contentType": "application/pdf" | "image/png" | "image/jpeg", "sizeBytes": number } } ]
}
Talk to us