API Endpoints

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

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

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

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

Update Upsell

PUT /upsells/:id

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

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

Bundles

List Bundles

GET /bundles

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

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

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

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

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

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

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

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

Update Settings

PATCH /settings

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

{
  "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