Add/Update Credit

The following endpoint can be used to add or update a credit (a credit memo or credit note) within the CoCard Pay Center application. A credit is money owed to a customer. Once issued, the customer can apply it to their open invoices at checkout in the customer portal. Every amount is stored as a positive number.

Endpoint

The following endpoint can be used to add or update a credit. You must replace the {base_url} and {site_id} variables with the appropriate values. Credits are available on API version 4.0 only, and must be enabled for the site; a site without credits answers credits_not_enabled .

• A credit created through the API is issued immediately and can be applied right away.
• Send every amount positive, or send your system's negative amounts with autoReverseAmount: true and they are flipped before they are stored. A negative amount without the flag, or the flag on a positive amount, is refused, so a sign is never changed by accident.
• A line whose sign differs from the credit's (a charge inside a credit) is refused: net it into the credit or send it as an invoice.
• Once a credit has been applied, its amount cannot be lowered below what has been applied, and its customer can never be changed.
• Pass deleted: true to void a credit that has not been applied. A voided credit stays voided: posting it again is refused with credit_voided .

			
{
  "externalId": "CM-88123",
  "creditNumber": "CM-88123",
  "creditDate": "2026-10-01",
  "poNumber": "PO-552",
  "description": "Return RMA 7781",
  "customer": {
    "externalId": "100234"
  },
  "lines": [
    {
      "name": "Returned: Cabinet Knob K-12",
      "qty": 10,
      "unitPrice": 1250,
      "subtotal": 12500,
      "total": 12500
    },
    {
      "name": "Returned: Drawer Pull P-40",
      "qty": 2,
      "unitPrice": 1250,
      "subtotal": 2500,
      "total": 2500
    }
  ]
}


		

			
{
  "externalId": "CM-88124",
  "creditNumber": "CM-88124",
  "customer": {
    "externalId": "100234"
  },
  "autoReverseAmount": true,
  "amount": -4500,
  "subtotal": -4500,
  "lines": [
    {
      "name": "Returned: Hinge H-3",
      "qty": -3,
      "unitPrice": 1500,
      "subtotal": -4500,
      "total": -4500
    }
  ]
}


		

			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z"
}


		

			
{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}


		

Sending a credit through Add/Update Invoice

If your system stores credits as negative invoices, you can keep sending them to site/{site_id}/invoice/addUpdate (single or batch) and add isCredit: true . The record is stored as a credit instead of an invoice, and the response's recordType is credit . On a site with credits enabled, a negative invoice without isCredit is refused with negative_invoice_requires_is_credit .

• invoiceNumber and invoiceDate become the credit number and credit date, and totals supplies the amounts.
• Lines are optional here: a credit sent without lines gets one line built from its description and total, and the response warns line_synthesized .
• Invoice-only fields such as send and dueDate are ignored and listed in warnings .
• Payments, installments, fees and templates are refused on a credit.
• A credit and an invoice on the same site cannot share an external id.

			
{
  "isCredit": true,
  "autoReverseAmount": true,
  "externalId": "CM-88123",
  "invoiceNumber": "CM-88123",
  "invoiceDate": "2026-10-01",
  "poNumber": "PO-552",
  "customer": {
    "externalId": "100234"
  },
  "description": "Return RMA 7781",
  "totals": {
    "subtotal": -15000,
    "taxes": 0,
    "discounts": 0,
    "total": -15000
  }
}


		

			
{
  "success": true,
  "action": "added",
  "_id": "6717a2c4e1f0a93b2c5d8e11",
  "updatedAt": "2026-10-01T14:02:37.000Z",
  "recordType": "credit",
  "code": "P5XU4MK7QZ2X",
  "warnings": [
    "line_synthesized"
  ]
}


		

How applied credits appear

Each application of a credit to an invoice is recorded as a payment with type: 'credit' and credit set to the credit's _id , so it reduces the invoice balance like any payment. Read it with the Payments endpoints and the payment webhook; a voided application reports status: 'voided' . These payments are read-only through the API.

Errors

A refused credit answers HTTP 422 with one of the following codes. A 422 is permanent: correct the payload rather than retrying it.

• credits_not_enabled : credits are not enabled for the site.
• credit_identity_required : a new credit needs an _id or externalId .
• credit_lines_required : Add/Update Credit needs at least one line.
• credit_negative_amount_requires_auto_reverse , credit_auto_reverse_on_non_negative_amount , credit_zero_amount : the amount's sign does not match autoReverseAmount , or the credit is zero.
• credit_mixed_sign_lines : a line's sign differs from the credit's.
• credit_totals_mismatch , credit_line_totals_mismatch : the amounts do not add up.
• credit_identity_conflict : the external id belongs to another credit or to an invoice.
• credit_customer_immutable , credit_amount_below_applied , credit_has_applications : the change is not allowed once the credit has been applied.
• credit_voided : the credit is voided.
• credit_kind_not_authorable : only creditNote can be created.