← All articles

Apply a customer receipt

Customer receipts in Sage 50 record money received from a customer and apply it to open sales invoices. Use POST /api/receipts to post a receipt against a single invoice.

Prerequisites

Before applying a receipt, make sure you have:

Use GET /api/sales to find invoices to pay. Filter by customerId and repeat paymentStatus for unpaid and partial invoices (0 = unpaid, 1 = partial). You can also limit the list with modifiedSince or activitySince:

GET /api/sales?customerId=42&paymentStatus=0&paymentStatus=1

modifiedSince returns invoices whose content was edited on or after that date and time (amounts, lines, and so on). Applying a payment alone does not count. activitySince returns invoices with any update on or after that time, including payments.

Each result includes invoiceNumber, amountOwing, lastModifiedAt, and lastActivityAt. lastModifiedAt is when the invoice itself was last edited. lastActivityAt is when anything last changed, including payments. You can also use GET /api/sales/{saleId} if you already have the sale id from when the invoice was created.

Pick a deposit account (bank or cash) from GET /api/general-accounts. Send the account display number in depositAccountNumber, the same way general journal lines use accountNumber.

Authentication

Pass your API key in the x-api-key request header:

x-api-key: YOUR_API_KEY

Endpoint

POST /api/receipts

customerId, invoiceNumber, amount, depositAccountNumber, and paymentMethod are required. The payment must be greater than zero and cannot exceed the invoice amountOwing.

What you actually need to send

Field Required? What happens if omitted
customerId Yes Request is rejected
invoiceNumber Yes Request is rejected. Must match an open invoice for the customer
amount Yes Request is rejected. Must be ≤ amountOwing on the invoice
depositAccountNumber Yes Request is rejected. Bank or cash account where the payment is deposited
paymentMethod Yes Request is rejected. See payment methods below
date No Sage uses the current date. The receipt date must fall within the company’s open fiscal period
chequeNumber No Optional reference when paymentMethod is Cheque (1)
creditCardId Yes for credit card Required when paymentMethod is CreditCard (2). Use GET /api/creditcards/selectable

paymentMethod values:

Value Method
0 Cash
1 Cheque
2 CreditCard
3 DirectPayment

When paymentMethod is 2 (CreditCard), creditCardId is required. When it is 1 (Cheque), send chequeNumber if you want the cheque reference on the receipt.

Request body

Minimum example for a full payment against one open invoice. Only the required fields are sent:

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 0
}

Cheque payment with a reference:

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 1,
  "chequeNumber": "1042"
}

Credit card payment (use an id from GET /api/creditcards/selectable):

{
  "customerId": 42,
  "invoiceNumber": "INV-1001",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 2,
  "creditCardId": 3
}

cURL example

curl -X POST "/api/receipts" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "customerId": 42,
    "invoiceNumber": "INV-1001",
    "amount": 113.0,
    "depositAccountNumber": "10600",
    "paymentMethod": 0
  }'

Success response

A successful request returns 201 Created with the posted receipt:

{
  "id": 88,
  "receiptNumber": "RCT-501",
  "customerId": 42,
  "date": "2026-09-29T00:00:00",
  "amount": 113.0,
  "depositAccountNumber": "10600",
  "paymentMethod": 0,
  "lines": [
    {
      "invoiceNumber": "INV-1001",
      "amount": 113.0
    }
  ]
}

Use the returned id as receiptId with GET /api/receipts/{receiptId} to retrieve the receipt later. After posting, GET /api/sales/{saleId} on the invoice should show a lower amountOwing and an updated paymentStatus (0 = unpaid, 1 = partial, 2 = paid).

Error response

If the request is invalid or Sage rejects the entry, the API returns 400 Bad Request:

{
  "title": "Validation failed",
  "status": 400,
  "detail": "Invoice INV-1001 was not found for customer 42.",
  "code": "INVOICE_NOT_FOUND",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Common causes include an invalid customerId, an invoice that is already paid or does not belong to the customer, an amount greater than amountOwing, a missing creditCardId when paymentMethod is CreditCard, or an unknown depositAccountNumber.

Next steps