Skip to main content
This page explains how Points handles order reversals after creation. There are two distinct operations:
OperationEndpointTypical use
CancelPOST /v1/orders/{uuid}/cancelThe order should no longer continue
RefundPOST /v1/orders/{uuid}/refundMoney/points need to be returned after settlement

​
Cancel an order

Use cancellation when the order should be stopped rather than financially reversed later. Example: 
curl -X POST https://api.papp.sa/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested cancellation" }'

​
Current behavior

  • validates merchant ownership of the order
  • rejects already-cancelled or already-refunded orders
  • defaults the reason to "Order cancelled via API" if omitted
  • emits webhook event cancelled

​
Refund an order

Use refund after an order is already settled and value must be returned. Example full refund: 
curl -X POST https://api.papp.sa/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/refund \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Example partial refund: 
curl -X POST https://api.papp.sa/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/refund \
  -H "x-api-key: $POINTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25.00,
    "reason": "One line item returned"
  }'

​
Current behavior

  • supports both full and partial refunds
  • emits webhook event refunded
  • updates order_status to fully_refunded or partially_refunded

​
How Points value is reversed

​
Replacing (redeem) orders

For a redeem checkout, refunding reverses the redeemed value and updates the order status accordingly.

​
Earning orders

For an earning order, refunding reverses previously awarded points. In partial refunds, the backend calculates the proportional points to reverse and includes remaining amounts in the refund payload used internally.

​
Auto-refund edge case

There is also an internal system event called auto_refunded. This can occur when the backend automatically reverses a replacing order because an expected transaction record was missing during reconciliation. Integrators should treat it as a refund-class terminal state and handle it in webhook consumers.
If the order should simply stop and has not entered your final fulfilment path, cancel is usually cleaner than refund.
If value was already settled, use the refund endpoint so Points can properly reverse the financial and loyalty effects.
Even when not required, always send a human-readable reason so support teams can reconcile merchant actions against webhook history.

​
Webhooks you should expect

ActionWebhook
Cancelcancelled
Refundrefunded
Internal automatic reversalauto_refunded

​
Next

Order Lifecycle

See where cancellation and refund fit in the state machine.

Webhook Events

Payload examples for cancelled, refunded, and related events.