### Create Product Entry (Bash)

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Provides an example of creating a new product with details such as name, description, pricing, and recurring settings. Supports physical goods, digital downloads, and services.

```bash
# Create a product
curl -X POST https://api.surecart.com/v1/products \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Membership",
    "description": "Access to all premium features",
    "price": 2999,
    "currency": "usd",
    "recurring": {
      "interval": "month",
      "interval_count": 1
    },
    "active": true
  }'
```

--------------------------------

### Authentication Example

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

All requests must include valid API credentials passed as a Bearer token in the Authorization header to access protected resources.

```APIDOC
## GET /v1/customers

### Description
This endpoint demonstrates how to authenticate API requests using a bearer token. It shows an example request to the customers endpoint with the necessary Authorization header.

### Method
GET

### Endpoint
https://api.surecart.com/v1/customers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.surecart.com/v1/customers \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json"
```

### Response
#### Success Response (200)
- **object** (string) - Indicates the type of the response object, typically 'list'.
- **data** (array) - An array containing the list of customer objects.
- **has_more** (boolean) - Indicates if there are more results available.

#### Response Example
```json
{
  "object": "list",
  "data": [...],
  "has_more": false
}
```
```

--------------------------------

### GET /v1/customers/{id}

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Fetch an existing customer by their unique identifier. Returns the full customer object including all associated metadata.

```APIDOC
## GET /v1/customers/{id}

### Description
Retrieves the details of a specific customer using their unique ID.

### Method
GET

### Endpoint
https://api.surecart.com/v1/customers/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the customer to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl https://api.surecart.com/v1/customers/cus_abc123 \
  -H "Authorization: Bearer sc_live_abc123def456"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the customer.
- **object** (string) - The type of the object, 'customer'.
- **email** (string) - The email address of the customer.
- **name** (string) - The full name of the customer.
- **phone** (string) - The phone number of the customer.
- **created_at** (integer) - Unix timestamp of when the customer was created.
- **updated_at** (integer) - Unix timestamp of when the customer was last updated.
- **metadata** (object) - Custom data associated with the customer.

#### Response Example
```json
{
  "id": "cus_abc123",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1234567890",
  "created_at": 1678901234,
  "updated_at": 1678901234,
  "metadata": {}
}
```
```

--------------------------------

### GET /v1/orders

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Retrieves a paginated list of orders. Supports filtering by customer, status, or date range, and uses cursor-based pagination.

```APIDOC
## GET /v1/orders

### Description
Retrieves a paginated list of orders. Supports filtering by customer, status, or date range, and uses cursor-based pagination.

### Method
GET

### Endpoint
https://api.surecart.com/v1/orders

### Parameters
#### Query Parameters
- **customer** (string) - Optional - Filter orders by customer ID.
- **status** (string) - Optional - Filter orders by status (e.g., 'paid', 'pending').
- **created_after** (integer) - Optional - Filter orders created after this Unix timestamp.
- **created_before** (integer) - Optional - Filter orders created before this Unix timestamp.
- **limit** (integer) - Optional - The maximum number of orders to return per page (default 10).
- **starting_after** (string) - Optional - An order ID to start the list after (for pagination).
- **ending_before** (string) - Optional - An order ID to end the list before (for pagination).

### Request Example
```bash
curl "https://api.surecart.com/v1/orders?customer=cus_abc123&limit=10"
  -H "Authorization: Bearer sc_live_abc123def456"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object, 'list'.
- **data** (array) - An array of order objects.
  - **id** (string) - The order ID.
  - **object** (string) - The type of object, 'order'.
  - **customer** (string) - The customer ID.
  - **amount** (integer) - The order amount.
  - **currency** (string) - The currency of the order.
  - **status** (string) - The status of the order.
  - **created_at** (integer) - Timestamp of when the order was created.
- **has_more** (boolean) - Indicates if there are more results available.
- **url** (string) - The API endpoint for this list.

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "ord_abc123",
      "object": "order",
      "customer": "cus_abc123",
      "amount": 5000,
      "currency": "usd",
      "status": "paid",
      "created_at": 1678901234
    }
  ],
  "has_more": false,
  "url": "/v1/orders"
}
```
```

--------------------------------

### POST /v1/products

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Create a new product with pricing, description, and inventory settings. Products can be physical goods, digital downloads, or services.

```APIDOC
## POST /v1/products

### Description
Creates a new product in SureCart. This endpoint allows you to define product details such as name, description, pricing, and recurrence settings.

### Method
POST

### Endpoint
https://api.surecart.com/v1/products

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - The name of the product.
- **description** (string) - Optional - A detailed description of the product.
- **price** (integer) - Required - The price of the product in the smallest currency unit (e.g., cents for USD).
- **currency** (string) - Required - The ISO currency code (e.g., 'usd').
- **recurring** (object) - Optional - Configuration for recurring products.
  - **interval** (string) - Required if recurring - The interval for recurrence ('day', 'week', 'month', 'year').
  - **interval_count** (integer) - Optional - The number of intervals between payments (defaults to 1).
- **active** (boolean) - Optional - Whether the product is active and available for sale (defaults to true).

### Request Example
```json
{
  "name": "Premium Membership",
  "description": "Access to all premium features",
  "price": 2999,
  "currency": "usd",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "active": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created product.
- **object** (string) - The type of the object, 'product'.
- **name** (string) - The name of the product.
- **description** (string) - The description of the product.
- **price** (integer) - The price of the product.
- **currency** (string) - The currency of the price.
- **recurring** (object) - Configuration for recurring products.
- **active** (boolean) - Whether the product is active.
- **created_at** (integer) - Unix timestamp of when the product was created.

#### Response Example
```json
{
  "id": "prod_xyz789",
  "object": "product",
  "name": "Premium Membership",
  "description": "Access to all premium features",
  "price": 2999,
  "currency": "usd",
  "recurring": {
    "interval": "month",
    "interval_count": 1
  },
  "active": true,
  "created_at": 1678901234
}
```
```

--------------------------------

### Initialize Checkout Session (Bash)

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Demonstrates the process of initiating a checkout session for payment processing. This handles the entire payment flow, including collecting payment methods and completing orders.

```bash
# Create checkout session
curl -X POST https://api.surecart.com/v1/checkout/sessions \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [
      {
        "price": "price_abc123",
        "quantity": 1
      }
    ],
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel",
    "customer_email": "customer@example.com",
    "metadata": {
      "order_id": "ORD-12345"
    }
  }'
```

--------------------------------

### Use Cases and Integration Patterns

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Overview of common use cases and integration patterns for the SureCart API, including direct API integration, webhook-based event processing, and hosted checkout pages.

```APIDOC
## Use Cases and Integration Patterns

The SureCart API is designed for building complete e-commerce solutions ranging from simple payment processing to complex subscription management systems. Common use cases include one-time product sales, recurring subscription services, digital product delivery, membership sites, and SaaS billing.

Integration typically follows a few standard patterns:

*   **Direct API Integration**: For custom storefronts where you maintain full control over the user experience.
*   **Webhook-based Event Processing**: For handling asynchronous events like payment confirmations and subscription renewals.
*   **Hosted Checkout Pages**: For rapid implementation with minimal code.

Most implementations combine multiple endpoints to create complete workflows, such as creating a customer, initiating a checkout session, processing payment, and then listening for webhook events to fulfill orders.
```

--------------------------------

### Create Subscription with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Establishes a recurring subscription for a customer using a specified pricing plan and payment method. Supports an optional trial period. Returns the subscription details, including its status and billing cycle dates.

```bash
# Create subscription
curl -X POST https://api.surecart.com/v1/subscriptions \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_abc123",
    "price": "price_monthly_premium",
    "payment_method": "pm_card_visa",
    "trial_period_days": 14,
    "metadata": {
      "plan": "premium"
    }
  }'
```

--------------------------------

### Create Customer Record (Bash)

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Shows how to create a new customer record via the API, including contact information and optional metadata. Returns the newly created customer object with its unique ID.

```bash
# Create a new customer
curl -X POST https://api.surecart.com/v1/customers \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "name": "John Doe",
    "phone": "+1234567890",
    "metadata": {
      "source": "website",
      "campaign": "spring_sale"
    }
  }'
```

--------------------------------

### Configure Webhook Endpoint with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Sets up a webhook endpoint to receive real-time notifications from SureCart. Specifies the URL for receiving events and the types of events to subscribe to. Returns the configuration details of the webhook endpoint.

```bash
# Create webhook endpoint
curl -X POST https://api.surecart.com/v1/webhook_endpoints \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/surecart",
    "enabled_events": [
      "payment.succeeded",
      "subscription.created",
      "subscription.canceled"
    ],
    "metadata": {
      "environment": "production"
    }
  }'
```

--------------------------------

### Process Payment with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Initiates a payment transaction through the SureCart API. Requires customer, payment method, amount, and currency details. Returns the payment status and details upon successful processing.

```bash
curl -X POST https://api.surecart.com/v1/payments \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "customer": "cus_abc123",
    "payment_method": "pm_card_visa",
    "description": "Payment for order #12345",
    "metadata": {
      "order_id": "12345"
    }
  }'
```

--------------------------------

### POST /v1/customers

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Create a new customer record with contact information and optional metadata. Returns the created customer object with a unique identifier.

```APIDOC
## POST /v1/customers

### Description
Creates a new customer record in SureCart. You can provide the customer's email, name, phone number, and any additional metadata.

### Method
POST

### Endpoint
https://api.surecart.com/v1/customers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Required - The email address of the customer.
- **name** (string) - Optional - The full name of the customer.
- **phone** (string) - Optional - The phone number of the customer.
- **metadata** (object) - Optional - Key-value pairs for custom data associated with the customer.

### Request Example
```json
{
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1234567890",
  "metadata": {
    "source": "website",
    "campaign": "spring_sale"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created customer.
- **object** (string) - The type of the object, 'customer'.
- **email** (string) - The email address of the customer.
- **name** (string) - The full name of the customer.
- **phone** (string) - The phone number of the customer.
- **created_at** (integer) - Unix timestamp of when the customer was created.
- **metadata** (object) - Custom data associated with the customer.

#### Response Example
```json
{
  "id": "cus_abc123",
  "object": "customer",
  "email": "customer@example.com",
  "name": "John Doe",
  "phone": "+1234567890",
  "created_at": 1678901234,
  "metadata": {
    "source": "website",
    "campaign": "spring_sale"
  }
}
```
```

--------------------------------

### POST /v1/subscriptions

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Creates a new recurring subscription for a customer, linked to a specific price plan. Allows for trial periods and metadata.

```APIDOC
## POST /v1/subscriptions

### Description
Creates a new recurring subscription for a customer, linked to a specific price plan. Allows for trial periods and metadata.

### Method
POST

### Endpoint
https://api.surecart.com/v1/subscriptions

### Parameters
#### Request Body
- **customer** (string) - Required - The ID of the customer subscribing.
- **price** (string) - Required - The ID of the price plan for the subscription.
- **payment_method** (string) - Required - The ID of the payment method to use for recurring charges.
- **trial_period_days** (integer) - Optional - The number of days for the trial period.
- **metadata** (object) - Optional - Key-value pairs for additional information.

### Request Example
```json
{
  "customer": "cus_abc123",
  "price": "price_monthly_premium",
  "payment_method": "pm_card_visa",
  "trial_period_days": 14,
  "metadata": {
    "plan": "premium"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the subscription.
- **object** (string) - The type of object, 'subscription'.
- **customer** (string) - The ID of the customer.
- **status** (string) - The current status of the subscription (e.g., 'trialing').
- **current_period_start** (integer) - Timestamp for the start of the current billing period.
- **current_period_end** (integer) - Timestamp for the end of the current billing period.
- **trial_end** (integer) - Timestamp for the end of the trial period, if applicable.
- **price** (string) - The ID of the price plan.
- **metadata** (object) - Any metadata associated with the subscription.

#### Response Example
```json
{
  "id": "sub_abc123",
  "object": "subscription",
  "customer": "cus_abc123",
  "status": "trialing",
  "current_period_start": 1678901234,
  "current_period_end": 1680110834,
  "trial_end": 1680110834,
  "price": "price_monthly_premium",
  "metadata": {
    "plan": "premium"
  }
}
```
```

--------------------------------

### SureCart API Overview

Source: https://developer.surecart.com/reference/introduction/index

General information about the SureCart REST API, including its organization around REST principles, predictable URLs, request/response formats, and authentication methods.

```APIDOC
## SureCart API Overview

### Description
The SureCart API is organized around REST principles. It features predictable, resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and utilizes standard HTTP response codes, authentication, and verbs.

Key characteristics include:
- **RESTful Organization**: Resources are exposed via intuitive URLs.
- **Request Format**: Accepts form-encoded request bodies.
- **Response Format**: Returns JSON-encoded responses.
- **HTTP Standards**: Uses standard HTTP response codes, authentication, and verbs.

**Important Note**: The SureCart API does not support bulk updates; each request operates on a single object.
```

--------------------------------

### Retrieve Customer Details by ID (Bash)

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Explains how to fetch an existing customer's details using their unique identifier. The response includes all associated metadata for the specified customer.

```bash
# Get customer details
curl https://api.surecart.com/v1/customers/cus_abc123 \
  -H "Authorization: Bearer sc_live_abc123def456"
```

--------------------------------

### POST /v1/checkout/sessions

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Initialize a checkout session for customer payment processing. The session handles the complete payment flow including payment method collection and order completion.

```APIDOC
## POST /v1/checkout/sessions

### Description
Initiates a new checkout session for processing customer payments. This endpoint is used to set up the payment process for one or more items, defining success and cancel URLs, and associating it with a customer.

### Method
POST

### Endpoint
https://api.surecart.com/v1/checkout/sessions

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **line_items** (array) - Required - An array of items to be included in the checkout session.
  - **price** (string) - Required - The ID of the price for the item.
  - **quantity** (integer) - Required - The quantity of the item.
- **success_url** (string) - Required - The URL to redirect the customer to upon successful payment.
- **cancel_url** (string) - Required - The URL to redirect the customer to if they cancel the checkout.
- **customer_email** (string) - Optional - The email address of the customer. If not provided, the customer can enter it during checkout.
- **metadata** (object) - Optional - Key-value pairs for custom data related to the session.

### Request Example
```json
{
  "line_items": [
    {
      "price": "price_abc123",
      "quantity": 1
    }
  ],
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "customer_email": "customer@example.com",
  "metadata": {
    "order_id": "ORD-12345"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the checkout session.
- **object** (string) - The type of the object, 'checkout_session'.
- **url** (string) - The URL where the customer can complete the checkout.
- **status** (string) - The current status of the checkout session (e.g., 'open').
- **line_items** (array) - The items included in the session.
- **success_url** (string) - The URL for successful payment redirection.
- **cancel_url** (string) - The URL for cancelled checkout redirection.
- **expires_at** (integer) - Unix timestamp indicating when the checkout session expires.

#### Response Example
```json
{
  "id": "checkout_sess_abc123",
  "object": "checkout_session",
  "url": "https://checkout.surecart.com/pay/cs_abc123",
  "status": "open",
  "line_items": [...],
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "expires_at": 1678987634
}
```
```

--------------------------------

### Handle SureCart API Errors

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Demonstrates how to handle potential errors when interacting with the SureCart API. The API uses standard HTTP status codes and returns detailed error objects with codes and messages for troubleshooting.

```bash
# Example error response
curl -X POST https://api.surecart.com/v1/payments \
  -H "Authorization: Bearer sc_live_invalid_key" \
  -H "Content-Type: application/json" \
  -d '{}'
```

--------------------------------

### POST /v1/payments

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Processes a single payment for a given amount, currency, customer, and payment method. Supports metadata for additional context.

```APIDOC
## POST /v1/payments

### Description
Processes a single payment for a given amount, currency, customer, and payment method. Supports metadata for additional context.

### Method
POST

### Endpoint
https://api.surecart.com/v1/payments

### Parameters
#### Request Body
- **amount** (integer) - Required - The payment amount in the smallest currency unit (e.g., cents).
- **currency** (string) - Required - The three-letter ISO currency code (e.g., 'usd').
- **customer** (string) - Required - The ID of the customer making the payment.
- **payment_method** (string) - Required - The ID of the payment method to use.
- **description** (string) - Optional - A description for the payment.
- **metadata** (object) - Optional - Key-value pairs for additional information.

### Request Example
```json
{
  "amount": 5000,
  "currency": "usd",
  "customer": "cus_abc123",
  "payment_method": "pm_card_visa",
  "description": "Payment for order #12345",
  "metadata": {
    "order_id": "12345"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payment.
- **object** (string) - The type of object, 'payment'.
- **amount** (integer) - The payment amount.
- **currency** (string) - The currency of the payment.
- **status** (string) - The status of the payment (e.g., 'succeeded').
- **customer** (string) - The ID of the customer.
- **payment_method** (string) - The ID of the payment method used.
- **created_at** (integer) - Timestamp of when the payment was created.
- **metadata** (object) - Any metadata associated with the payment.

#### Response Example
```json
{
  "id": "pay_abc123",
  "object": "payment",
  "amount": 5000,
  "currency": "usd",
  "status": "succeeded",
  "customer": "cus_abc123",
  "payment_method": "pm_card_visa",
  "created_at": 1678901234,
  "metadata": {
    "order_id": "12345"
  }
}
```
```

--------------------------------

### POST /v1/webhook_endpoints

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Configures webhook endpoints to receive real-time notifications about events. Supports specifying enabled events and metadata.

```APIDOC
## POST /v1/webhook_endpoints

### Description
Configures webhook endpoints to receive real-time notifications about events. Supports specifying enabled events and metadata.

### Method
POST

### Endpoint
https://api.surecart.com/v1/webhook_endpoints

### Parameters
#### Request Body
- **url** (string) - Required - The URL to which webhook events will be sent.
- **enabled_events** (array) - Optional - An array of event types to subscribe to (e.g., 'payment.succeeded'). If omitted, all events are sent.
- **metadata** (object) - Optional - Key-value pairs for additional information.

### Request Example
```json
{
  "url": "https://example.com/webhooks/surecart",
  "enabled_events": [
    "payment.succeeded",
    "subscription.created",
    "subscription.canceled"
  ],
  "metadata": {
    "environment": "production"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the webhook endpoint.
- **object** (string) - The type of object, 'webhook_endpoint'.
- **url** (string) - The configured URL for the webhook.
- **enabled_events** (array) - The list of event types that trigger webhooks.
- **status** (string) - The status of the webhook endpoint (e.g., 'enabled').
- **created_at** (integer) - Timestamp of when the webhook endpoint was created.

#### Response Example
```json
{
  "id": "we_abc123",
  "object": "webhook_endpoint",
  "url": "https://example.com/webhooks/surecart",
  "enabled_events": [
    "payment.succeeded",
    "subscription.created",
    "subscription.canceled"
  ],
  "status": "enabled",
  "created_at": 1678901234
}
```

### Example webhook payload received
```json
{
  "id": "evt_abc123",
  "object": "event",
  "type": "payment.succeeded",
  "created": 1678901234,
  "data": {
    "object": {
      "id": "pay_abc123",
      "amount": 5000,
      "currency": "usd",
      "customer": "cus_abc123"
    }
  }
}
```
```

--------------------------------

### Authenticate API Request with Bearer Token (Bash)

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Demonstrates how to authenticate an API request using a bearer token in the Authorization header. Requires a valid API key for accessing protected resources.

```bash
# Authenticate API request with bearer token
curl https://api.surecart.com/v1/customers \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json"
```

--------------------------------

### POST /v1/refunds

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Issues a full or partial refund for a completed payment. Refunds are processed immediately and credited to the customer's original payment method.

```APIDOC
## POST /v1/refunds

### Description
Issues a full or partial refund for a completed payment. Refunds are processed immediately and credited to the customer's original payment method.

### Method
POST

### Endpoint
https://api.surecart.com/v1/refunds

### Parameters
#### Request Body
- **payment** (string) - Required - The ID of the payment to refund.
- **amount** (integer) - Optional - The amount to refund in the smallest currency unit. If omitted, the full payment amount is refunded.
- **reason** (string) - Optional - The reason for the refund (e.g., 'customer_request', 'dispute').
- **metadata** (object) - Optional - Key-value pairs for additional information.

### Request Example
```json
{
  "payment": "pay_abc123",
  "amount": 2500,
  "reason": "customer_request",
  "metadata": {
    "support_ticket": "TICKET-789"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the refund.
- **object** (string) - The type of object, 'refund'.
- **payment** (string) - The ID of the payment that was refunded.
- **amount** (integer) - The amount refunded.
- **status** (string) - The status of the refund (e.g., 'succeeded').
- **reason** (string) - The reason for the refund.
- **created_at** (integer) - Timestamp of when the refund was created.
- **metadata** (object) - Any metadata associated with the refund.

#### Response Example
```json
{
  "id": "ref_abc123",
  "object": "refund",
  "payment": "pay_abc123",
  "amount": 2500,
  "status": "succeeded",
  "reason": "customer_request",
  "created_at": 1678901234,
  "metadata": {
    "support_ticket": "TICKET-789"
  }
}
```
```

--------------------------------

### Refund Payment with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Issues a refund for a specified payment, either in full or partially. Requires the payment ID and the refund amount. Optional fields include reason and metadata. Returns the refund status and details.

```bash
# Create refund
curl -X POST https://api.surecart.com/v1/refunds \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "payment": "pay_abc123",
    "amount": 2500,
    "reason": "customer_request",
    "metadata": {
      "support_ticket": "TICKET-789"
    }
  }'
```

--------------------------------

### List Orders with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Retrieves a paginated list of orders from the SureCart API. Supports filtering by customer ID and limiting the number of results. Uses cursor-based pagination for efficient handling of large datasets.

```bash
# List orders with filters
curl "https://api.surecart.com/v1/orders?customer=cus_abc123&limit=10" \
  -H "Authorization: Bearer sc_live_abc123def456"
```

--------------------------------

### Error Responses

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

This section details common error responses returned by the SureCart API, including Unauthorized, Bad Request, and Payment Required errors, along with their specific error codes and messages.

```APIDOC
## Error Responses

### Response (401 Unauthorized)

This error occurs when an invalid API key is provided.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "param": null
  }
}
```

### Response (400 Bad Request)

This error indicates a missing required parameter in the request.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: amount",
    "param": "amount"
  }
}
```

### Response (402 Payment Required)

This error is returned when a payment is declined, for instance, due to insufficient funds.

```json
{
  "error": {
    "type": "payment_error",
    "code": "card_declined",
    "message": "Your card was declined",
    "decline_code": "insufficient_funds",
    "param": "payment_method"
  }
}
```
```

--------------------------------

### Error Handling

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

The SureCart API utilizes standard HTTP status codes for indicating request outcomes and returns detailed error objects with machine-readable codes and human-friendly messages.

```APIDOC
## Error Handling

### Description
The SureCart API utilizes standard HTTP status codes for indicating request outcomes and returns detailed error objects with machine-readable codes and human-friendly messages.

### Response Codes
- **2xx**: Success
- **4xx**: Client Error (e.g., invalid request, authentication failure)
- **5xx**: Server Error

### Error Response Body
```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter 'amount' is missing."
  }
}
```

### Example Error Scenario (Invalid API Key)
```bash
# Example error response
curl -X POST https://api.surecart.com/v1/payments \
  -H "Authorization: Bearer sc_live_invalid_key" \
  -H "Content-Type: application/json" \
  -d '{}'

# Expected Error Response (e.g., 401 Unauthorized)
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided: sc_live_invalid_key"
  }
}
```
```

--------------------------------

### Cancel Subscription with SureCart API

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Cancels an existing subscription, either immediately or at the end of the current billing cycle. Requires the subscription ID. Returns the updated subscription object reflecting the cancellation status.

```bash
# Cancel subscription
curl -X POST https://api.surecart.com/v1/subscriptions/sub_abc123/cancel \
  -H "Authorization: Bearer sc_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true
  }'
```

--------------------------------

### POST /v1/subscriptions/{subscription_id}/cancel

Source: https://context7.com/context7/developer_surecart_com-reference-introduction/llms.txt

Cancels an active subscription, either immediately or at the end of the current billing period. Returns the updated subscription object.

```APIDOC
## POST /v1/subscriptions/{subscription_id}/cancel

### Description
Cancels an active subscription, either immediately or at the end of the current billing period. Returns the updated subscription object.

### Method
POST

### Endpoint
https://api.surecart.com/v1/subscriptions/{subscription_id}/cancel

### Parameters
#### Path Parameters
- **subscription_id** (string) - Required - The ID of the subscription to cancel.

#### Request Body
- **cancel_at_period_end** (boolean) - Optional - If true, cancellation occurs at the end of the current billing period. Defaults to false (immediate cancellation).

### Request Example
```json
{
  "cancel_at_period_end": true
}
```

### Response
#### Success Response (200)
- **id** (string) - The subscription ID.
- **object** (string) - The type of object, 'subscription'.
- **status** (string) - The status of the subscription (e.g., 'active').
- **cancel_at_period_end** (boolean) - Indicates if cancellation is scheduled for the end of the period.
- **canceled_at** (integer) - Timestamp of when the subscription was canceled, if applicable.
- **current_period_end** (integer) - Timestamp for the end of the current billing period.

#### Response Example
```json
{
  "id": "sub_abc123",
  "object": "subscription",
  "status": "active",
  "cancel_at_period_end": true,
  "canceled_at": 1678901234,
  "current_period_end": 1681493634
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.