Credit notes

POST /v1/credit-notes issues a credit note (nota de crédito, XML 1.1.0): a return, a discount or a correction that reduces the amount of an invoice already issued.

Request

curl https://api.flashpi.com.ec/v1/credit-notes \
  -H "Authorization: Bearer $FLASHPI_API_KEY" \
  -H "Idempotency-Key: return-RMA-2291" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
    "establishment": "001",
    "emissionPoint": "001",
    "issueDate": "2026-10-16",
    "customer": {
      "idType": "ruc",
      "id": "1790000000001",
      "name": "Supermercados La Pradera S.A.",
      "email": "compras@example.com"
    },
    "modifiedDocument": {
      "type": "invoice",
      "number": "001-001-000000123",
      "issueDate": "2026-10-15"
    },
    "reason": "Return of damaged goods",
    "items": [
      {
        "code": "CAF-500",
        "description": "Ground coffee 500 g",
        "quantity": "1",
        "unitPrice": "4.25",
        "discount": "0.25",
        "taxes": [{ "type": "vat", "rate": "15" }]
      }
    ],
    "expectedTotal": "4.60"
  }'

Field	Required	Notes
customer	Yes	The buyer of the modified invoice. It cannot be a final consumer (final_consumer_not_allowed). Credit notes do not print the address.
modifiedDocument.type	No	The type of the modified document. Only invoice is accepted, and it is the default.
modifiedDocument.number	Yes	Its number, 001-001-000000123.
modifiedDocument.issueDate	Yes	Its issue date, on or before the credit note’s.
reason	Yes	Why the note is issued, up to 300 characters.
items	Yes	The lines being credited, as in an invoice; code is optional here. Lines take one VAT and optionally one ad valorem ICE.
expectedTotal	No	The credited amount you expect.

Credit notes have no payments and no tip. The fields every request shares work as everywhere.

• VAT rates follow the modified invoice: a credit note uses the rates in force on modifiedDocument.issueDate, not on its own date, so a return of goods sold at an older rate keeps that rate.
• Flashpi does not look the invoice up. It checks the number’s format and the date order, but the invoice may have been issued outside Flashpi. Make sure the number, the date and the amounts match the invoice you modify: the SRI and your customer rely on them.

What Flashpi computes

The line subtotal is 1 × 4.25 − 0.25 = 4.00, the VAT 15 % of 4.00 = 0.60, and the credited amount, the note’s total, 4.60.

Response

202 Accepted:

{
  "id": "01a1451f-b91c-73ac-a726-b8348185c655",
  "type": "credit_note",
  "environment": "test",
  "status": "processing",
  "issuerId": "01a0fd6a-d098-76ca-b492-1bcb6505a7bd",
  "establishment": "001",
  "emissionPoint": "001",
  "sequential": 18,
  "number": "001-001-000000018",
  "accessKey": "1610202604179000000000110010010000000186420931518",
  "issueDate": "2026-10-16",
  "xmlVersion": "1.1.0",
  "counterparty": { "id": "1790000000001", "name": "Supermercados La Pradera S.A." },
  "totals": {
    "subtotal": "4.00",
    "discount": "0.25",
    "taxes": [{ "type": "vat", "rate": "15", "taxableBase": "4.00", "amount": "0.60" }],
    "total": "4.60"
  },
  "authorization": { "number": null, "authorizedAt": null },
  "ride": { "status": "pending", "template": null, "generatedAt": null },
  "email": { "requested": true, "status": "queued", "deliveries": [], "warnings": [] },
  "sriMessages": [],
  "failure": null,
  "voidedAt": null,
  "createdAt": "2026-10-16T14:31:09.340Z",
  "updatedAt": "2026-10-16T14:31:09.340Z"
}

Credit notes are numbered in their own series: the first credit note of an emission point is 000000001, whatever its invoices are at. With options.waitForAuthorization the answer can be 200 OK with the final status (Sync and async modes). The credit_note.authorized and credit_note.rejected webhooks report the SRI’s decision.

Errors

Answer	When
422 validation_failed	For example customer.idType final_consumer_not_allowed, modifiedDocument.number invalid_format, or modifiedDocument.issueDate later than the note (date_too_late).
422 total_mismatch	expectedTotal differs from the computed credited amount.
409 sequential_already_used, sequentials_exhausted	See Sequentials.