Documentation
Transformer Rules
Expression Service Specification
API Models
Documentation
Transformer Rules
Expression Service Specification
API Models

API Models

Overview

The OrderCreatedSourceAction represents a complete order structure for tracking e-commerce transactions. This model captures all essential order information including customer details, line items, addresses, and financial data for all source actions we provide.

OrderCreatedSourceAction Object

Field Name Type Required Description
orderNumber string No Human-readable identifier for the order (not guaranteed unique)
externalOrderKey string Yes Unique identifier for the order in the originating system (must be unique within organization)
orderCreatedDate timestamp No Date and time when the order was originally created
orderModifiedDate timestamp No Date and time when the order was last modified
orderCancelledDate timestamp No Date and time when the order was cancelled (null if not cancelled)
orderPaidDate timestamp No Date and time when payment was completed
orderFulfilledDate timestamp No Date and time when the order was fulfilled/shipped
currencyCode string No ISO 4217 currency code (e.g., "USD", "EUR", "GBP")
totalShipping number No Total shipping cost before tax
shippingTax number No Tax amount applied to shipping
totalDiscount number No Total discount amount applied to the order
discountTax number No Tax amount on discounts
subTotal number No Order subtotal before tax and shipping
totalPrice number No Final total price including all taxes, shipping, and discounts
totalTax number No Total tax amount for the entire order
paymentMethod string No Payment method used (e.g., "Credit Card", "PayPal", "Bank Transfer")
confirmationNumber string No Order confirmation or reference number
customer OrderCustomer No Customer information
billingAddress BillingAddress No Billing address details
shippingAddress ShippingAddress No Shipping address details
orderItems Array of OrderItem No List of products/services in the order
orderTags Array of strings No Tags or labels associated with the order
customNotes Array of strings No Custom notes or comments about the order
metaData Array of strings No Additional metadata fields
customField1 string No Configurable custom field #1
customField2 string No Configurable custom field #2
customField3 string No Configurable custom field #3
reviewRequired boolean No Whether this order requires manual review
deliveryMethod string No Configurable delivery method (e.g., "Standard", "Express", "Pickup")

Sub-Objects

OrderItem

Represents individual products or services within an order.

Field Name Type Required Description
externalLineItemKey string Yes Unique identifier for this line item in the origin system (must be unique within the order)
itemId string Yes Unique product identifier in the origin system
sku string No Stock Keeping Unit (product SKU)
grams number No Weight of the item in grams
name string No Product or service name
quantity integer No Number of units ordered
price number No Unit price of the item
currencyCode string No Currency code for this item (if different from order currency)
requiresShipping boolean No Whether this item requires physical shipping
subTotal number No Line item subtotal (price × quantity) before tax
subTotalTax number No Tax amount for this line item
totalPrice number No Final line item total including tax and discounts
totalDiscount number No Discount amount applied to this line item
totalTax number No Total tax for this line item
vendor string No Vendor or supplier name
channel string No Sales channel (e.g., "Online", "In-Store", "Phone")
brand string No Product brand name
warehouse string No Fulfillment warehouse identifier
description string No Detailed product description
itemTags Array of strings No Tags associated with this specific item

OrderCustomer

Customer information for the order.

Field Name Type Required Description
customerId string No Unique customer identifier in the origin system
name string No Full customer name
contact string No Primary contact method
firstName string No Customer's first name
lastName string No Customer's last name
email string No Customer's email address
addressLine1 string No Primary address line
addressLine2 string No Secondary address line (apartment, suite, etc.)
city string No City name
state string No State or region
province string No Province (alternative to state)
provinceCode string No Province abbreviation code
country string No Country name
countryCode string No ISO country code (e.g., "US", "CA", "GB")
zipCode string No Postal/ZIP code
phone string No Customer's phone number
note string No Notes about the customer
tags Array of strings No Customer tags or segments

BillingAddress

Billing address information.

Field Name Type Required Description
name string No Full name on billing address
contact string No Contact person name
firstName string No First name
lastName string No Last name
email string No Email address for billing
addressLine1 string No Primary billing address line
addressLine2 string No Secondary address line
city string No Billing city
state string No Billing state/region
zipCode string No Billing postal code
country string No Billing country
countryCode string No Billing country code
province string No Billing province
provinceCode string No Province code
phone string No Phone number for billing
company string No Company name (for B2B orders)

ShippingAddress

Shipping/delivery address information.

Field Name Type Required Description
name string No Full name for shipping
contact string No Contact person for delivery
firstName string No Recipient's first name
lastName string No Recipient's last name
email string No Email for shipping notifications
addressLine1 string No Primary shipping address
addressLine2 string No Secondary address line
city string No Shipping city
state string No Shipping state/region
zipCode string No Shipping postal code
country string No Shipping country
countryCode string No Shipping country code
province string No Shipping province
provinceCode string No Province code
phone string No Phone for delivery
company string No Company name for delivery

Data Types

Type Description Format Example
string Text value UTF-8 string "ORDER-12345"
number Decimal number Float64 99.99
integer Whole number Int 5
boolean True/false value Boolean true
timestamp RFC3339 date/time RFC3339 format "2024-01-15T10:30:00Z"
Array of X List of specified type JSON array ["tag1", "tag2"]

Timestamp Format (RFC3339)

All timestamp fields use RFC3339 format, which is a profile of ISO 8601:

Format Examples:

  • UTC: "2024-01-15T10:30:00Z"
  • With timezone: "2024-01-15T10:30:00-05:00"
  • With milliseconds: "2024-01-15T10:30:00.123Z"
  • Local time with offset: "2024-01-15T15:30:00+01:00"

Key Points:

  • ✅ Always include timezone information (Z for UTC or offset like -05:00)
  • ✅ Use 24-hour format
  • ✅ Date and time are separated by 'T'
  • ✅ Seconds are required (even if :00)
  • ✅ Microseconds/nanoseconds are optional but supported

Invalid Examples:

  • ❌ "2024-01-15 10:30:00" (missing T separator)
  • ❌ "2024-01-15T10:30" (missing seconds)
  • ❌ "2024-01-15T10:30:00" (missing timezone)

Required Fields Summary

Main Order Object:

  • ✅ externalOrderKey (string) - Must be unique across all orders in the organization

Order Item Object:

  • ✅ externalLineItemKey (string) - Must be unique across all order items in the organization
  • ✅ itemId (string) - Must be a unique product identifier and unique within the order

Important Notes

🚫 Common Errors

  • an error occurred parsing the source action payload: This error happens when a field in the mapper input has an incorrect type or name. Please verify the field exists in the model above and is the correct data type.

🔑 Unique Identifiers

  • externalOrderKey: REQUIRED - Must be unique across all orders in your organization
  • externalLineItemKey: REQUIRED - Must be unique within each order
  • itemId: REQUIRED - Must be a valid product identifier in your system

💰 Currency Handling

  • All monetary values are decimal numbers
  • Currency codes follow ISO 4217 standard
  • Individual items can have different currencies than the order

📅 Date Handling

  • All timestamps use RFC3339 format
  • Timezone information is required
  • UTC timezone is recommended for consistency
  • Null dates indicate the event hasn't occurred

⚠️ Required vs Optional

  • Required fields must always be provided and cannot be null or empty
  • Optional fields can be omitted or set to null
  • Empty arrays are acceptable for optional list fields

🏷️ Tags and Metadata

  • Tags are simple string arrays for categorization
  • Metadata provides extensibility for custom data
  • Custom fields (1-3) offer structured extension points

Example Usage

{
  "externalOrderKey": "order_12345",
  "orderNumber": "ORD-2024-001",
  "orderCreatedDate": "2024-01-15T10:30:00Z",
  "orderModifiedDate": "2024-01-15T11:45:30Z",
  "orderPaidDate": "2024-01-15T10:35:15Z",
  "totalPrice": 129.99,
  "currencyCode": "USD",
  "reviewRequired": false,
  "customer": {
    "customerId": "cust_789",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "orderItems": [
    {
      "externalLineItemKey": "line_item_001",
      "itemId": "product_12345",
      "name": "Premium T-Shirt",
      "quantity": 2,
      "price": 49.99,
      "requiresShipping": true
    }
  ]
}