Carbon API Migration Guide

Executive Summary

What's Changing

Why Upgrade?

Simplified Payment Workflow — The Carbon API reduces the payment workflow from two distinct operations down to one streamlined call. Create orders and initiate payments in a single request.

Consolidated Logistics — Bundle multiple terminal returns into one case, streamlining operations and reducing costs (vs. one-terminal-per-return in Lithium).

PRO Terminal Access — New PRO terminal models run v5 of the payment app by default. Migration is NOT required to deploy PRO terminals to your merchants, however new features and functionality depend on migration.

Terminal Fleet Considerations

PRO Terminals (New Fleet)

All new PRO terminal models ship with v5 of the payment app by default and fully support all Carbon features.

Pre-v5 Terminal Apps

Terminals running earlier app versions (pre-v5) will accept Carbon API calls — your integration works immediately after migration. Behind the scenes, these calls are processed through a Lithium compatibility layer, which means:

• All current functionality works — everything you do today will continue to work
• Performance is Lithium-equivalent — speed remains the same as before migration
• New features are not available — features like combined purchase + return orders require v5

When terminal app v5 becomes available (target: late February 2026), updating your terminals will unlock:

• Significant speed improvements — Carbon's native performance
• New features — Combined purchase/return orders, and future Carbon capabilities

API Readiness Status

Endpoints Ready for Production

The following endpoints are Live on Carbon:

Endpoints In Testing

Terminal API Limitations (v5)

The following terminal configuration properties are not yet supported in v5:

Technical Migration Guide

Why Migrate Now?

Migrating to Carbon aligns your integration with the new API structure. All your current functionality continues to work immediately — even on terminals running pre-v5 app versions (processed via a Lithium compatibility layer).

When terminal app v5 rolls out (target: late February 2026), you'll automatically benefit from Carbon's native speed improvements and new features — no additional API changes needed.

Step 1: Update Base URL

Replace all API calls from the Lithium base URL to Carbon:

// Before (Lithium)
baseApiUrl = "https://lithium.[domain]/api"

// After (Carbon)
baseApiUrl = "https://carbon.[domain]/api"

Step 2: Migrate to Orders-First Workflow

In Carbon, Orders is the primary API. Payment initiation now happens directly from the order creation — no separate Payments API call needed.

Key Changes from Lithium

Refunds: Negative Quantities

In Lithium, you created separate orders with type: "return". In Carbon, refunds are line items with negative quantities:

// Carbon: Purchase and return in the same order
{
  "orderLines": [
    { "id": "item1", "name": "Blue Shirt", "quantity": 1, "amount": { "total": 500 } },
    { "id": "item2", "name": "Red Shirt (returned)", "quantity": -1, "amount": { "total": -500 } }
  ]
}

Lithium: Create Order + Initiate Payment

// Step 1: Create Order
POST /orders
{
  "terminal$id": "813bee989f08500405",
  "type": "purchase",
  "referenceId": "orderabc",
  "customer": {
    "person": {
      "id": "cust123",
      "name": { "firstName": "John", "lastName": "Doe" },
      "phoneNumber": { "code": 46, "number": "701234567" }
    },
    "billing": {
      "address1": "Main Street 1",
      "city": "Stockholm",
      "postalCode": "10001",
      "country": "Sweden"
    }
  },
  "orderLines": [
    {
      "id": "1234",
      "name": "Bucket hat",
      "quantity": 1,
      "itemAmount": { "regular": 2000, "total": 2000, "currency": "SEK" }
    }
  ]
}

// Step 2: Initiate Payment (separate call)
POST /payments
{
  "orderId": "8288f03bde50680c0b",
  "paymentMethod": "CARD"
}

// Step 3: Check payment status
GET /payments/811f9bd48c6eb80c06/status

Carbon: Single Order Call with Payment Initiation

POST /orders
{
  "terminal$id": "8386af3b0f71b80b04",
  "referenceId": "order-12345",
  "customer": {
    "customerId": "cust123",
    "person": {
      "name": { "firstName": "John", "lastName": "Doe" },
      "phoneNumber": { "code": "46", "number": "701234567" }
    }
  },
  "billing": {
    "name": { "firstName": "John", "lastName": "Doe" },
    "address": {
      "addressLine1": "Main Street 1",
      "city": "Stockholm",
      "postalCode": "10001",
      "countryCode": "SE"
    }
  },
  "orderLines": [
    {
      "id": "1234",
      "name": "Bucket hat",
      "quantity": 1,
      "amount": { "regular": 2000, "total": 2000, "currency": "752" }
    }
  ],
  "controlFunctions": {
    "initiatePaymentsOptions": {
      "paymentMethod": "CARD",
      "amount": 2000
    }
  }
}

// Response includes payment data
{
  "status": "SUCCESS",
  "data": {
    "orderId": "8381a26eae26f0900b",
    "paymentId": "8381a26eae26f2af06",
    "paymentUrl": "https://...",
    "qrData": "00020126..."
  }
}

// Check order status (includes payment info)
GET /orders/8381a26eae26f0900b/status

Step 3: Migrate Terminals API

The Terminals API endpoint path has changed and the registration parameter has been renamed.

Key Changes

• Endpoint changed from POST /terminals to POST /merchants/:merchantId/stores/:storeId/devices
• Parameter renamed: registrationId → registrationIdentifier

Lithium

POST /terminals
{
  "registrationId": "250901",
  "storeId": "store_456",
  "terminalName": "Kiosk One"
}

Carbon

POST /merchants/:merchantId/stores/:storeId/devices
{
  "registrationIdentifier": "250901",
  "terminalName": "Kiosk One"
}

Online SDK Note

A new Carbon Online SDK is coming soon with:

• Multi-basket order support
• Significant performance and speed improvements

In the meantime, you can use Carbon to create orders and continue using the existing Thorium SDK for Online Checkout. The two are compatible during the transition period.

Stable APIs (No Changes Required)

The following APIs work identically in both Lithium and Carbon:

• Stores API — Minor addition of optional terminalType filter
• Receipts API — Identical endpoints and schemas
• Branding API — Identical endpoints and schemas
• Order Webhooks — All events unchanged
• Merchant Webhooks — All application lifecycle events unchanged

New Carbon-Only APIs

Carbon introduces new APIs not available in Lithium:

Migration Checklist

Support & Resources

For technical questions during migration, contact your partner success manager or reach out via the partner support portal.

Read the Carbon docs here: Carbon API Documentation →