Order Creation

Overview

The External Order Creation feature has been designed with versatility and flexibility at its core, ensuring it can support a wide range of business scenarios and integration patterns. Once channels are configured, SCAYLE is fully prepared to receive and process external orders. These orders can be seamlessly created through API calls using the publicly available Storefront API, ensuring smooth integration into existing systems.

Its modular structure allows merchants and integrators to seamlessly handle different order origins (marketplace, in-store, or external checkout), configure channels dynamically, and enrich payloads with customer, pricing, and fulfilment details.

The below section provides detailed examples for various scenarios. Please refer to Storefront API documentation for complete Schema, query parameters, header and authentication.

Business Scenarios

In Store

The In-store use case enables retailers to capture purchases made in physical stores and synchronise them directly into SCAYLE OMS. Using the External Order Creation feature, point-of-sale (POS) systems can create orders in real time, ensuring they are linked to the correct customer account and visible alongside online purchases. This provides customers with a unified shopping history, while giving merchants consistent reporting, inventory visibility, and analytics across both offline and online channels. Below you can find examples payloads for the use case:

In Store Request Example

json

Copy

In Store Response Example

json

Copy

Additional Feature Illustrations

By supporting multiple identification methods for customers, optional overrides for prices and costs, and extensible objects such as customData, the schema adapts easily to both simple and complex use cases.

Ext order API Request with Guest Customer example

json

Copy

Ext order API Request with new Customer Creation example

json

Copy

Ext order API Request with Prices Override and Registered customer example

json

Copy

Moreover, consistent validation rules and clear error handling guarantee reliability, while optional fields and configuration flags give businesses the freedom to enable only the features they need.

This balance of structure and openness makes the schema not only future-proof but also practical for diverse commerce models—from lightweight guest checkouts to enterprise-level marketplace integrations

Troubleshooting & FAQs

This section lists common errors and questions when using the External Order Creation API, with explanations and solutions.

Q: Order creation request is rejected with 406 external_prices_not_allowed

• Cause: You included external item or order prices in the payload, but Price Override is disabled for the channel.
• Solution:
  1. Either remove all external pricing fields and let SCAYLE calculate totals internally, or
  2. Enable Price Override in your channel configuration (externalOrder.priceOverride.enabled = true).

Q: Order rejected with 406 external_voucher_not_allowed or similar error

• Cause: Vouchers, promotions, or campaign discounts were sent in the request. The External Order API does not support voucher or campaign details.
• Solution: Apply all discounts in the external system before sending the final paid prices to SCAYLE. The OMS only accepts the net result of these discounts.

Q: Order rejected with 406 external_customer_required

• Cause: The request did not include a valid customer reference. Every external order must be linked to a customer.
• Solution: Provide one of:
  • customer.id (SCAYLE-internal ID), or
  • customer.referenceKey (merchant reference), or
  • a full inline customer object (creates a guest customer).

Q: Items missing or rejected during order creation

• Cause: One or more items could not be processed (e.g., invalid variantId, no available stock, or missing required price fields).
• Solution:
  • Check that each variantId exists and is active.
  • Provide mandatory fields (quantity, unitPrice if override enabled).
  • If some items are invalid but at least one is valid, the API creates the order with the valid items only.

Q: Payments not reflected correctly

• Cause: OMS treats payments from external orders as informational only. It uses a dummy payment method internally.
• Solution: Always provide a paymentTypes entry with a transactionId and authorized Value, but remember SCAYLE won’t process actual payment collection.