docs
  1. Features
  2. Transactions & Orders
  3. Order State Transition Overview

Order State Transition Overview

This document provides a comprehensive overview of the order states and the corresponding webhooks and emails triggered throughout the checkout and post-checkout processes within SCAYLE Order Management System (OMS). This information is crucial for understanding the lifecycle of an order and integrating effectively with the SCAYLE platform.

1. CREATED

  • Trigger: When a customer enters the checkout process.
  • Outcome: None.

2. CREATED to PENDED

  • Trigger: Occurs when a customer clicks the "Confirm Order/Order Now" button.
  • Description: This is an intermediate state, not visible to customers. The system initiates validation steps. An order can remain in PENDED indefinitely if the customer exits the session or closes the payment window.
  • Validation Steps:
    • a. Validate PSP (Payment Service Provider): Authorise the payment with the selected PSP. If successful, control returns to SCAYLE for Signature Validation. If failed, the order reverts to CREATED.
    • b. Validate Signature: SCAYLE verifies order integrity (signature, addresses, promotions, payment providers, basket, vouchers). Custom data is not checked. If validation passes, the order transitions to CONFIRMED, and the customer sees the Order Summary Page (OSP). If validation fails, the order reverts to CREATED, an error message is displayed, and payment authorization is cancelled.
  • Outcome:
    • Webhooks: None.
    • Emails: None.

3. PENDED to CONFIRMED

  • Trigger: Immediately after successful PSP validation.
  • Validation: The order signature is checked again to ensure that in the meantime no relevant detail in the order has changed, otherwise the authorisation is cancelled and order transitions back to Created
  • Outcome:
    • Webhooks: order-confirmed is triggered (no email sent yet).
    • Emails: None.
    • Order enters a Transition Queue for delegation.

4. CONFIRMED to DELEGATED

  • Trigger: A State Transition worker picks up orders from the Transition Queue for delegation.
  • Description: SCAYLE connects with merchants via the Delegation API (configured during merchant creation) to determine if they can fulfil the order. The delegation process runs every 2 hours until successful or timed out (46h).
  • Outcomes:
    • Complete Delegation (All items delegated):
      • Order moves to DELEGATED.
      • Webhook: order-delegated.
      • Email: Order Confirmation Mail.
    • Partial Delegation (At least one item successfully delegated):
      • Order moves to DELEGATED.
      • For delegated items:
        • Webhook: order-delegated.
        • Email: Order Confirmation Mail (only for fulfillable items).
      • For un-delegated items:
        • Webhook: order-item-out-of-stock.
        • Refunds for unfulfillable items are queued later (in SHIPPED state).
    • Failed Delegation (All merchants respond items cannot be delegated or Merchant Unreachable):
      • Order set to ABORTED.
      • Cancellation worker updates order to CANCELLED.
      • Webhook: order-cancelled.
      • Email: Order Cancellation Mail (all items).
      • Payment: Cancellation of Payment.
  • Edge Cases:
    • Customer Cancellations: Allowed when the order state is between CONFIRMED and DELEGATED.

5. DELEGATED to SHIPPED

  • Trigger: Shipment notification are received from the merchant. A Queue worker picks up shipment messages for processing.
  • Description: A shipment email is sent per shipment.
  • Outcomes:
    • All Packages Shipped:
      • SCAYLE receives shipment notifications for all packages.
      • Webhook: order-package-shipped.
      • Email: Shipment email.
    • Partial Packages Shipped:
      • Scenario a: Some items shippable, some items not (out of stock, undeliverable, customer cancellations):
        • For Shipped packages:
          • Webhook: order-package-shipped.
          • Email: Shipment email.
          • Webhook: order-partially-invoiced (if partial invoice enabled).
          • PDF: Partial invoice (if partial invoice enabled).
        • For un-shippable packages:
          • Webhook: order-item-unshippable.
          • Email: Shipment email.
          • Payment: Refunds are Queued.
          • Vouchers: Revalidated if tied to volumes.
      • Scenario b: SCAYLE did not receive shipment notifications for some packages within 14 days (force closed):
        • For Shipped packages: Same as "For Shipped packages" above.
        • For force closed packages:
          • Webhook: order-package-shipped.
    • None Shipped:
      • Scenario a: All items un-shippable (out of stock, undeliverable):
        • Order state changes to ABORTED, then CANCELLED.
      • Scenario b: SCAYLE did not receive shipment notifications for all packages within 14 days (force closed):
        • For force closed packages:
          • Webhook: order-package-shipped.
  • Special Cases:
    • If 0 items shipped, the order is ABORTED, then CANCELLED.
    • Customer cancellations are possible before shipment.
    • If shipment notification is not received within 14 days, the order is transitioned to SHIPPED
    • Orders will stay in DELEGATED state, if partial items are shipped within the 14 day period.

6. SHIPPED to INVOICED

  • Trigger: A State Transition worker picks up orders from the Transition Queue for invoice generation.
  • Outcomes:
    • Payment Capture: Late capture initiated if payment not completed.
    • Full Invoice: Generated and sent via email.
      • PDF: Full Invoice generated.
      • Email: Invoice email.
      • Webhook: order-invoiced.
  • Special Case:
    • If "Shipment Notification - Out of stock" from Merchant is received when an order is in SHIPPED state and was force closed:
      • Webhook: order-corrective-invoiced.
      • PDF: Corrective Invoice PDF.

7. ABORTED

  • Trigger:
    • Customer cancellation (via customer service, payment cancellation, or Account Area).
    • Delegation failure (no items delegated).
    • Shipment failure (no items deliverable by carrier).
  • Outcome: The "Order Transition Manager-Aborted" worker picks up the order for cancellation.

8. CANCELLED

  • Trigger: A State Transition worker picks up orders from the Transition Queue for cancellation.
  • Description: This is the final state for fully cancelled orders.
  • Outcomes:
    • Order is cancelled.
    • Email: Order cancelled email.
    • Webhook: order-cancelled.
    • Payment: Payments are cancelled.
    • Loyalty Points: Points are returned to the user's loyalty account.

9. Returns (Sub-process within INVOICED)

  • Trigger: A customer returns one or more packages. Notification is sent by the merchant to SCAYLE. A Return Handler groups multiple returns within a 3-hour return window.
  • Outcomes (All items returned):
    • When all items are NOT returned within the 3-hour window (for all items returned):
      • Email: Return email.
      • Webhook: order-item-returned.
      • PDF: Corrective Invoice PDF.
      • Email: Corrective Invoice email.
      • Webhook: order-corrective-invoiced.
      • Payment: Partial Payment cancellation to PSP (Mpay).
      • Loyalty points: Points are returned to the user's loyalty account.
      • Voucher: Revalidation of vouchers.
      • Return Costs: If configured, refund is initiated holding return costs.
      • Bank account SMS/email reminders.
    • When all items are returned within the 3-hour window:
      • Email: Return email.
      • Webhook: order-item-returned.
  • Special Cases:
    • If "Shipment Notification "Unshippable" from Merchant is received when an order is in INVOICED state and was force closed:
      • Webhook: order-corrective-invoiced.
      • PDF: Corrective Invoice PDF.
    • If "Shipment Notification "Undeliverable" from Merchant is received when an order is in INVOICED state and was force closed:
      • Webhook: order-package-undeliverable.
      • Email: Products Undeliverable email.
Previous
Order Lifecycle & States
Next up
Risk Assessment