Skip to main content
Prerequisites:
  • API access credentials (contact [email protected])
  • A test merchant account
  • Basic understanding of REST APIs

​
Complete Subscription Flow

This guide walks you through creating a complete subscription from scratch, including customer creation, payment method setup, and subscription activation.
1

Create a Customer

First, create a customer account:
curl -X POST https://api.journey.io/api/v1/customer/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{
    "full_name": "Jón Jónsson",
    "email": "[email protected]",
    "phone_number": "7771234",
    "address": "Laugavegur 1",
    "postal_code": "101",
    "city": "Reykjavík"
  }'
Response:
{
  "id": 42,
  "customer_handle": "cust-journey-42",
  "full_name": "Jón Jónsson",
  "email": "[email protected]",
  "phone_number": "7771234",
  "address": "Laugavegur 1",
  "postal_code": "101",
  "city": "Reykjavík",
  "date_time": "2025-10-09T14:23:45Z"
}
2

Add Payment Method

Create a Straumur checkout session to add a payment card:
curl -X POST https://api.journey.io/api/v1/straumur/create-session-add-card/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{
    "customer_id": 42,
    "return_url": "https://yoursite.com/payment-complete"
  }'
Response:
{
  "checkoutUrl": "https://pay.straumur.is/checkout/xyz123",
  "uuid": "550e8400-e29b-41d4-a716-446655440000"
}
Redirect your customer to the checkoutUrl to complete card verification.
3

Create Subscription

After the payment method is added, create a subscription:
curl -X POST https://api.journey.io/api/v1/subscription/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{
    "customer_id": 42,
    "subscription_status": "active",
    "delivery_option_id": 3,
    "start_date": "2025-11-01"
  }'
Response:
{
  "id": 789,
  "customer_id": 42,
  "subscription_status": "active",
  "start_date": "2025-11-01",
  "delivery_option_id": 3,
  "created": "2025-10-09T14:30:00Z"
}
4

Add Items to Subscription

Add products to the subscription cart:
curl -X POST https://api.journey.io/api/v1/subscription/789/update_cart/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{
    "order_items": [
      {
        "product_variation_id": 5,
        "quantity": 2,
        "subscription_frequency_id": 2
      }
    ]
  }'
Response:
{
  "id": 789,
  "customer_id": 42,
  "subscription_status": "active",
  "order_items": [
    {
      "id": 101,
      "product_variation_id": 5,
      "quantity": 2,
      "subscription_frequency_id": 2
    }
  ]
}
5

Verify Subscription

Retrieve the subscription to confirm everything is set up correctly:
curl -X GET https://api.journey.io/api/v1/subscription/789/ \
  -H "Cookie: sessionid=your_session_id"

​
What Happens Next?

Once your subscription is active, Journey automatically:
  1. Generates Deliveries - Creates delivery records based on your subscription frequency
  2. Processes Payments - Charges the customer’s payment method before each delivery
  3. Handles Failures - Automatically retries failed payments using dunning logic
  4. Sends Notifications - Triggers email/SMS events for payment confirmations and delivery updates

​
Next Steps

Authentication

Learn about customer login flows

Subscriptions Guide

Deep dive into subscription management

Dunning & Payment Recovery

Understand automatic payment retries

API Reference

Explore all API endpoints

​
Common Operations

​
Pause a Subscription

curl -X POST https://api.journey.io/api/v1/subscription/789/pause/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{"reason": "Customer going on vacation"}'

​
Resume a Subscription

curl -X POST https://api.journey.io/api/v1/subscription/789/resume/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{"coupon_code": "WELCOME10"}'

​
List Customer Subscriptions

curl -X GET https://api.journey.io/api/v1/customer/42/subscriptions/ \
  -H "Cookie: sessionid=your_session_id"

​
Testing

Use the staging environment for testing: 
https://staging-api.journey.io
All test data is isolated from production, and you can reset your test environment at any time.