Points de terminaison API : documentation CheckoutOS

Cette référence présente tous les points de terminaison disponibles de l’API CheckoutOS. Tous nécessitent une authentification et renvoient des réponses JSON.

URL de base

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

Ventes incitatives

Lister les ventes incitatives

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

Créer une vente incitative

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

Récupérer une vente incitative

GET /upsells/:id

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

Mettre à jour une vente incitative

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

Supprimer une vente incitative

DELETE /upsells/:id

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

Lots

Lister les lots

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

Créer un lot

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

Analyses

Récupérer les indicateurs

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

Récupérer un rapport

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

Expériences

Lister les expériences

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

Récupérer les résultats d’une expérience

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

Commandes

Récupérer une commande

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

Paramètres

Récupérer les paramètres

GET /settings

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

Mettre à jour les paramètres

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

Réponses d’erreur

Format des erreurs

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

Codes d’erreur courants

400 Bad Request — Paramètres non valides
401 Unauthorized — Clé API absente ou non valide
403 Forbidden — Autorisations insuffisantes
404 Not Found — Ressource introuvable
429 Too Many Requests — Limite de débit atteinte
500 Internal Server Error — Erreur du serveur

Sujets associés

Authentification

Gestion des clés API

Webhooks

Notifications d’événements en temps réel