​

Refund a Checkout Session

​

Endpoint

• Endpoint: POST /v1/checkouts/{checkoutId}/refund
• Description: Issue a refund for a specific checkout session.
• Path Parameters:
  • checkoutId (string, required): The unique identifier of the checkout session to refund.
• Request Body:
  Copy

  {
    "amount": 1000,
    "currency": "usd",
    "reason": "customer_request"
  }
  

• Response:
  Copy

  {
    "id": "cs_test_123",
    "amount": 1000,
    "currency": "usd",
    "status": "refunded",
    "created_at": "2024-01-01T12:00:00Z",
    "customer_id": "cus_456"
  }
  

​

Parameters

• checkoutId (string, required): The unique identifier of the checkout session to refund.
• amount (integer, required): The amount to refund in the smallest currency unit (e.g., cents for USD).
• currency (string, required): The currency code (e.g., “usd”).
• reason (string, optional): The reason for the refund (e.g., “customer_request”, “fraudulent”).

​

Example Request

curl -X POST https://api.example.com/v1/checkouts/cs_test_123/refund \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "usd",
    "reason": "customer_request"
  }'

​

Example Response

{
  "id": "cs_test_123",
  "amount": 1000,
  "currency": "usd",
  "status": "refunded",
  "created_at": "2024-01-01T12:00:00Z",
  "customer_id": "cus_456"
}

​

Notes

• Ensure that the checkout session exists and is eligible for a refund before issuing the request.
• The response includes the updated status of the checkout session after the refund is processed.

​

Errors

• 404 Not Found: The specified checkout session does not exist.
• 400 Bad Request: Invalid request parameters or refund amount exceeds the original payment.
• 401 Unauthorized: Invalid or missing API key.

​

See Also

• Create a Checkout Session
• Retrieve a Checkout Session
• Search Checkout Sessions