Cancel Fulfillment

OverviewCopy Anchor Link

Cancels a claimed fulfillment and refunds the points to the member's wallet. Only active fulfillments can be cancelled.

This action is irreversible and will refund points according to the cancellation policy.

AuthenticationCopy Anchor Link

Requires a valid Clerk JWT token in the Authorization header.

Path ParametersCopy Anchor Link

curl -X POST "http://localhost:3000/v1/members/me/wallet/fulfillments/fulfill_550e8400-e29b-41d4-a716-446655440000/cancel" \
  -H "Authorization: Bearer YOUR_CLERK_JWT"

ResponseCopy Anchor Link

{
  "success": true,
  "message": "Fulfillment cancelled successfully"
}

Cancellable StatusesCopy Anchor Link

Only fulfillments with these statuses can be cancelled:

claimedCopy Anchor Link

• Timing: Just claimed, not yet processed
• Refund: Full point refund
• Impact: No impact on property

pending_approvalCopy Anchor Link

• Timing: Waiting for property approval
• Refund: Full point refund
• Impact: Notifies property of cancellation

modifiedCopy Anchor Link

• Timing: Property modified, awaiting member response
• Refund: Full point refund
• Impact: Notifies property of cancellation

approvedCopy Anchor Link

• Timing: Approved but not yet used
• Refund: Full point refund
• Impact: Notifies property, may affect relationship

Non-Cancellable StatusesCopy Anchor Link

These fulfillments cannot be cancelled:

fulfilledCopy Anchor Link

• Reason: Already redeemed/used
• Action: Contact support for exceptional cases

rejectedCopy Anchor Link

• Reason: Already declined by property
• Action: Points already refunded

cancelledCopy Anchor Link

• Reason: Already cancelled
• Action: No further action needed

expiredCopy Anchor Link

• Reason: Already expired
• Action: Points typically already refunded

Cancellation ProcessCopy Anchor Link

When a fulfillment is successfully cancelled:

1. Status Update: Fulfillment status changes to "cancelled"
2. Point Refund: Points are refunded to the member's wallet
3. Property Notification: Property is notified of cancellation (if applicable)
4. Code Invalidation: Verification codes become invalid
5. Transaction Record: Cancellation is logged for audit purposes

Refund DetailsCopy Anchor Link

• Point Type: Same asset type as originally charged (VALID/CREDIT)
• Amount: Full amount originally charged
• Timing: Immediate (synchronous with API call)
• Transaction: Creates a CREDIT transaction in wallet

Best PracticesCopy Anchor Link

Before CancellingCopy Anchor Link

1. Check Status: Ensure fulfillment can be cancelled
2. Review Terms: Some offers may have no-cancellation policies
3. Contact Property: For courtesy, especially if close to travel dates

After CancellingCopy Anchor Link

1. Confirm Refund: Check wallet balance to confirm points returned
2. Save Confirmation: Keep the success message for records
3. Property Follow-up: Contact property if needed to confirm cancellation

Error HandlingCopy Anchor Link

Common error scenarios:

Fulfillment Not Found (404)Copy Anchor Link

• Cause: Invalid fulfillment ID or not owned by member
• Solution: Verify the fulfillment ID and membership

Cannot Cancel (400)Copy Anchor Link

• Cause: Fulfillment status doesn't allow cancellation
• Solution: Check fulfillment status and cancellation rules

System Error (500)Copy Anchor Link

• Cause: Backend processing error
• Solution: Retry or contact support if persistent

Related EndpointsCopy Anchor Link

• Get Fulfillment - Check fulfillment status before cancelling
• Get Fulfillments - List all fulfillments
• Get Balance - Verify refund processed