End-to-End Checkout Integration

Overview

This guide describes the complete flow for integrating Delivery Gateway into your webshop checkout process. It covers the entire journey from the backend session creation through frontend widget integration to order and shipment management.

Architecture

The integration involves four main components:

• User/Customer: Initiates the checkout process
• Frontend (Webshop): Frontend client running on the browser
• Frontend (Delivery Gateway Widget): Handles delivery method selection and address management
• Backend (Webshop): Your backend system
• Backend (Delivery Gateway): Processes sessions, orders, and shipments

Integration Sequence

Step 1: Create a Session on the Backend

When a customer reaches the shipping method selection step in your checkout, initiate a session from your backend.

Why start with a session?

Creating a session allows you to:

• Associate delivery options and pricing with a specific customer journey
• Pass custom data (such as shipping costs) to the frontend widget
• Obtain a sessionId that connects the frontend interactions to your backend

Create a session

Use the createSession mutation to create a new session:

GraphQL mutation

mutation {
  createSession(input: {
    # Optional: pass delivery options and pricing
    items: [
      {
        name: "Standard Delivery"
        price: {
          net: { amount: 1000, currency: HUF }
          gross: { amount: 1270, currency: HUF }
          vat: 27
        }
      }
    ]
  }) {
    session {
      id
    }
  }
}

Response:

{
  "data": {
    "createSession": {
      "session": {
        "id": "session_abc123xyz"
      }
    }
  }
}

Store the sessionId to use in the next steps.

Reference: Create Session

Step 2: Load the Delivery Gateway Frontend SDK

On your checkout page, load the Delivery Gateway JavaScript SDK:

<script src="https://api.deliverygateway.io/sdk/en.js" async></script>

For details on SDK setup, see: Set Up DGW on Frontend

Step 3: Render the Delivery Selection Widget

When a customer reaches the delivery method selection step, render the appropriate widget based on their choice.

For store/pickup point delivery

If the customer selects "Store Pickup" or "Pickup Point Delivery":

window.DGW.mount({
  sessionId: 'session_abc123xyz',
  type: 'pickup-point-selection',
  ownShopFilterSelected: true, // true for your own stores, false for third-party pickup points
  container: '#dgw-widget',
  onAddressSelected: (data) => {
    console.log('Selected pickup point:', data);
  }
});

Reference: Create Pickup Point Selector

For home delivery

If the customer selects home delivery and needs to enter or modify their address:

window.DGW.mount({
  sessionId: 'session_abc123xyz',
  type: 'address-selection',
  container: '#dgw-widget',
  onAddressSelected: (data) => {
    console.log('Selected address:', data);
  }
});

Reference: Create Address Selector

Step 4: Handle Widget Callbacks

When a customer completes their selection in the widget, the callback is triggered with the selected delivery information.

onAddressSelected: Triggered when the customer successfully selects a delivery method and location. The callback receives an object containing:

• Selected delivery method details
• Pickup point or address information
• Session metadata

Reference: Callback Options

Store the delivery details

While you receive delivery information in the frontend callback, we strongly recommend querying the session from your backend for security reasons. This prevents tampering with delivery data.

// In your frontend callback, you might show a confirmation
// But verify on the backend:
onAddressSelected: (data) => {
  fetch('/your-api/confirm-delivery-selection', {
    method: 'POST',
    body: JSON.stringify({
      sessionId: 'session_abc123xyz'
    })
  });
}

On your backend, retrieve the verified session data:

GraphQL query

query {
  session(id: "session_abc123xyz") {
    id
    selectedDeliveryMethod {
      id
      name
    }
    selectedPickupPoint {
      id
      name
      address
    }
    selectedAddress {
      street
      city
      postalCode
      country
    }
    pricing {
      net { amount, currency }
      gross { amount, currency }
      vat
    }
  }
}

Store the delivery method, pickup point, or address in your checkout data.

Reference: Query Session

Step 5: Create an Order

When the order is finalized and ready to be shipped, create an order in Delivery Gateway. We recommend that your ERP system creates the order rather than the webshop, since this keeps order creation logic in one place.

Using the upsertOrder mutation

GraphQL mutation

mutation {
  upsertOrder(input: {
    referenceId: "order_12345"
    createdAt: "2025-04-16T14:30:00+02:00"
    items: [
      {
        name: "Product Name"
        sku: "SKU-001"
        quantity: { count: 1, type: PIECE }
        unit: {
          net: { amount: 10000, currency: HUF }
          gross: { amount: 12700, currency: HUF }
          vat: 27
        }
        total: {
          net: { amount: 10000, currency: HUF }
          gross: { amount: 12700, currency: HUF }
        }
        isShipping: true
        isPayment: true
      }
    ]
    total: {
      net: { amount: 10000, currency: HUF }
      gross: { amount: 12700, currency: HUF }
    }
  }) {
    order {
      id
      referenceId
      status
    }
  }
}

Reference: Create an Order

Step 6: Create a Shipment

Once your order is created and ready to ship, create a shipment. You can either:

1. Pass order data within the shipment creation (recommended for simple workflows)
2. Create the order first, then reference it (recommended for complex workflows)

Creating a shipment with inline order data

GraphQL mutation

mutation {
  createShipment(input: {
    order: {
      referenceId: "order_12345"
      # ... order data
    }
    selectedDeliveryMethod: "pickup-point"
    pickupPointId: "pp_xyz789"
    sender: {
      name: "Your Shop Name"
      address: {
        street: "123 Main St"
        city: "Budapest"
        postalCode: "1011"
        country: "HU"
      }
      email: "shop@example.com"
      phone: "+36-1-234-5678"
    }
  }) {
    shipment {
      id
      status
      parcels {
        label {
          url
        }
      }
    }
  }
}

The response includes the parcel label URL:

{
  "data": {
    "createShipment": {
      "shipment": {
        "id": "shipment_abc123",
        "status": "PENDING",
        "parcels": [
          {
            "label": {
              "url": "https://dgw-labels.example.com/label_xyz789.pdf"
            }
          }
        ]
      }
    }
  }
}

Retrieve and store the label URL for printing or sending to the customer.

Reference: Create Shipment

Step 7: Monitor Shipment Status

Track shipment status using one of two methods:

Option 1: Webhooks (Recommended)

Subscribe to SHIPMENT_UPDATED webhooks to receive real-time status updates without polling:

{
  "event": "SHIPMENT_UPDATED",
  "data": {
    "shipmentId": "shipment_abc123",
    "status": "PICKED_UP",
    "updatedAt": "2025-04-16T15:45:00+02:00"
  }
}

You can configure webhooks:

• Via code: Subscribe programmatically during integration
• Via Admin Panel: Set up once, then automatically receive updates for all shipments

Reference: Configure Webhooks

Option 2: Polling

Query the shipment status on-demand:

GraphQL query

query {
  shipment(id: "shipment_abc123") {
    id
    status
    trackingNumber
    estimatedDeliveryDate
    parcels {
      id
      status
      tracking {
        url
        number
      }
    }
  }
}

Use polling only if you cannot use webhooks. Webhooks reduce server load and provide faster updates.

Reference: Query Shipment

Complete Flow Summary

1. Backend initiates: Create a session with delivery options and pricing
2. Frontend renders: Load the SDK and display the widget
3. Customer selects: Chooses delivery method and location via widget
4. Backend verifies: Query the session to confirm the delivery selection
5. Backend prepares: Store delivery details in your checkout
6. ERP creates: Generate the finalized order
7. Backend ships: Create a shipment and retrieve the label URL
8. Monitor: Track shipment status via webhooks or polling

Best Practices

• Security: Always verify delivery selections on your backend before proceeding with orders
• Order creation: Have your ERP system create orders to centralize order management logic
• Webhooks: Use webhooks for real-time shipment status updates instead of polling
• Labels: Retrieve and securely store label URLs immediately after shipment creation
• Error handling: Implement proper error handling for each step (session creation, widget interaction, order/shipment creation)