Norce Checkout Order

The Norce Checkout Order is the central data structure that manages the checkout process. The Norce Checkout Order contains cart items, customer details, shipping options, payment information, and the callbacks (validations, hooks, and notifications) that coordinate adapter behavior.

Overview

The Norce Checkout Order manages all aspects of the checkout transaction. Every order starts in the checkout state and progresses through states as the customer completes payment.

Order Context

The order contains key context information that cannot be modified during checkout. This data is crucial for most adapters and their integrations and remains static throughout the flow.

• Culture: Defines the locale and language for the checkout.
• Currency: Specifies the currency used for the transaction.
• Country: Indicates the country associated with the order.

Cart

The cart keeps track of items and discounts.

Read more about carts here.

Customer details

The customer model includes two addresses: billing and shipping. We're considering adding orderer as a third. Each address has a different owner. The billing address is primarily for the payment provider and is often provided by them. The shipping address is used by the delivery provider and may come from the checkout, payment provider, or the shipping provider. Currently, platform adapters assume that the billing address also represents the individual making the order.

Order States

A new order starts in the Checkout state, where it is editable. When a payment is initiated, the order transitions to Processing. If the payment is accepted, the order advances to the Accepted state; if it is declined, the order returns to Checkout. After all conditions are met, the order finally reaches the Completed state. However, if there's a failure after acceptance, it will transition to Declined.

Read more about order states here.

Shippings

Keeps track of delivery details and the cost of shipping. It has an adapterId that tells us which adapter has created and manages this shipping.

Order total

The order always calculates the sum of the cart total and all active shipping costs. We cannot transition the order to the processing state unless the total of all active payments matches this overall total.

Payments

Payments on the order contain an optional adapterId to inform us if this payment was created and is being managed by an adapter, very useful for cases where we have multiple payment adapters creating payments on the order. amount informs us how much of the order this payment is covering.

Example order with payments

This example shows a realistic order where a customer purchases two items totaling 1,598 SEK, with standard shipping at 49 SEK. The customer applies a 200 SEK gift card voucher, and pays the remaining 1,447 SEK via Klarna Checkout.

{
  "id": "ord_2f8a4b6c-9d3e-4f1a-b5c7-8e9f0a1b2c3d",
  "state": "completed",
  "culture": "sv-SE",
  "currency": "SEK",
  "country": "SE",
  "cart": {
    "items": [
      {
        "id": "item_001",
        "sku": "SHOE-BLK-42",
        "name": "Running Shoes - Black",
        "quantity": 1,
        "unitPrice": {
          "includingVat": 1299,
          "excludingVat": 1039.20,
          "vatRate": 25
        },
        "total": {
          "includingVat": 1299,
          "excludingVat": 1039.20
        }
      },
      {
        "id": "item_002",
        "sku": "SOCK-WHT-M",
        "name": "Sport Socks 3-Pack - White",
        "quantity": 1,
        "unitPrice": {
          "includingVat": 299,
          "excludingVat": 239.20,
          "vatRate": 25
        },
        "total": {
          "includingVat": 299,
          "excludingVat": 239.20
        }
      }
    ],
    "total": {
      "includingVat": 1598,
      "excludingVat": 1278.40
    }
  },
  "customer": {
    "billing": {
      "firstName": "Anna",
      "lastName": "Andersson",
      "email": "anna.andersson@example.com",
      "phone": "+46701234567",
      "address": {
        "street": "Storgatan 15",
        "postalCode": "11122",
        "city": "Stockholm",
        "country": "SE"
      }
    },
    "shipping": {
      "firstName": "Anna",
      "lastName": "Andersson",
      "address": {
        "street": "Storgatan 15",
        "postalCode": "11122",
        "city": "Stockholm",
        "country": "SE"
      }
    }
  },
  "shippings": [
    {
      "id": "ship_001",
      "adapterId": "ingrid_adapter",
      "name": "Standard Delivery",
      "description": "Delivery within 3-5 business days",
      "total": {
        "includingVat": 49,
        "excludingVat": 39.20,
        "vatRate": 25
      }
    }
  ],
  "payments": [
    {
      "id": "pay_001",
      "adapterId": "klarna_checkout_adapter",
      "name": "Klarna Checkout",
      "type": "default",
      "status": "captured",
      "amount": 1447
    },
    {
      "id": "pay_002",
      "adapterId": "awardit_adapter",
      "name": "Gift Card",
      "type": "voucher",
      "status": "captured",
      "amount": 200,
      "upperLimitAmount": 200
    }
  ],
  "total": {
    "includingVat": 1647,
    "excludingVat": 1317.60
  },
  "createdAt": "2025-01-15T14:32:00Z",
  "completedAt": "2025-01-15T14:35:22Z"
}

In this order, the cart total is 1,598 SEK and shipping is 49 SEK, resulting in an order total of 1,647 SEK. The gift card voucher covers 200 SEK (its upperLimitAmount), and the Klarna payment covers the remaining 1,447 SEK. The sum of all payment amounts (200 + 1,447 = 1,647) matches the order total, which is required before the order can transition to the processing state.

Callbacks

Callbacks are used to interact with adapters without tightly coupling them. There are three different types of callbacks registered on the order:

• Validations
• Hooks
• Notifications

Read more about validations, hooks and notifications here.