SPS Commerce

The SPS Commerce node builds a shipment message (Advance Ship Notice / ASN) for SPS Commerce from structured input fields, renders it as XML, and writes that XML to workflow storage for downstream delivery. SPS Commerce is a cloud EDI and supply-chain network used to exchange documents — purchase orders, invoices, ASNs — between suppliers and their retail trading partners. Use this node to assemble a shipment notice from order, pack, item, and summary data produced upstream, without hand-writing the EDI XML.

Overview

The SPS Commerce node is essential when you need to:

• Build a shipment / ASN message - Assemble an SPS Commerce shipment XML from structured fields
• Avoid hand-writing EDI XML - Populate header, order, pack, item, and summary sections and let the node render the document
• Stage the message for delivery - Write the generated XML to workflow storage so a later node can transmit it to SPS Commerce
• Automate supplier-to-retailer flows - Generate shipment notices as orders ship, driven by upstream workflow data

Configuration

Action

The operation to perform. Only one action is available.

• Send Shipment Message (sendShipmentMessage, default) - Build a shipment XML message and write it to workflow storage.

Destination file (Action = Send Shipment Message)

The file name to write the generated XML as, within the current execution's workflow storage. Supports expressions. Optional — when left empty the storage service defaults the name to file.xml.

Shipment (Action = Send Shipment Message, required)

The shipment to build, supplied as a collection of optional sections. Each section is added individually; only sections you add are rendered into the XML. The available sections are:

Section	Purpose
Meta	Envelope/routing metadata (sender, receiver, control numbers, batch info)
Header	Shipment-level header, plus dates, references, contacts, addresses, carrier, totals
ContainerLevel	Container/packaging detail
Order Level	One or more orders: order header, addresses, carrier, references, and nested pack/item levels
PackLevel	Pack/carton detail
ItemLevel	Line-item detail
Summary	Shipment totals

Section and field names map directly to elements in the generated XML. The document is assembled in a fixed element order and empty values are pruned before rendering, so any field you leave blank is omitted.

Meta

A single group of string fields: SenderUniqueID, SenderCompanyName, ReceiverUniqueID, ReceiverCompanyName, IsDropShip, InterchangeControlNumber, GroupControlIdentifier, GroupControlNumber, DocumentControlIdentifier, DocumentControlNumber, InterchangeSenderID, InterchangeReceiverID, GroupSenderID, GroupReceiverID, BatchPart, BatchTotal, BatchID, Comments, Validation, OrderManagement, Version.

Header

The Header section contains a Shipment Header group plus several repeatable sub-collections.

Shipment Header fields (selection): TradingPartnerId, ShipmentIdentification, ShipDate, ShipmentTime, TsetPurposeCode, TsetTypeCode, ShipNoticeDate, ShipNoticeTime, BuyersCurrency, SellersCurrency, ExchangeRate, StatusReasonCode, BillOfLadingNumber, CarrierProNumber, AppointmentNumber, PickupNumber, RequestedPickupDate/Time, ScheduledShipDate/Time, CurrentScheduledDeliveryDate/Time, CurrentScheduledShipDate/Time, DocumentVersion, DocumentRevision, plus the option field below. Date and time fields are normalized to YYYY-MM-DD and HH:mm:ssZ when a parseable value is supplied.

ASN Structure Code (options):

Option	Value
Pick and Pack Structure	0000
Standard Carton Pack Structure	0001
Pick and Pack with Pallet Structure	0004
Standard Carton Pack with Pallet Structure	SOTPI

Header sub-collections (each repeatable): Dates, References, Notes, Contacts, Address, CarrierInformation, QuantityAndWeight, Commodity, CarrierSpecialHandlingDetail, Taxes, ChargesAllowances, FOBRelatedInstruction, QuantityTotals, RegulatoryCompliances.

Selected option fields within these sub-collections:

• Dates → DateTimeQualifier: ActualDeliveryDateandTime, ActualPickupDateandTime, EstimatedDeliveryDateandTime, PromisedforDeliveryDateandTime, RequestedPickupDateandTime, ShippedDateandTime.
• References → ReferenceQual: AdditionalReferenceNumber, AppointmentNumber, BillOfLadingNumber, CarrierProNumber, CustomerOrderNumber, DeliveryNoteNumber, InternalVendorNumber, PoNumber, PurchaseOrderNumber, TransactionReferenceNumber, WarehouseReferenceNumber.
• Address → AddressTypeCode: BillTo, BuyingParty, Carrier, DesignatedAgent, Manufacturer, MarkForParty, MessageFrom, MessageTo, PartyToReceiveCommercialInvoice, ShipFrom, ShipTo, SoldTo, Supplier, Vendor, Warehouse. The Address group also includes LocationCodeQualifier, AddressName, Address1–Address4, City, State, PostalCode, Country, LocationID, and nested References/Contacts/Dates.

Note: A References entry is only included if it has a ReferenceQual together with a ReferenceID, Date, Time, or nested ReferenceIDs; otherwise it is dropped.

Order Level

Repeatable. Each order contains an Order Header group plus the same family of sub-collections as Header, and nested PackLevel, ItemLevel, and ContainerLevel collections.

Order Header fields: DepositorOrderNumber, InternalOrderNumber, InternalOrderDate, InvoiceNumber, InvoiceDate, PurchaseOrderNumber, ReleaseNumber, PurchaseOrderDate, Department, DepartmentDescription, Vendor, JobNumber, Division, CustomerAccountNumber, CustomerOrderNumber, DeliveryDate, DeliveryTime.

ContainerLevel

Sub-collections: Container, Dates, References, Notes, QuantityAndWeight, CarrierInformation, Address, RegulatoryCompliances, ItemLevel.

PackLevel

Sub-collections: Pack, PhysicalDetails, MarksAndNumbersCollection, PalletInformation, Dates, References, Notes, Address, Taxes, ChargesAllowances, CarrierInformation, Packaging, RegulatoryCompliances, ItemLevel.

ItemLevel

The most-used group is ShipmentLine, whose rendered fields are: LineSequenceNumber, BuyerPartNumber, VendorPartNumber, ConsumerPackageCode. Additional ItemLevel sub-collections exposed in the form include PhysicalDetails, CarrierSpecialHandlingDetail, CarrierInformation, Measurements, PriceInformation, ProductOrItemDescription, MasterItemAttribute, Dates, References, Notes, Commodity, Address, Taxes, ChargesAllowances, ItemLoadInfo, and RegulatoryCompliances.

Summary

Number fields: TotalOrders, TotalLineItemNumber.

Credential

The node declares a required SPS Commerce Client credential (spscommerce-auth):

Field	Required	Description
Client ID	Yes	OAuth client ID.
Client Secret	Yes	OAuth client secret.

These are SPS Commerce OAuth client-credentials values intended for authenticating against the SPS Commerce API (token endpoint https://auth.spscommerce.com/oauth/token, audience api://api.spscommerce.com/). The credential is marked required on the node.

note

The deployed Send Shipment Message handler builds the XML and writes it to workflow storage; it does not itself upload to SPS Commerce or exchange the credential for a token in that step. Transmission to SPS Commerce (the https://api.spscommerce.com/transactions/v5/data/in endpoint) is handled separately/downstream. Document the upload step against the node actually performing it.

Output

The node returns the storage path of the generated XML file (relative to the execution):

"<task>/<destination-file>.xml"

• The return value is the workflow-storage path the XML was written to: <task>/<destFile> when Destination file is set, or <task>/file.xml (the storage service default) when it is left empty. The object is stored under the execution at S3 key <execution>/<task>/<file>.

A downstream node reads this path to transmit or further process the message.

Example Usage & Common Use Cases

Build an ASN with Header, Order, Item, and Summary Data

[Build shipment fields] → [SPS Commerce] → [Deliver to SPS]

SPS Commerce:
  Action: Send Shipment Message
  Destination file: ASN-{{ $json.poNumber }}.xml
  Shipment:
    Header:
      Shipment Header:
        TradingPartnerId: {{ $json.tradingPartner }}
        ShipmentIdentification: {{ $json.shipmentId }}
        ShipDate: {{ $json.shipDate }}
        ASN Structure Code: Standard Carton Pack Structure
    Order Level:
      Order Header:
        PurchaseOrderNumber: {{ $json.poNumber }}
      ItemLevel:
        ShipmentLine:
          LineSequenceNumber: 1
          VendorPartNumber: {{ $json.sku }}
          ConsumerPackageCode: {{ $json.upc }}
    Summary:
      TotalOrders: 1
      TotalLineItemNumber: {{ $json.lineCount }}

Output: "<task>/ASN-....xml"

Auto-name the Generated File

SPS Commerce:
  Action: Send Shipment Message
  (Destination file left empty)
  Shipment: { Header: {...}, Order Level: {...} }

Output: "<task>/file.xml"

How It Works

1. Validate the event - The handler requires parameters and execution metadata; without them it throws (No parameters found / This node requires execution metadata).
2. Read the shipment - It takes the Shipment collection and the Destination file from the node parameters.
3. Process the parameters - Each section's fixed collection is unwrapped, empty objects/strings are pruned, and the data is assembled into the canonical Shipments → Shipment[] shape in a fixed element order. Date/time fields are normalized; reference entries lacking a qualifier+value are dropped.
4. Validate and build XML - The assembled object is validated against the internal shipment schema, then rendered to pretty-printed XML. A validation failure throws a Validation error: … describing the offending payload.
5. Write to storage - The XML is written to the execution's workflow-storage bucket at S3 key <execution>/<task>/<file>, where <file> is the Destination file value or the default file.xml.
6. Return the path - The node returns the storage path (<task>/<file>) for downstream nodes to pick up.

Best Practices

• Add only the sections you need - Sections you do not add, and empty fields, are pruned from the XML, so include just the levels and fields your trading partner's ASN requires.
• Match codes to your trading-partner spec - Values such as ASN Structure Code, reference qualifiers, address type codes, and date/time qualifiers must match what SPS Commerce and the retailer expect.
• Use a meaningful destination file name - Set Destination file (e.g. derived from the PO or shipment ID) so the staged message is identifiable, rather than relying on the auto-generated UUID name.
• Wire a delivery step after this node - This node stages the XML in storage; add a downstream node to transmit the file at path to SPS Commerce.
• Provide both credential fields - Client ID and Client Secret are required on the node; store them in the SPS Commerce Client credential.

Troubleshooting

Common Issues

• "Error: No parameters found" - The node ran without parameters. Ensure the Shipment configuration is present.
• "This node requires execution metadata" - The node was invoked outside a workflow execution context (no execution/task metadata).
• "Validation error: …" - The assembled shipment failed internal schema validation. The error includes the offending payload; check that field types and required structure match (e.g. numeric fields like Summary totals, properly qualified references).
• Empty or missing sections in the XML - Empty values are pruned; if an expected element is absent, confirm the field was populated and not left blank.

Debugging Tips

• Inspect the returned path - The output path shows exactly where the XML was written; download it from workflow storage to inspect the generated document.
• Build incrementally - Start with Header + one Order Level + one ShipmentLine, confirm the XML renders, then add sub-collections.

Related

• HTTP Request - Transmit the staged XML to SPS Commerce or call other SPS endpoints
• FTP - Deliver the staged file to a remote server
• Set - Shape values before populating the Shipment sections