Canonical URL: https://chargezen.com/docs/checkoutos/api/endpoints

# API Endpoints

Complete reference for CheckoutOS API endpoints

Last updated: 2025-01-16

This reference documents all available CheckoutOS API endpoints. All endpoints require authentication and return JSON responses.

##### Base URL

Production: `https://api.chargezen.com/v1`  
Sandbox: `https://sandbox.api.chargezen.com/v1`

## Upsells

### List Upsells

GET /upsells

```bash
curl -X GET "https://api.chargezen.com/v1/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "upsell_123",
      "name": "Premium Add-On",
      "status": "active",
      "product_id": "prod_abc",
      "discount_type": "percentage",
      "discount_value": 15,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45
  }
}
```

### Create Upsell

POST /upsells

```bash
curl -X POST "https://api.chargezen.com/v1/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Add-On",
    "product_id": "prod_abc",
    "trigger_products": ["prod_xyz"],
    "discount": {
      "type": "percentage",
      "value": 15
    },
    "placement": "post_purchase",
    "status": "active"
  }'
```

### Get Upsell

GET /upsells/:id

```bash
curl -X GET "https://api.chargezen.com/v1/upsells/upsell_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update Upsell

PUT /upsells/:id

```bash
curl -X PUT "https://api.chargezen.com/v1/upsells/upsell_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": {
      "type": "percentage",
      "value": 20
    }
  }'
```

### Delete Upsell

DELETE /upsells/:id

```bash
curl -X DELETE "https://api.chargezen.com/v1/upsells/upsell_123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Bundles

### List Bundles

GET /bundles

```bash
curl -X GET "https://api.chargezen.com/v1/bundles" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Query parameters:
# ?type=fixed|mix_match|build_a_box
# ?status=active|draft|archived
# ?page=1&per_page=20
```

### Create Bundle

POST /bundles

```bash
curl -X POST "https://api.chargezen.com/v1/bundles" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Skincare Starter Kit",
    "type": "fixed",
    "products": [
      { "product_id": "prod_cleanser", "quantity": 1 },
      { "product_id": "prod_toner", "quantity": 1 },
      { "product_id": "prod_moisturizer", "quantity": 1 }
    ],
    "pricing": {
      "type": "percentage_off",
      "value": 20
    }
  }'
```

## Analytics

### Get Metrics

GET /analytics/metrics

```bash
curl -X GET "https://api.chargezen.com/v1/analytics/metrics?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "total_revenue": 127450.00,
    "checkoutos_revenue": 28190.00,
    "average_order_value": 94.50,
    "upsell_acceptance_rate": 0.184,
    "orders_with_upsells": 782,
    "total_orders": 4250
  },
  "period": {
    "start": "2025-01-01",
    "end": "2025-01-31"
  }
}
```

### Get Report

GET /analytics/reports/:type

```bash
curl -X GET "https://api.chargezen.com/v1/analytics/reports/upsell_performance?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Available report types:
# - upsell_performance
# - bundle_performance
# - revenue_attribution
# - conversion_funnel
```

## Experiments

### List Experiments

GET /experiments

```bash
curl -X GET "https://api.chargezen.com/v1/experiments" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Query parameters:
# ?status=running|completed|draft
# ?page=1&per_page=20
```

### Get Experiment Results

GET /experiments/:id/results

```bash
curl -X GET "https://api.chargezen.com/v1/experiments/exp_123/results" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "experiment_id": "exp_123",
  "status": "significant",
  "winner": "variant_a",
  "variants": [
    {
      "name": "control",
      "visitors": 5000,
      "conversions": 250,
      "conversion_rate": 0.05
    },
    {
      "name": "variant_a",
      "visitors": 5000,
      "conversions": 325,
      "conversion_rate": 0.065,
      "lift": 0.30,
      "p_value": 0.001
    }
  ]
}
```

## Orders

### Get Order

GET /orders/:id

```bash
curl -X GET "https://api.chargezen.com/v1/orders/order_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response includes CheckoutOS-specific data:
{
  "order_id": "order_123",
  "shopify_order_id": "5678901234",
  "checkoutos_data": {
    "upsells_accepted": ["upsell_abc"],
    "bundles_purchased": [],
    "checkoutos_revenue": 24.99,
    "experiment_variant": "variant_a"
  }
}
```

## Settings

### Get Settings

GET /settings

```bash
curl -X GET "https://api.chargezen.com/v1/settings" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Update Settings

PATCH /settings

```bash
curl -X PATCH "https://api.chargezen.com/v1/settings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upsells": {
      "default_placement": "post_purchase",
      "max_offers_per_checkout": 2
    }
  }'
```

## Error Responses

Error Format

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": [
      {
        "field": "discount.value",
        "message": "must be between 1 and 100"
      }
    ]
  }
}
```

#### Common Error Codes

*   400 Bad Request — Invalid parameters
*   401 Unauthorized — Missing or invalid API key
*   403 Forbidden — Insufficient permissions
*   404 Not Found — Resource not found
*   429 Too Many Requests — Rate limited
*   500 Internal Server Error — Server error

## Related Topics

[

### Authentication

API key management

Learn more



](https://chargezen.com/docs/checkoutos/api/authentication)[

### Webhooks

Real-time event notifications

Learn more



](https://chargezen.com/docs/checkoutos/api/webhooks)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)