API 엔드포인트: CheckoutOS 문서

이 참조 문서는 사용 가능한 모든 CheckoutOS API 엔드포인트를 설명해요. 모든 엔드포인트는 인증이 필요하며 JSON 응답을 반환해요.

기본 URL

프로덕션: https://api.chargezen.com/v1
샌드박스: https://sandbox.api.chargezen.com/v1

추가 판매

추가 판매 목록 조회

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
  }
}

추가 판매 만들기

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 /upsells/:id

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

추가 판매 업데이트

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 /upsells/:id

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

번들

번들 목록 조회

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

번들 만들기

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
    }
  }'

분석

지표 조회

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 /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

실험

실험 목록 조회

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 /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
    }
  ]
}

주문

주문 조회

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

설정

설정 조회

GET /settings

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

설정 업데이트

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": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": [
      {
        "field": "discount.value",
        "message": "must be between 1 and 100"
      }
    ]
  }
}

일반적인 오류 코드

400 Bad Request — 잘못된 매개변수
401 Unauthorized — API 키가 없거나 유효하지 않아요
403 Forbidden — 권한이 부족해요
404 Not Found — 리소스를 찾을 수 없어요
429 Too Many Requests — 요청 한도에 도달했어요
500 Internal Server Error — 서버 오류

API 엔드포인트