Process Transaction Refund

Process a full refund for a customer purchase transaction. Use this endpoint when a customer returns items or requests a refund for their purchase.

Development Environment

For testing and development, prepend the base URL: https://dev.api.grandshifts.com

POST/pos/v1/invoices/{invoiceNumber}/refund

Refund Process

When you process a refund, the system will:

Verify the transaction is in a refundable status
Automatically reverse any cashback credits given to the customer
Update the transaction status to REFUNDED
Record the refund reason for audit purposes

Important Constraints

Refund Rules

Transaction must be in APPROVED, PAID, or CASHBACK_PROCESSED status
Cashback is automatically reversed from the customer's wallet
Partial refunds are NOT supported at this time - only full refunds
Refunds cannot be processed for transactions that have already been refunded or cancelled
The reason field must be between 5 and 500 characters

Path Parameters

Property	Type	Description
invoiceNumberRequired	string	The unique invoice number of the transaction to refund. Example: INV-2024-001234

Request Body

Property	Type	Description
reasonRequired	string	Reason for the refund (required for audit). Min: 5 characters \| Max: 500 characters Example: Customer returned item
metadata	object	Additional metadata about the refund. Example: { "refundTransactionId": "REF-001", "authorizedBy": "manager123" }

Request Example

{
  "reason": "Customer returned item",
  "metadata": {
    "refundTransactionId": "REF-001",
    "authorizedBy": "manager123"
  }
}

Example Request

cURL

curl -X 'POST' \
  'https://dev.api.grandshifts.com/pos/v1/invoices/INV-2024-001234/refund' \
  -H 'accept: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "Customer returned item",
    "metadata": {
      "refundTransactionId": "REF-001",
      "authorizedBy": "manager123"
    }
  }'

Response Schema

Property	Type	Description
invoiceIdRequired	number	Internal invoice ID. Example: 12345
invoiceNumberRequired	string	Invoice number. Example: INV-2024-001234
statusRequired	string	Updated status after refund. Example: REFUNDED
refundedAtRequired	string	Timestamp when refund was processed. Example: 2024-01-15T11:00:00Z
refundReasonRequired	string	Refund reason. Example: Customer returned item
refundedAmountRequired	number	Refunded amount (grand total). Example: 977.5
cashbackReversed	number	Cashback amount that was reversed from the customer's wallet. Example: 48.88
messageRequired	string	Status message. Example: Refund processed successfully. Cashback has been reversed.

Success Response (200 OK)

Refund processed successfully. Customer cashback has been reversed.

Response

{
  "invoiceId": 12345,
  "invoiceNumber": "INV-2024-001234",
  "status": "REFUNDED",
  "refundedAt": "2024-01-15T11:00:00Z",
  "refundReason": "Customer returned item",
  "refundedAmount": 977.5,
  "cashbackReversed": 48.88,
  "message": "Refund processed successfully. Cashback has been reversed."
}

Error Responses

400Bad Request

Refund cannot be processed. Transaction may be in an invalid status (already refunded, cancelled, or pending approval).

Also returned if the reason field is missing, less than 5 characters, or more than 500 characters.

401Unauthorized

Invalid or missing API key. Ensure you include a valid x-api-key header.

404Not Found

Transaction not found with the provided invoice number. Ensure the invoiceNumber matches exactly what was used during submission.