How Code Snippet works in Automation

Code Snippet lets you add your own JavaScript step to an Automation workflow. Use it when the built-in conditions and actions are not enough: to call your OMS, ERP or warehouse system, to calculate a score or a value from the order data, or to stop an order before it ships when an external system says so.

A Code Snippet step runs a snippet: a small JavaScript function you write once and reuse in any workflow. When the workflow runs, ShippyPro passes the order data you selected to the snippet, runs it in a secure sandbox, and gives its results back to the workflow.

1. Write the snippet: the code, the order data it reads (inputs), the results it returns (outputs), the secrets it uses and the external hosts it may call.
2. Test it with sample values before saving.
3. Submit it for review. Every version is checked automatically for problems before it can run.
4. Add it to a workflow as a Custom Code Snippet step, map its inputs to the order fields, and save the workflow.

A workflow with a Code Snippet step can start on:

• Order imported
• Label generated
• Label printed
• Order error
• Any other available event in ShippyPro

Every snippet exports one asynchronous function called main. It receives an event and returns an object with outputFields:

export async function main(event) {   const { orderId, orderTotal, destinationCountry } = event.inputFields;   const { MY_API_KEY } = event.secrets;    const res = await fetch('https://api.example.com/orders/check', {     method: 'POST',     headers: { 'content-type': 'application/json', 'x-api-key': MY_API_KEY },     body: JSON.stringify({ orderId, orderTotal, destinationCountry }),   });   if (!res.ok) {     throw new Error(`Check failed: HTTP ${res.status}`);   }   const { approved, reason } = await res.json();    return { outputFields: { approved, reason } }; }

Inputs

Inputs are the order fields the snippet reads, for example the order ID, total, currency, destination country, address or items. You give each input a name and map it to an order field when you add the step to a workflow. In the code they are available in event.inputFields. The order items arrive as a list, where each item has a name, SKU, EAN, quantity and weight.

Outputs

Outputs are the values the snippet returns. Declare each one with a name and a type: text (string), number, true/false (boolean), date and time (datetime), or a list of allowed values (enum). The values you return must match the declared types.

You can use outputs in the notes written by later actions of the same workflow, for example to save the warehouse your OMS picked or the reason an order was stopped.

Secrets

Store API keys and tokens as secrets, never in the code. A secret's name uses capital letters, numbers and underscores (for example OMS_API_KEY). In the code, read it from event.secrets. Secret values are not shown again after you save them.

External calls

Snippets can call external APIs with fetch. For security, a snippet may only call the hosts you list in its settings (up to 10, for example api.example.com or *.example.com), and only over HTTPS.

Limits

The sandbox provides standard JavaScript (JSON, Math, Date, URL), fetch and console.log. Timers, file access, Node.js modules and package imports are not available.

When the snippet fails

A snippet fails when it throws an error, times out or returns values that don't match its outputs. You choose what happens to the order:

• Stop the workflow: the order is tagged automation-blocked and gets a note with the error message, so your team sees why it was stopped. Throwing an error with a clear message is the way to stop an order on purpose, for example when your fraud check or stock check says it must not ship.
• Skip and continue: the step is skipped and the rest of the workflow runs.
• Retry, then stop: the step is retried a few times before the workflow stops.

Versions and review

Each time you change a snippet you save a new version, which is reviewed before it can run. Versions already saved never change. A workflow keeps using the version it was saved with: to move a workflow to a newer version, open the Code Snippet step, select the new version and save the workflow.

Tips

• One snippet per workflow branch. To run several snippets on the same order, create one workflow for each and set their priorities: workflows with a higher priority run first.
• Make snippets safe to run twice. A workflow can run again on the same order, so check whether your external system already has the order before creating or changing anything there.
• Write clear error messages. With "stop the workflow" the message becomes the note on the order, so write it for the person who will read it.
• Log what matters. Use console.log for the values you want to check later; never log secrets.

Example uses

• Send orders to your OMS and save the warehouse it picked in an order note.
• Score the order risk (order value, destination, payment method) and stop high-risk orders for review.
• Confirm the shipment to your OMS or ERP when the label is generated.