Skip to main content

Quick Start & Examples

Get up and running with Reachu API in minutes. This guide walks you through a complete ecommerce flow from browsing products to completing a purchase.

Demo API Key​

Start testing immediately with our demo API key:

CFN9A5W-V74MACA-K2XD00S-W2D42D3

This gives you access to sample products and a complete test environment.

Complete Ecommerce Flow​

Follow this step-by-step guide to understand how Reachu API works:

Step 1: Explore Your Channel​

First, understand what products are available in your channel and verify your channel configuration.

Get Channel Information:

GET
/api/channel/me

Get your channel configuration and available features

Browse Available Products:

GET
/api/channel/products?currency=NOK

Get all products available in your channel with Norwegian pricing

Step 2: Create a Shopping Cart​

Every purchase starts with creating a cart. This is where customers will add products.

POST
/api/cart

Create a new shopping cart for your customer

{
  "customer_session_id": "demo-session-001",
  "currency": "NOK"
}

What happens here:

  • Creates a unique cart for the customer session
  • Sets the currency for all prices
  • Returns a cart_id you'll use for all cart operations

Step 3: Add Products to Cart​

Now add products to the cart. Use a product ID from Step 1's response.

POST
/api/cart/{cartId}/item/add

Add products to the cart (replace {cartId} with actual ID from Step 2)

{
  "line_items": [
    {
      "product_id": 68787,
      "quantity": 1
    }
  ]
}

Important notes:

  • Replace {cartId} with the actual cart ID from Step 2
  • Use real product IDs from your channel products
  • You can add multiple products in one request

Step 4: Review Cart Contents​

Check what's in the cart and get updated pricing including taxes and shipping.

GET
/api/cart/{cartId}

Get complete cart details with totals and line items

Step 5: Set Shipping Country (Optional)​

Update the cart with shipping destination to get accurate shipping costs.

PATCH
/api/cart/{cartId}

Update cart with shipping country for accurate pricing

{
  "shipping_country": "NO"
}

Step 6: Initialize Checkout​

Create a checkout session from the cart to begin the payment process.

POST
/api/checkout

Create checkout session from cart

{
  "cart_id": "CART_ID_FROM_STEP_2"
}

Step 7: Add Customer Information​

Update the checkout with billing and shipping addresses.

PATCH
/api/checkout/{checkoutId}

Add customer billing and shipping information

{
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+4712345678",
    "address": "Test Street 123",
    "city": "Oslo",
    "post_code": "0123",
    "country": "NO"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address": "Test Street 123",
    "city": "Oslo",
    "post_code": "0123",
    "country": "NO"
  }
}

Step 8: Get Payment Methods​

See what payment options are available for this checkout.

GET
/api/checkout/{checkoutId}/payment-methods

Get available payment methods for this checkout

Step 9: Initialize Payment​

Choose a payment method and get payment details (link or embedded form).

POST
/api/checkout/{checkoutId}/payment/stripe

Initialize Stripe payment for the checkout

{
  "payment_method": "stripe",
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel"
}

Key Concepts​

Channel-Based Architecture​

  • All products are accessed through your channel (/api/channel/products)
  • Each channel has its own product catalog and configuration
  • No direct product access - everything goes through your channel context

Important IDs to Track​

  • Cart ID - From cart creation, used for all cart operations
  • Checkout ID - From checkout creation, used for payment flow
  • Product IDs - From your channel's product catalog
  • Customer Session ID - Your unique identifier for the customer

Error Handling​

  • 400 Bad Request - Invalid data or missing required fields
  • 401 Unauthorized - Invalid or missing API key
  • 404 Not Found - Resource doesn't exist (wrong ID)
  • 422 Unprocessable - Valid data but business logic error

Testing Tips​

  1. Start with Channel Products - Always verify what products are available first
  2. Use Real Product IDs - Get product IDs from your channel's product list
  3. Track IDs Carefully - Save cart_id and checkout_id from responses
  4. Test Error Cases - Try invalid IDs to see error responses
  5. Currency Consistency - Use the same currency throughout the flow

Next Steps​

  • Integrate Payments - Set up Stripe, Klarna, or Vipps webhooks
  • Handle Webhooks - Listen for payment completion events
  • Customize UI - Build your own checkout experience
  • Production Setup - Get your own API key and configure your channel

Common Integration Patterns​

Frontend Integration​

// 1. Get products
const products = await fetch('/api/channel/products?currency=NOK', {
  headers: { 'Authorization': 'YOUR_API_KEY' }
});

// 2. Create cart when user starts shopping
const cart = await fetch('/api/cart', {
  method: 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ customer_session_id: userSession, currency: 'NOK' })
});

// 3. Add items as user shops
const addItem = await fetch(`/api/cart/${cartId}/item/add`, {
  method: 'POST',
  headers: { 'Authorization': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ line_items: [{ product_id: productId, quantity: 1 }] })
});

Backend Webhook Handling​

// Handle payment completion
app.post('/webhook/payment-complete', (req, res) => {
  const { checkout_id, status, payment_method } = req.body;
  
  if (status === 'completed') {
    // Order is paid - fulfill the order
    fulfillOrder(checkout_id);
  }
  
  res.status(200).send('OK');
});

Ready to start building? Try the interactive examples above or check out our Postman Collection for more detailed testing!