
## Frequently asked questions

Below is a list of frequently asked questions about the EDI Translate API. If you have any questions not listed here, please [contact us](https://www.stedi.com/contact).

## Data & Privacy

### How does the EDI Translate API use my data?

In short, we don’t. The payloads sent to the `translate` API are not stored – temporarily or permanently. The contents of your file are encrypted in transit.

### Is data sent to the EDI Translate API stored?

The `translate` API is a stateless system that executes a transformation on your data. The transformation happens during the duration of the request; we do not retain the payload once a response is returned.

### What does Stedi log when I hit the EDI Translate API?

We log only request meta information such as the size of the request, latency, transaction sets, and release.

These data points allow our engineers to monitor the health of the system and drive improvements to the service. They help the team answer questions like:

- How many requests did the API receive over the past week?
- What percentage of the responses returned a 4XX/5XX status code?
- Why did latency increase after the most recent deployment?

If a request fails with a 500 status code, an engineer on the team is notified (yes, we investigate every single one).


How your data is handled when using Stedi’s EDI Translate API

Data and privacy

EDI Translate Data and Privacy


The EDI Translate API has several limits on how you can use the service. If you are impacted or blocked by any of these restrictions, please [contact support](https://www.stedi.com/docs/support), and we can help solve your issue.

| Resource or operation       | Limit           | Can be increased |
| --------------------------- | --------------- | ---------------- |
| Requests per second         | 25              | Yes              |
| Maximum concurrent requests | 100             | Yes              |
| Maximum request size        | 6 megabytes[^1] | No[^2]           |
| Maximum response size       | 6 megabytes[^1] | No[^2]           |

[^1]: The request and response sizes are limited by the size of the HTTP request. You can receive more data when you use gzip compression on your request. Most HTTP clients support compression, and you can enable it by setting the `Accept-Encoding` header to `gzip`. When translating EDI to JSON with compression enabled, the maximum response size limit applies to the size of the compressed JSON response.
[^2]: [Stedi Core](https://www.stedi.com/docs/core) supports parsing large files. For more information, visit [Limits](https://www.stedi.com/docs/core/limits) in the Core documentation.


Request and response limits for Stedi’s EDI Translate API

Limits

EDI Translate Limits


The EDI Translate API is billed based on usage. There are no minimum fees, monthly commitments, or upfront costs to use this product.

Usage is calculated based on request count and MB processed.

A request is defined as a single call to the EDI Translate API, regardless of how many transactions (e.g. ST segments) are in the payload.

## Pricing tiers

### API request count pricing

The first 1,000 requests per month are free. Each API request includes a 10 KB data allowance.

| **Request Count per Month** | **Price**             |
| --------------------------- | --------------------- |
| First 1,000                 | Free                  |
| 1,000 to 250,000            | $0.007500 per request |
| 250,000 to 500,000          | $0.006750 per request |
| 500,000 to 1,000,000        | $0.006375 per request |
| Above 1,000,000             | $0.006000 per request |

### API bytes processed per request pricing

Each API request includes a 10 KB data allowance, and you're only charged for bytes processed above the 10 KB allowance per request. The first 5 MB of data processed per month are free.

| **Data Processed per Month** | **Price**                         |
| ---------------------------- | --------------------------------- |
| Up to 5 MB\*                 | Free                              |
| Above 5 MB                   | $0.0075 for each additional 50 KB |

[Contact us](https://www.stedi.com/contact) if you have a question on pricing.

\*1 MB = 1024 KB or 1,048,576 bytes


Pricing information for Stedi’s EDI Translate API

Pricing

EDI Translate Pricing

EDI Translate takes a JSON document that’s already structured like EDI and turns it into an X12 EDI document. You need a Stedi guide that describes the structure. If you have a JSON document that’s not structured like EDI, you have to map it first.

- See also: [Create a Stedi guide](/docs/guides)
- See also: [Map a JSON document](/docs/mappings)



## JSON structure

The Stedi guide determines how the input JSON should be structured. If you need an example of the JSON structure, you can [open your Stedi guide](https://www.stedi.com/app/guides/) and go to the _EDI Inspector_ tab. It will show you an example of both the EDI and the JSON.

## Envelope

EDI documents have envelopes that contain metadata. That metadata is typically not included in the JSON document, so you need to provide it separately.

There are three types of envelopes.

- The interchange ([ISA](https://www.stedi.com/edi/x12/segment/ISA)) tells you who the message is for on an organization level. It identifies you as the sender and your trading partner as the receiver.
- The functional ([GS](https://www.stedi.com/edi/x12/segment/GS)) group tells you who the message is for on a department level. Invoices go to the Finance department, ship notices go to the Shipping department, that sort of thing.
- The transaction set ([ST](https://www.stedi.com/edi/x12/segment/ST)) represents a single document. An EDI message can contain multiple documents and the transaction set envelope helps keep them apart.

Each envelope has a start segment and an end segment. EDI Translate will generate these segments based on the data you provide.

```json
{
  "interchangeHeader": {
    "senderQualifier": "ZZ",
    "senderId": "ME",
    "receiverQualifier": "ZZ",
    "receiverId": "YOU",
    "date": "2022-08-15",
    "time": "13:20",
    "usageIndicatorCode": "P",
    "controlNumber": "12"
  },
  "groupHeader": {
    "functionalIdentifierCode": "PO",
    "applicationSenderCode": "ME",
    "applicationReceiverCode": "YOUR DEPT",
    "date": "2022-08-15",
    "time": "13:20:52",
    "controlNumber": "1"
  }
}
```

| Interchange field  | Description                                                                                                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| senderId           | Identifies the sender of the message.                                                                                                                                                                                                                      |
| senderQualifier    | Indicates the type of identifier used in `senderId`. For example, `01` means Duns, `20` means Health Industry Number, `ZZ` whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner.   |
| receiverId         | Identifies the receiver of the message.                                                                                                                                                                                                                    |
| receiverQualifier  | Indicates the type of identifier used in `receiverId`. For example, `01` means Duns, `20` means Health Industry Number, `ZZ` whatever you agree on. The implementation guide should tell you which values are valid. If not, contact your trading partner. |
| date               | The date this message was sent, e.g. `2022-08-15`.                                                                                                                                                                                                         |
| time               | The time this message was sent, e.g. `13:20`.                                                                                                                                                                                                              |
| usageIndicatorCode | `P` if this is a production message, `T` if it’s a test message, `I` if the message is informational.                                                                                                                                                      |
| controlNumber      | A unique identifier for this interchange.                                                                                                                                                                                                                  |

| Functional group field   | Description                                                                                                                                                                                                            |
| ------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| functionalIdentifierCode | Indicates the type the message. Must be one of the [standardized functional identifier code](https://www.stedi.com/edi/x12/element/479).                                                                               |
| applicationSenderCode    | Indicates where the message came from. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner. |
| applicationReceiverCode  | Indicates where the message should go. There are no standardized codes; you need to agree on valid values with your trading partner. If you can’t find this in the implementation guide, contact your trading partner. |
| date                     | The date this message was sent, e.g. `2022-08-15`.                                                                                                                                                                     |
| time                     | The time this message was sent, e.g. `13:20:52`.                                                                                                                                                                       |
| controlNumber            | A unique identifier for this functional group.                                                                                                                                                                         |

If you want to specify the transaction set envelope, you should do so in the JSON document, not in the `envelope` field.

Translate takes care of writing the transaction set trailer (SE segment) as long as the information for the transaction set header (ST) is provided in the JSON document. If the document does not include the transaction set header, translate will NOT write out the trailer.

At the moment, it isn’t possible to produce EDI documents with multiple functional groups.

## Delimiters

When writing EDI, EDI Translate uses the delimiters configured in the Stedi guide. When you create a guide, a default set of delimiters is assigned to the guide. You have the ability to change these values through the Stedi Guides UI. Just open your guide and click on _Overview_ in the top left. You’ll find the delimiters at the bottom.

## Calling the API

You translate a document by calling the API. First you need an [API key](https://www.stedi.com/app/settings/api-keys) and then you can call the EDI Translate endpoint: `https://edi-translate.us.stedi.com/2022-01-01/x12/from-json`.

```javascript
const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function jsonToX12(guideId, document, envelope) {
  if (typeof document === "string") {
    document = JSON.parse(document);
  }

  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/from-json",
    data: {
      guideId: guideId,
      input: document,
      envelope: envelope,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

With EDI Translate, you can translate a JSON document into X12 EDI. You need a Stedi guide to describe the structure of the JSON.

Translate JSON to X12 EDI

EDI Translate takes X12 EDI and turns it into a JSON document.
You may use a Stedi guide to describes the structure of the document.
Guides ensure that EDI exchanged between trading partners meets their needs.
The shape of the JSON document resembles the original X12 EDI, but you can map it into any shape you need.

You may also translate X12 EDI without a guide for more flexibility.
Review calling the API [without a guide](#without-a-guide) for more details.

- See also: [Create a Stedi guide](/docs/guides)
- See also: [Map a JSON document](/docs/mappings)



## Envelopes

The interchange envelope ([ISA](https://www.stedi.com/edi/x12/segment/ISA)) and functional group envelope ([GS](https://www.stedi.com/edi/x12/segment/GS)) are optional, but if you provide either, you should provide both. The input EDI can optionally contain the transaction set envelope ([ST](https://www.stedi.com/edi/x12/segment/ST)).

At the moment, it isn’t possible to translate EDI documents with multiple functional groups. Multiple transaction sets within the same functional group works fine, though.

## Delimiters

The delimiters used during translation depend on the type of EDI document you submit.

- EDI document with ISA envelope.
  The delimiters specified in the ISA segment are used for parsing purposes.
  Delimiters specified in the guide or as request input options are ignore in this case.
- EDI document without ISA and GS envelopes.
  If EDI Translate is called with a guide, the delimiters specified in the guide will be used.
  If EDI Translate is called without a guide, the delimiters specified in `guidelessInputOptions` will be used.

The response of the [`to-json` endpoint](https://www.stedi.com/docs/api/edi-translate#TranslateJsonToX12) includes the delimiters used during processing of the EDI document.

## Calling the API

You translate a document by calling the API. First you need an [API key](/docs/accounts-and-billing/authentication) and then you can call the EDI Translate endpoint: `https://edi-translate.us.stedi.com/2022-01-01/x12/to-json`.

### With a Guide

```javascript
const axios = require("axios");

const apiKey = process.env.STEDI_API_KEY;

async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      guideId: guideId,
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

### Without a Guide

Using EDI Translate without a Stedi guide lets you receive X12 EDI that might not conform to strict, partner-specific EDI requirements. Translation flexibility is useful for the following use cases:

- Developing and testing a new trading partner integration
- Troubleshooting EDI that doesn't meet your expectations
- Developing a guide to make sure EDI you receive meets your requirements

When you translate EDI without a Stedi guide, EDI Translate validates the incoming EDI with the generic X12 release specification and uses a default structure definition for the resulting JSON document. For example, the output will use default names for all properties.

Therefore, we do not recommend translating without a Stedi guide in production scenarios that require accurately processing partner-specific data. For example, updating an ERP system in response to incoming EDI may require specific fields for data consistency. In this case, you should use a guide to ensure these fields are present before the data is passed to the ERP system.

To translate without a guide, simply omit the `guideId` argument from the API call.

```javascript
async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

If your X12 EDI document does not have an ISA or GS envelope you will need to
specify an X12 release to use.

```javascript
async function x12ToJson(guideId, document) {
  const response = await axios({
    method: "post",
    url: "https://edi-translate.us.stedi.com/2022-01-01/x12/to-json",
    data: {
      input: document,
      inputOptions: {
        guidelessInputOptions: {
          x12Release: "004010",
        },
      },
    },
    headers: { Authorization: `Key ${apiKey}` },
  });

  return response.data;
}
```

With EDI Translate, you can translate X12 EDI into a JSON document. You can use a Stedi guide to describe the structure of the document.

Translate X12 EDI to JSON


Stedi strives for backwards compatibility for all products in general availability.

The following changes are considered backwards compatible:

- New API resources.
- Additional optional parameters to API requests.
- Additional fields in API responses.
- Changes in the order of properties in API responses.
- Changes in human-readable error messages.
- Downgrading mandatory parameters to optional parameters.

When a breaking change is made, a root-level, dated version is released.

For more information on the product lifecycle, please see the [Preview Program](/docs/getting-started/preview-program).


Upgrades


EDI Translate lets you translate documents between X12 EDI and JSON.

Many use cases require using EDI Translate with a [Stedi guide](/docs/guides) that describes the structure of the JSON. We provide recommendations about when you may want to [use EDI Translate without a guide](edi-translate/translate-x12-edi-to-json#calling-the-api-without-a-guide).

## Use cases

- **Writing EDI documents.** Generate X12 EDI documents based on a Stedi guide to ensure outgoing EDI documents adhere to your partner's specific requirements.
- **Reading EDI documents.** Read X12 EDI documents received from your trading partner with or without a guide, depending on your use case.

## Getting started

Before you can use EDI Translate, you need a Stedi account and an API key.

- [Create a Stedi account](/terminal/sign-up) (free and no credit card required)
- [Create an API key](/docs/accounts-and-billing/authentication)

After that, you can get started.

- [Translate JSON to X12 EDI](/docs/edi-translate/translate-json-to-x12-edi)
- [Translate X12 EDI to JSON](/docs/edi-translate/translate-x12-edi-to-json)


EDI Translate


To send a `gzip` compressed payload to the EDI Core API, set the `Content-Type` header to the value of `application/gzip`. EDI Core only supports `gzip` compression.

Note that the [maximum document size limit][core-limits] **is applied after decompressing the content of the payload**. If the decompressed payload of a given request is larger than the maximum document size limit, the EDI Core API will reject the request.

The following [TypeScript][typescript] example shows how to send a `gzip` compressed payload to the `/translate` endpoint.

```ts
import * as fs from "fs";
import axios from "axios";
import { gzipSync } from "zlib";

const API_KEY = "YOUR_API_KEY";
const rootURL = "https://edi-core.stedi.com/2021-06-05/translate";
const headers = {
  "Authorization": `Key ${API_KEY}`,
  "content-type": "application/gzip",
  "accept-encoding": "gzip",
};
const edi = fs.readFileSync(process.argv[2], "utf-8");

async function makeRequest(): Promise<void> {
  const request = {
    input: edi,
    input_format: "edi",
    output_format: "jedi@2.0",
  };

  const response = await axios.request({
    method: "post",
    url: url,
    data: gzipSync(JSON.stringify(request)),
    headers: headers,
  });
  console.log(response.status);
  console.log(response.data);
}

async function main() {
  try {
    await makeRequest();
  } catch (e) {
    console.log(e);
  }
}

main();
```

[core-limits]: https://www.stedi.com/docs/edi-core/limits
[typescript]: https://www.typescriptlang.org/


Sending compressed payloads


# Frequently asked questions

Below is a list of frequently asked questions about the EDI Core API. If you have any questions not listed here, please [contact us](https://www.stedi.com/contact).

## Data & Privacy

### How does the EDI Core API use my data?

In short, we don’t. The payloads sent to the `translate` API are not stored – temporarily or permanently. The contents of your file are encrypted in transit.

### Is data sent to the EDI Core API stored?

The `translate` API is a stateless system that executes a transformation on your data. The transformation happens during the duration of the request; we do not retain the payload once a response is returned.

### What does Stedi log when I hit the EDI Core API?

We log only request meta information such as the size of the request, latency, transaction sets, and release.

These data points allow our engineers to monitor the health of the system and drive improvements to the service. They help the team answer questions like:

- How many requests did the API receive over the past week?
- What percentage of the responses returned a 4XX/5XX status code?
- Why did latency increase after the most recent deployment?

If a request fails with a 500 status code, an engineer on the team is notified (yes, we investigate every single one).


FAQs


# Glossary

## Composite element

A single [element](#element) that contains multiple values of different types, similar to a struct or record. The [specification](#specification) will specify which fields makes up a composite element. The values in a composite element are kept apart by a [delimiter](#delimiter). The delimiter to use is specified in the [interchange](#interchange) header. In the following example, values are delimited using a `:`.

```
PRV*LA***ORT:HS:Y~
```

## Delimiter

A delimiter is used in the [X12 EDI Format](#x12-edi-format) to mark the end of a [segment](#segment) or [element](#element). The end of a [segment](#segment) is [delimited](#delimiter) by a `~` and the end of an [element](#element) by a `*`. Here's an example of two segments, both with three elements.

```edi
SE*2*0000~
GE*1*987654321~
```

There are also delimiters for [repeated elements](#repeated-element) and [composite elements](#composite-element), but these aren't standardized. Instead, these delimiters are specified in the [interchange](#interchange).

## Element

An element is a data field within a [segment](#segment). In the [X12 EDI Format](#x12-edi-format), elements in a [segment](#segment) are delimited by a `*`. For example, here's a [segment](#segment) with several elements.

```edi
GS*SO*00*00*20210902*1200*987654321*X*008010~
```

The values an element may contain, are described in a [specification](#specification).

## EDI (Electronic Data Interchange)

EDI allows businesses to exchange electronic documents, like invoices, insurance applications, train sheets, credit reports. There are several standards related to EDI. Most relevant to working with Stedi are the [specifications](#specification) of [transaction sets](#transaction-set) and the [X12 EDI Format](#x12-edi-format).

## Functional group

Within an [EDI](#edi) file, a functional group is a set of [transaction sets](#transaction-set). Typically, all the [transaction sets](#transaction-set) within a functional group are intended for the same department within an organization.

The beginning of a functional group is marked by the [GS](https://edi.stedi.com/x12-008010/segment/GS) [segment](#segment) and the end is marked by the [GE](https://edi.stedi.com/x12-008010/segment/GE) \[segment]\[#segment]. A functional group must be part of an [interchange](#interchange).

## Interchange

Within an [EDI](#edi) file, an interchange is a set of [functional groups](#functional-group) which in turn contain [transaction sets](#transaction-set). Typically, the contents of an interchange is intended for a specific organization and the contents of a [functional group](#functional-group) is intended for a specific department within that organization.

The beginning of an interchange is marked by the [ISA](https://edi.stedi.com/x12-008010/segment/ISA) [segment](#segment) and the end is marked by the [IEA](https://edi.stedi.com/x12-008010/segment/IEA) [segment](#segment). Every EDI file must have at least one interchange and consequently, every EDI file starts with an [ISA](https://edi.stedi.com/x12-008010/segment/ISA) [segment](#segment) and ends with an [IEA](https://edi.stedi.com/x12-008010/segment/IEA) [segment](#segment).

## JEDI (JSON EDI)

A file format for encoding [EDI](#edi) data in a JSON representation, developed by Stedi. You can find details in the [JEDI Format Guide](https://www.stedi.com/docs/edi-core/jedi-format).

## Loop

A loop is a collection of [segments](#segment) that can appear multiple times in a [transaction set](#transaction-set). The [segments](#segment) in a loop typically have a semantic relationalship, for example, the segments Party Identification, Geographic Location, and Communication Contact Information together can tell you about a single [trading partner](#trading-partner) and a loop of those segments allows you to refer to multiple [trading partners](#trading-partner) in a [transaction set](#transaction-set).

In [X12 EDI Format](#x12-edi-format), there's no special [delimiter](#delimiter) for loops, nor is there a set of [segments](#segment) that mark the begin and end of the loop, like there is for [interchanges](#interchange), [functional groups](#functional-group), and [transaction sets](#transaction-set). Instead, the segments in the loop are just repeated.

```edi
N1*21*Stedi*ZZ*ID001~
N4*New York**US~
COM*16*stedi.com~
N1*21*Basic Bits*ZZ*ID002~
N4*Haarlem**NL~
COM*16*basicbits.tech~
```

## Repeated element

A single [element](#element) that contains multiple values of the same type, similar to a homogeneous array. Not every [element](#element) can be repeated; the [specification](#specification) must indicate that it's okay to do so.

In [X12 EDI Format](#x12-edi-format), the values in a repeated element are kept apart by a [delimiter](#delimiter). The delimiter to use is specified in the [interchange](#interchange) header. In the following example, values are delimited using a `/`.

```edi
AAA*Y***NF/NR/TO~
```

## Repeated segment

Within an [EDI](#edi) file, some segments can occur multiple times in a row. The [specification](#specification) will tell when a segment can be repeated.

In [X12 EDI Format](#x12-edi-format)], a repeated segment appears as, well, a segment that's repeated.

```edi
NTE**When a segment has need to repeat,~
NTE**How does one accomplish that feat?~
NTE**It's really no bother.~
NTE**One after the other.~
NTE**A solution that's simple and neat.~
```

## Segment

Within an [EDI](#edi) file, a segment is a set of [elements](#element), where the segment is like a record and the [elements](#element) are its fields. Each segment starts with a segment identifier that tells you which [elements](#element) will follow. The different types of segments and their elements are listed in the [specification](#specification).

In the [X12 EDI Format](#x12-edi-format), segments are [delimited](#delimiter) by a `~`. It's also common to add a new line character after the [delimiter](#delimiter), but that's for human readability only and has no semantic value.

## Specification

A specification describes the data schema of a [transaction set](#transaction-set). It lists the [loops](#loop) and [segments](#segment), the order in which they appear, and the [elements](#element) within the [segments](#segment). The specification gives you all the information you need to write or interpret an [EDI](#edi) document that conforms to that specification.

[X12](#x12) has published [many specifications](https://edi.stedi.com/). A [trading partner](#trading-partner) can use these specifications directly, or they can base their own specification on one of them.

## Trading partner

Any business that sends or receives business transactions.

## Transaction set

A transaction set is a type of business document, for example a purchase order, or a booking cancellation. Each transaction set is based on a [specification](#specification) that describes what data the transaction set can and must contain. There is a [list of standardized transaction sets](https://edi.stedi.com/).

The standard transaction sets are designed to be widely applicable. A [trading partner](#trading-partner) can take a transaction set, base its own [specification](#specification) on it, and only accept the data it knows how to handle. Many of these [business-specific transaction sets are available on Stedi](https://edi.stedi.com/specifications).

## X12

An organization that has published many standards related to [EDI](#edi).

## X12 EDI Format

A file format for encoding [EDI](#edi) data, standardized by [X12](#x12). It's text-based and makes use of [delimiters](#delimiter) to mark the [segments](#segment) and [elements](#element). It looks something likes this.

```edi
ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*|*00801*123456789*1*T*:~
GS*SO*00*00*20210902*1200*987654321*X*008010~
ST*326*0000~
SE*2*0000~
GE*1*987654321~
IEA*1*123456789~
```


Glossary


# JEDI Format

JEDI is a JSON representation of an EDI document. Normally, an EDI document is represented in X12 EDI Format and looks something like this.

```edi
ISA*00*          *00*          *ZZ*               *ZZ*               *210902*1200*/*00801*123456789*1*T*:~
GS*SO*00*00*20210902*1200*987654321*X*008010~
ST*326*0000~
SE*2*0000~
GE*1*987654321~
IEA*1*123456789~
```

It's a compact format, well suited for sending over the wire, but it isn't convenient when you want to process it in code. Most programming languages have support for working with JSON, so it would be nice to have the same data in JSON format and that's what JEDI provides.

```json
{
  "interchanges": [
    {
      "interchange_control_header_ISA": {
        "authorization_information_qualifier_01": "no_authorization_information_present_no_meaningful_information_in_i02_00",
        "authorization_information_02": "",
        "security_information_qualifier_03": "no_security_information_present_no_meaningful_information_in_i04_00",
        "security_information_04": "",
        "interchange_id_qualifier_05": "mutually_defined_ZZ",
        "interchange_sender_id_06": "",
        "interchange_id_qualifier_07": "mutually_defined_ZZ",
        "interchange_receiver_id_08": "",
        "interchange_date_09": "210902",
        "interchange_time_10": "1200",
        "repetition_separator_11": "/",
        "interchange_control_version_number_code_12": "00801",
        "interchange_control_number_13": "123456789",
        "acknowledgment_requested_code_14": "interchange_acknowledgment_requested_ta1_1",
        "interchange_usage_indicator_code_15": "test_data_T",
        "component_element_separator_16": ":"
      },
      "groups": [
        {
          "functional_group_header_GS": {
            "functional_identifier_code_01": "ocean_shipment_information_304_311_317_319_322_323_324_325_326_361_SO",
            "application_senders_code_02": "00",
            "application_receivers_code_03": "00",
            "date_04": "20210902",
            "time_05": "1200",
            "group_control_number_06": "987654321",
            "responsible_agency_code_07": "accredited_standards_committee_x12_X",
            "version_release_industry_identifier_code_08": "008010"
          },
          "transaction_sets": [
            {
              "heading": {
                "transaction_set_header_ST": {
                  "transaction_set_identifier_code_01": "326",
                  "transaction_set_control_number_02": "0000"
                },
                "transaction_set_trailer_SE": {
                  "number_of_included_segments_01": "2",
                  "transaction_set_control_number_02": "0000"
                }
              },
              "type": "326"
            }
          ],
          "functional_group_trailer_GE": {
            "number_of_transaction_sets_included_01": "1",
            "group_control_number_02": "987654321"
          }
        }
      ],
      "interchange_control_trailer_IEA": {
        "number_of_included_functional_groups_01": "1",
        "interchange_control_number_02": "123456789"
      },
      "delimiters": {
        "element": "*",
        "segment": "~",
        "sub_element": ":",
        "repetition": "/"
      }
    }
  ]
}
```

You can translate to the new JEDI 2.0 format by [making an API call](https://www.stedi.com/docs/edi-core#translation) using `jedi@2.0` as the `output` format.

## Structure

The purpose of an EDI file is to exchange business documents: invoices, requisition orders, shipping instructions, [you name it](https://edi.stedi.com/x12-008010). Each such a document is a _transaction set_ in EDI parlance.

An EDI file often contains multiple transaction sets and they don't all need to be of the same type. It's no problem, for example, to send invoices and requisition orders all in one go. However, when you receive such a file, it's convenient if you can tell which transaction sets are intended for the finance department and which should be sent to the warehouse. This is where _functional groups_ can help out. You put all the invoices in one functional group and all the requistion orders in another, and now it's easy to route them within your organization.

It's even possible to put transaction sets intended for different organizations into one EDI file. In that case, you wrap them in an _interchange_.

So, an EDI file contains one or more interchanges, an interchange contains one or more functional groups, and a functional group contains one or more transaction sets. This same structure is reflected in JEDI.

```json
{
  "interchanges": [
    {
      "groups": [
        {
          "transaction_sets": []
        }
      ]
    }
  ]
}
```

## Transaction sets

Within a transaction set, segments are grouped into three sections: heading, detail, and summary. This is reflected in JEDI, where a transaction set has the following structure.

```json
{
  "heading": {},
  "detail": {},
  "summary": {}
}
```

Not all sections have to be present. For example, the following invoice doesn't include details.

```json
{
  "heading": {
    "transaction_set_header_ST": {
      "transaction_set_identifier_code_01": "810",
      "transaction_set_control_number_02": "0000"
    },
    "beginning_segment_for_invoice_BIG": {
      "date_01": "20210902",
      "invoice_number_02": "AB01010101"
    }
  },
  "summary": {
    "total_monetary_value_summary_TDS": {
      "amount_01": "999"
    },
    "transaction_set_trailer_SE": {
      "number_of_included_segments_01": "4",
      "transaction_set_control_number_02": "0000"
    }
  }
}
```

## Segments

In EDI, all data is represented in the form of a _segment_. A segment starts with an identifier, which lets you know what type of segment you're dealing with. It's followed by a list of values. If you want to know what those values mean, you have to take the segment identifier and [look it up](https://edi.stedi.com/x12-008010/segment). For example, the [ST segment](https://edi.stedi.com/x12-008010/segment/ST) marks the start of a new transaction set and has three elements: identifier code, control number, and implementation convention reference. In that order.

In X12 EDI Format, a segment looks like this.

```edi
ST*810*1~
```

The elements in the segment are delimited with a `*` and the end of the segment is marked by a `~`. The identifier `ST` marks this as the start of a transaction set. [`810` is the code for an invoice](https://edi.stedi.com/x12-008010/810). `1` is the number of this transaction set within the functional group. The third element for this segment is optional and it's omitted here.

In JEDI, the same segment would look like this.

```json
"transaction_set_header_ST": {
  "transaction_set_identifier_code_01": "810",
  "transaction_set_control_number_02": "1"
}
```

### Loops

A transaction set can have a collection of segments that belong together and can occur multiple times. This is called a _loop_. For example, an invoice can have multiple items. In JEDI, that would look like this.

```json
{
  "detail": {
    "baseline_item_data_invoice_IT1_loop": [
      {
        "baseline_item_data_invoice_IT1": {
          "assigned_identification_01": "PL123",
          "quantity_invoiced_02": "3",
          "unit_or_basis_for_measurement_code_03": "hectoliter_H4",
          "unit_price_04": "1250",
          "basis_of_unit_price_code_05": "standard_ST"
        },
        "currency_CUR": {
          "entity_identifier_code_01": "country_CY",
          "currency_code_02": "NZL"
        }
      },
      {
        "baseline_item_data_invoice_IT1": {
          "assigned_identification_01": "PL897",
          "quantity_invoiced_02": "1",
          "unit_or_basis_for_measurement_code_03": "hectoliter_H4",
          "unit_price_04": "825",
          "basis_of_unit_price_code_05": "standard_ST"
        },
        "currency_CUR": {
          "entity_identifier_code_01": "country_CY",
          "currency_code_02": "NZL"
        }
      },
      {
        "baseline_item_data_invoice_IT1": {
          "assigned_identification_01": "SQ555",
          "quantity_invoiced_02": "10",
          "unit_or_basis_for_measurement_code_03": "microliter_4G",
          "unit_price_04": "20",
          "basis_of_unit_price_code_05": "standard_ST"
        },
        "currency_CUR": {
          "entity_identifier_code_01": "country_CY",
          "currency_code_02": "NZL"
        }
      }
    ]
  }
}
```

This loop contains three items. Note the following.

- The key for the loop is the same as the segment identifier of the first item in the loop, suffixed by `_loop` (`baseline_item_data_invoice_IT1_loop` in the example above).
- The items in the loop are contained in an array.
- Each item is its own JSON object.

### Repeated segments

Sometimes, a segment may be repeated even outside of a loop. For example, an invoice has a [Note segment (`NTE`)](https://edi.stedi.com/x12-008010/segment/NTE) that can be repeated, allowing a note with many lines. In X12 EDI Format, this segment simply appears many times.

```edi
NTE**This is a note~
NTE**With many a line~
NTE**A segment repeated~
NTE**Can store this just fine~
```

JEDI puts these repeated segments into an array, with one object per segment.

```json
{
  "heading": {
    "note_special_instruction_NTE": [
      {
        "description_02": "This is a note"
      },
      {
        "description_02": "With many a line"
      },
      {
        "description_02": "A segment repeated"
      },
      {
        "description_02": "Can store this just fine"
      }
    ]
  }
}
```

### Sequence IDs

Some segments will return with a sequence ID. For example, `3310` is the sequence ID below.

```json
"loop_LS_3310": {
  "loop_trailer_LE": {
    "loop_identifier_code_01": "0001"
  },
  "loop_header_LS": {
    "loop_identifier_code_01": "0001"
  },
  "loop_entries": [...]
}
```

Where does this `_3310` come from?

A transaction set is based on a specification. The specification tells you which segments make up a transaction set. If you take a look at the [specification for an mortgage credit report](https://edi.stedi.com/x12-008020/200), you'll see that each segment has a sequence number. One type of segment can appear multiple times in a transaction set, at the same level. For example, a mortgage credit report contains multiple `LS` segments. The sequence number helps to uniquely identify each segment. In X12 EDI Format, the sequence number is implicit based on the position of the segment in the transaction set, but JEDI makes the sequence number explicit by putting it in front of the segment identifier when needed.

## Elements

In EDI, elements are the individual pieces of data in the file, like a cell in a spreadsheet. All JEDI elements are transmitted as strings to avoid data loss, but numerical values can be converted to lossless number formats in your code.

### Repeated elements

Some elements can be repeated within their segment. For example, the last element of the [Request Validation segment (`AAA`)](https://edi.stedi.com/x12-008010/segment/AAA) can contain one or more error reason codes. In X12 EDI Format, that looks like this.

```edi
AAA*Y****NF/NR/TO~
```

The last element contains three values, delimited by a `/`. [The delimiter for repeated elements is specified in the ISA header.](https://edi.stedi.com/x12-008010/element/I65) In JEDI, the values are collected in an array.

```json
"request_validation_AAA": [
  {
    "yes_no_condition_or_response_code_01": "yes_Y",
    "error_reason_code_05": [
      "NF",
      "NR",
      "TO"
    ]
  }
]
```

### Composite elements

A single element can be made up of multiple values if it's a composite element. Where a repeated element has multiple values for the same field, a composite element is like a structure with its own fields. For example, the [Provider Information segment (`PRV`)](https://edi.stedi.com/x12-008010/segment/PRV) has a composite element [Provider Specialty Information (`CO35`)](https://edi.stedi.com/x12-008010/segment/PRV) and that element has three fields of its own. The values in a composite element are delimited by a `:`. [The delimiter for composite elements is specified in the ISA header.](https://edi.stedi.com/x12-008010/element/I15)

```edi
PRV*LA****ORT:HS:Y~
```

JEDI represents a composite element as an element nested in an element.

```json
"provider_information_PRV": {
  "provider_code_01": "laboratory_LA",
  "provider_specialty_information_05": {
    "provider_specialty_code_01": "ORT",
    "agency_qualifier_code_02": "department_of_health_and_human_services_HS",
    "yes_no_condition_or_response_code_03": "yes_Y"
  }
}
```

### Data Formats

X12 data elements have a schema defined which can be looked up at [edi.stedi.com](https://edi.stedi.com). Most will be treated as plain strings and the values are passed through between JEDI and EDI without any changes, but we modify the values of a couple to make them easier to work with in JEDI.

#### Codes

In many cases, X12 will use a short string in place of a more verbose string that is included in the documentation. In order to avoid needing to have the [documentation](https://edi.stedi.com) open while reading JEDI, the service will replace codes with the description value. For example, if you see the code `50` in an [beer information segment](https://edi.stedi.com/x12-008020/segment/BER) it would say "Dark British Beer-Oatmeal Stout". In JEDI, the value of `50` will be replaced by `dark_british_beer_oatmeal_stout_50`. When converting from JEDI to EDI, both `50` and `dark_british_beer_oatmeal_stout_50` are converted to `50`.

#### Numbers

- Numeric `Nn`: numeric type elements are defined by 2 characters. The first is `N` which says it is numeric and is followed by a digit that says where the decimal place should go. For example, if we have an element of type `N2` and the value is `1234` in an EDI document it will become `12.34` in JEDI. When converting from JEDI to EDI, `12.34` will become `1234`, but if you pass `1234` when converting from JEDI to EDI, it will be rendered as `123400` in EDI.
- Decimal Number `R`: JEDI will not make any changes to this number format, but if the length of the string is longer than defined by X12, a validation error will be returned from `/translate` to indicate that the number might be too wide to be accepted by the receiving service.

## Delimiters

The X12 EDI Format uses delimiters to separate segments and elements. By default, segments are delimited by a `~` and elements by a `*`. Values in composite and repeated elements are delimited by whatever you specify in the ISA header. The JEDI format doesn't need these delimiters. Still, if you want to translate an EDI document from JEDI to X12 EDI Format, EDI Core has to add delimiters, so JEDI stores the delimiters in a required field called `delimiters`.

```json
{
  "interchanges": {
    "delimiters": {
      "element": "*",
      "segment": "~",
      "sub_element": ":",
      "repetition": "/"
    },
    "groups": ...,
    "interchange_control_header_ISA": ...,
    "interchange_control_trailer_IEA": ...
  }
}
```

## Optional Trailers

X12 EDI surrounds groups of segments with envelopes in some cases. If you look at the example JEDI file above, you will see 3 sets of envelopes that consist of a header and trailer. The trailer may be omitted when converting from JEDI to EDI. The service can infer the values needed for those segments from the matching header and the contents of the envelope. If the JEDI document includes the trailers, the service will not replace the values submitted.

1.  `interchange_control_header_ISA`/`interchange_control_trailer_IEA`: number of functional groups and control number
2.  `functional_group_header_GS`/`functional_group_trailer_GE`: number of transaction sets and control number
3.  `transaction_set_header_ST`/`transaction_set_trailer_SE`: number of included segments and control number


JEDI Format


# JEDI Specification

## Overview

JSON EDI (JEDI) is our proposed format for allowing customers to work with tools they are familiar with while still supporting conversion to and from EDI without any loss of fidelity. This document describes how a JEDI is structured and how it maps to an EDI file. This document assumes you have a general understanding of the EDI document format.

## Definitions

### Envelopes

An EDI transaction is wrapped in a series of 3 envelopes (a pre and post segment that wraps around inner information) that supply metadata about the transaction. Each envelope can be repeated so in the JSON form you will see arrays.

- Interchange control: (ISA/IEA) the outer most envelope. The data is at the top level of the JEDI document as the keys:
  - ISA: fields from the ISA segment
  - IEA: fields from the IEA segment
  - value: array of functional groups defined in this envelope
- Functional group: (GS/GE) in the 2nd layer and is represented as the envelopeGroup key at the top level. envelopeGroup is an array. Each object in the array has the following keys:
  - GS: fields from the GS segment
  - GE: fields from the GE segment
  - value: array of transactions defined in this envelope
- Transaction Set: (ST/SE) is the final layer that represents the an EDI transaction with the envelopeTransactionSet key
  - ST: fields from the ST segment
  - SE: fields from the SE segment
  - value: contents of the transaction

### Delimiters

EDI files are split by 3 different delimiters defined in the first (ISA) segment of the document. They are included in the document to ensure round trip rendering. There doesn't appear to be a standard for delimiters. The top level of a JEDI document contains a key called delimiters with the character used for each delimiter. Each delimiter must be a single character and unique within the delimiters. Often, EDI files have an additional \n at the end of each segment that is there for legibility but acts as whitespace.

- segment
- element
- subElement

#### Example

```EDI
ISA*00*          *00*          *ZZ*SENDER         *ZZ*RECEIVER       *201120*1204*U*00401*000000350*0*P*^~
```

Will extract the delimiters into

```JSON
{
  "segment": "~",
  "element: "*",
  "sub_element": "^",
  "repetition": "@"
}
```

### Elements

Individual data elements in a segment are called elements. The EDI documentation describes how the text of the element should be converted to numbers, text, or binary data. In JEDI, everything not defined as a number element will be rendered to the JSON as a string. Numbers will be saved as JSON numbers.

### Composites

Some elements are further broken into smaller pieces called sub elements. In this case, instead of scalar value in the JSON document, you will see another JSON object with keys from the subelements inside. All composite element ids start with a C followed by a 3 digit number.

### Segments

In EDI, a segment is prefixed by the segment id and then followed by 1 or more data elements separated by element delimiters and ended with a segment delimiter. In JEDI, the segment becomes a JSON object. The key of the segment in the JSON document will be its sequence id + the segment id. For example, line 5 in the EDI example below is an MIT segment. In JEDI, the key will be 100-MIT like it is described on edi.stedi.com.

#### Example (Segment)

The following SPT (Spirit and Liqueur Information) segment:

```EDI
SPT*AB*SG***01^^107***~
```

turns into:

```JSON
{
  "0100_SPT": {
    "type": "segment",
    "value": {
      "01_1823": { "type": "data_element", "value": "AB"},
      "02_1824": { "type": "data_element", "value": "GS" },
      "05_C075": {
        "type": "composite_data_element",
        "value": {
          "01_1827": { "type": "data_element", "value": "01" },
          "03_1827": { "type": "data_element", "value": "107" }
        }
      }
    }
  }
}
```

Notice that there is no entry in the map 03-1825 or 04-1826. Blank elements are not included in the map and will be rendered as an empty string when converting to EDI. The same thing happens inside of the composite element where 02-1827 is omitted.

### Repeated Segments

Many segments can be repeated. In this case, the child of the segment key, will be an array of segment objects instead of an object.

#### Example (Repeated Segment)

The following MSG segment:

```EDI
MSG*Your pizza is ready*NP
MSG*extra hot*NP
```

turns into

```JSON
{
  "0800_MSG": {
    "type": "segment_repeat",
    "value": [
      {
        "01_933": {"type": "data_element", "value": "Your pizza is ready" },
        "02_934": {"type": "data_element", "value": "NP" }
      },
      {
        "01_933": {"type": "data_element", "value": "extra hot" },
        "02_934": {"type": "data_element", "value": "NP" }
      }
    ]
}
```

### Loops

Some groups of segments are defined as loops in EDI. These will be shown as an array of segment maps.

#### Example (Loop)

The following MIT loop:

```EDI
MIT*999994627**80*55
MSG*Your pizza is ready*NP
```

turns into

```JSON
{
  "loop_MIT": {
    "type": "loop",
    "value": [
      {
        "0100_MIT": {
          "type": "segment",
          "value": {
            "01_127": {"type": "data_element", "value": "999994627" },
            "03_931": {"type": "data_element", "value": 80 },
            "04_932": {"type": "data_element", "value": 55 }
        }
      },
        "0800_MSG": {
          "type": "segment_repeat",
          "value": [
          {
            "01_933": {"type": "data_element", "value": "Your pizza is ready" },
            "02_934": {"type": "data_element", "value": "NP" }
          }
        ]
      }
    }
  ]
}
```

### Areas

The X12 definition for EDI put segments into 3 areas: heading, detail, and summary. The JEDI format uses the X12 data to put segments into the correct area.


JEDI Specification


The EDI Core API has a few limits on how you can use the service. If you are impacted, please let us know and we would be happy to work to help meet your needs. The request and response sizes are limited by the size of the HTTP request. You can receive more data if you set the `accept-encoding` header to `gzip`. The API can also accept a [gzip compressed request][compression].

| Limit                       |             | Can be increased |
| --------------------------- | ----------- | ---------------- |
| Requests per second         | 25          | Yes              |
| Maximum concurrent requests | 100         | Yes              |
| Maximum request size        | 4 megabytes | No               |
| Maximum response size       | 6 megabytes | No               |

[compression]: https://www.stedi.com/docs/edi-core/compression



The EDI Core API is billed based on usage. There are no minimum fees, monthly commitments, or upfront costs to use this product.

Usage of the /translate endpoint is billed based on request count and MB processed.

A request is defined as a single call to the EDI Core API, regardless of how many transactions (e.g. ST segments) are in the payload.

## Pricing tiers

### API request count pricing

The first 1,000 requests per month are free.

| **Request Count per Month** | **Price**           |
| --------------------------- | ------------------- |
| First 1,000                 | Free                |
| Above 1,000                 | $0.0075 per request |

### API bytes processed per request pricing

The first 5 MB of data processed per month are free.

| **Data Processed per Month** | **Price**      |
| ---------------------------- | -------------- |
| Up to 5 MB\*                 | Free           |
| Above 5 MB                   | $0.0512 per MB |

[Contact us](https://www.stedi.com/contact) if you have a question on pricing or for a volume discount (minimum 250K requests per month)

\*1 MB = 1024 KB or 1,048,576 bytes

## Examples

### Shipment status (214) feed

The EDI Core `/translate` endpoint is used to convert batched X12 EDI 214s from a shipping partner into JEDI bound for a retailers' ERP. Each EDI 214 document contains 300 transactions, resulting in an average file size of 150 KB. The shipping partner sends a batch every 30 minutes, every day of the week, resulting in 1,488 EDI 214s every month.

```text
First 1,000 requests = $0.00
Next 488 requests = 488 * $0.0075 = $3.66
Total for all requests = $3.66

Total bytes processed = 150 KB * 1,488 requests = 217.97 MB
First 5 MB = $0.00
Next 212.97 MB = 212.97 * $0.0512 = $10.90
Total for all requests = $10.90

$3.66 + $10.90 = $14.56 total
$14.56 / 1,488 requests = $0.009788 per request
```

### Medium volume purchase order (850) feed

The EDI Core `/translate` endpoint is used to convert JEDI 850s to X12 EDI 850s to generate purchase orders for vendors. The retailer generates 25,500 X12 EDI 850s each month, and each JEDI file is an average of 1.5 KB in size.

```text
First 1,000 requests = $0.00
Next 24,500 requests = 24,500 * $0.0075 = $183.75
Total for all requests = $183.75

Total bytes processed = 1.5 KB * 25,500 requests = 37.35 MB
First 5 MB = $0.00
Next 32.35 MB = 32.35 * $0.0512 = $1.66
Total for all requests = $1.66

$183.75 + $1.66 = $185.41 total
$185.41 / 25,500 requests = $0.007271 per request
```

### Hourly inventory (846) feed

The EDI Core `/translate` endpoint is used to convert X12 EDI 846 Inventory Inquiry/Advice to the JEDI equivalent in order to exchange inventory data with trading partners. A customer receives 10,000 KB (10MB) EDI 846s once an hour every day, totaling 720 files over the course of a month.

```text
First 1,000 requests = $0.00
Total for all requests = $0.00

Total bytes processed = 10,000 KB * 720 requests = 7,031.25 MB
First 5 MB = $0.00
Next 7,026.25 MB = 7,026.25 * $0.0512 = $359.74
Total for all requests = $359.74

$0.00 + $359.74 = $359.74 total
$359.74 / 720 requests = $0.499644 per request
```


EDI Core


The Functions service has a few limits in place on usage. If you are impacted or blocked by any of these restrictions, please let us know and we would be happy to help meet your needs.

| Resource or operation                                | Default limit  | Can be increased |
| ---------------------------------------------------- | -------------- | ---------------- |
| Maximum concurrent invocations per second            | 50             | Yes              |
| Maximum request size                                 | 4 megabytes    | No               |
| Maximum response size                                | 6 megabytes    | No               |
| Maximum bundled code size per function               | 3.25 megabytes | No               |
| Memory available in Function runtime                 | 1024 megabytes | Yes              |
| Maximum function duration                            | 15 minutes     | No               |
| Maximum size of environment variables (all combined) | 4 kilobytes    | No               |



You can invoke a Stedi function automatically when certain events occur in other Stedi products. This allows you to kick off an automated workflow. For example, when a trading partner uploads an EDI message to a bucket, the function can pick it up, call EDI Translate, and send the result to your internal API.

## Stedi Buckets

Stedi Buckets is the only product that supports sending notifications right now. It can invoke a function whenever an object is added to a bucket. You enable these notifications by configuring the bucket that sends them. You don’t need to configure anything on the side of the function.

> See also\
> [Overview: Bucket notifications](/docs/buckets/notifications)\
> [Reference: Update bucket notifications with the JavaScript SDK](/docs/buckets/sdk#updatecommandobject)\
> [Reference: Update bucket notifications with the Web API](/docs/api/buckets#UpdateBucket)


You can invoke a Stedi function automatically when certain events occur in other Stedi products.

Notifications

Functions SDK


In this tutorial, we will show you how to deploy your first Stedi Function using our API. You can find more detailed information in the [API docs](/docs/api/functions).

## Authentication

Before you can get started with the API, you need an API key. If you already have an API key for another Stedi product, you can use that here as well; you don’t need a separate key for Functions.

Once you have the key, include it in every call to the API as part of the Authorization header of the HTTP request.

```
Authorization: Key your-api-key
```

If you’d like more information about authentication, take a look at our [Authentication guide](/docs/accounts-and-billing/authentication).

## Basics

### Code template

Your code must include a function called `handler` that looks like the following.

```javascript
exports.handler = async function (event, context) {
  return {};
};
```

An `event` is a JSON-formatted document that you pass in when you invoke the function; it contains data for a function to process. `context` contains information about the execution environment that the function is running in.

When writing a function, you should always return a value, or you’ll receive an error. Other than that, the return value is up to you.

#### Create a Function using the UI

In the [web UI](/app/functions), you can create a function by clicking _Create function_, adding code to the editor, and clicking _Save_. You cannot include libraries or additional packages using this method, for that you can find instructions [here](#providing-code-as-a-zipped-package-via-api).

#### Create a Function using the API

You can also create functions via the API. The following example creates a new function called `example-function` and includes the JavaScript code as a string.

```http
POST https://functions.cloud.us.stedi.com/2021-11-16/functions HTTP/1.1
Content-Type: application/json
Authorization: Key your-api-key

{
  "functionName": "example-function",
  "code": "exports.handler = async function (event, context) {\n  console.log('This is exciting!');\n  return { greeting: 'Hello, world!' }\n};"
}
```

A major downside of both the UI and the API methods shown above is that you can’t include multiple files, such as external packages. You can remedy this by creating a deployment package — which is a zip file with multiple files that include your code and libraries—and passing that via API instead.

#### Providing code as a zipped package via API

With this method, you include the zip file as a base64-encoded string in the API request. There are a few steps involved to create the zip file for every deployment:

- Run 'npm build' to download all required node modules.
- Create a zip file with your code and modules.
- Convert the zip file to a base64-encoded string.
- Deploy the base64-encoded package by making a request to the Functions API.

We encourage to do this through our deployment scripts linked on the [Stedi Demos on GitHub](https://github.com/Stedi-Demos/simple-function). In the web-request tutorial, you can find instructions for how to use the build script to create or update functions.

### Invoke a Function using the UI

In the [Functions UI](/app/functions), you can invoke your function by clicking _Execute_. Do remember to save your function before executing it. If you uploaded a package using the API, the UI won’t show the code of your function. You can still invoke it, though.

When the function is done, you can view the invocation result, which includes the function return value and the logs.

<picture>
  <source srcSet="/images/docs/functions/tutorial/image-1.png" media="(prefers-color-scheme: dark)" />

  <img alt="Screenshot of Stedi Terminal homepage" src="/images/docs/functions/tutorial/image-2.png" />
</picture>

### Invoke a function using the Stedi Functions SDK

You can also invoke a function using the Stedi SDK for JavaScript, which can be installed using `npm install -g @stedi/sdk-client-functions@0.0.x`. Once the SDK is installed, you could invoke a function and see the log response returns.

```javascript
const { FunctionsClient, InvokeFunctionCommand } = require("@stedi/sdk-client-functions");

const apiKey = "<replace-me>"; // Your Stedi API key
const functionName = "example-function"; // Your Stedi Function's name

// Create a Functions client
const client = new FunctionsClient({
  region: "us",
  apiKey: apiKey
});

async function main() {
  const output = await client.send(
    new InvokeFunctionCommand({
      functionName: functionName,
      requestPayload: Buffer.from(JSON.stringify({ name: "Functions Customer" }), "utf-8")
    })
  );

  const response = Buffer.from(output.responsePayload!).toString("utf-8");
  console.log("Function response:\n\n" + response + "\n");

  // Optional: Up to 4kb worth of the function's log output is returned in the invoke function response
  const logs = Buffer.from(output.invocationLogs!, "base64").toString("utf-8");
  console.log("Function logs:\n\n" + logs);
}

main();
```

### Passing data into a function

When you invoke a function, you can pass data into it. This data is available in the function through the `event` object.

The following function expects you to pass in a name and will echo that name to the log, with a little embellishment.

```javascript
exports.handler = async function (event, context) {
  console.log(`Well hello, my dear ${event.name}.`);
  return {
    greeting: `Hello, ${event.name}!`,
  };
};
```

#### Passing data into a function using the UI

If you click on _Edit invocation payload_, you can type in the input you want to pass to the function.

The invocation payload will be saved in your browser’s local storage, so you won’t have to type it in each time.

<picture>
  <source srcSet="/images/docs/functions/tutorial/image-1.png" media="(prefers-color-scheme: dark)" />

  <img alt="Screenshot of Stedi Terminal homepage" src="/images/docs/functions/tutorial/image-2.png" />
</picture>

### Updating a function

Updating a function is similar to creating a function: you can specify code as a string in the `code` field or as a zipped package in the `package` field. The differences are that you specify the function name in the URL instead of the body and that you use PUT instead of POST.

```http
PUT https://functions.cloud.us.stedi.com/2021-11-16/functions/example-function/ HTTP/1.1
Content-Type: application/json
Authorization: Key your-api-key

{
  "code": "exports.handler = async function (event, context) {\n  console.log('This is familiar.');\n  return { greeting: 'Hello again.' }\n};"
}
```

### Using third-party libraries

You can use any third-party library you want by zipping it along with your own code. This does require you deploy your function using the API, because the Functions UI doesn’t yet support zipped packages.

### A JavaScript example

For example, the following code translates Markdown to HTML, but it requires the Marked library to do so.

```javascript
import { marked } from "marked";

exports.handler = async function (event, context) {
  return { html: marked.parse(event.markdown) };
};
```

You can install the Marked library locally by running npm.

```bash
npm install marked
```

You then create a package by zipping the `node_modules` directory along with your function code.

```bash
zip package -r index.js node_modules/
```

After you’ve base64-encoded the zipped package, you can use it to [create a new function](#create-a-function-using-the-ui) or [update an existing one](#updating-a-function). For example, the following curl command updates `example-function`. Just make sure you set the environment variable `STEDI_API_KEY` to your API key.

> Other than the Stedi API key, you shouldn’t store secrets in environment variables. If your function needs access to passwords, API keys, and the like, store them in [Stash](/docs/stash) and access Stash from your function. The Stedi API key is the only exception, because you need it to access Stash.

```bash
curl --request PUT https://functions.cloud.us.stedi.com/2021-11-16/functions/example-functions \
  --header "Content-Type: application/json" \
  --header "Authorization: Key ${STEDI_API_KEY}" \
  --data-raw "{
    \"package\": \"$(base64 -i package.zip)\"
  }"
```

When calling this function, you need to [pass in](#passing-data-into-a-function) some Markdown, which doesn’t look pretty when you’re using curl, but that doesn’t mean it’s hard.

```bash
curl --request POST https://functions.cloud.us.stedi.com/2021-11-16/functions/example-function/invocations \
  --header "Authorization: Key ${STEDI_API_KEY}" \
  --header "Accept: application/octet-stream" \
  --data-raw "{ \"markdown\": \"# Greetings\nHello, world\" }"
```

### Calling web APIs

A function has access to the wider Internet, meaning you can call any public web API. The following example calls Stedi’s [EDI Core API](/docs/edi-core) because we like to promote our own products, but the principle is the same for any web API.

```javascript
const axios = require("axios");

exports.handler = async function (event, context) {
  let response = await axios.post(
    "https://edi-core.stedi.com/2021-06-05/translate",
    {
      input_format: "edi",
      output_format: "jedi@2.0",
      input:
        "ISA*00*          *00*          *ZZ*STEDI          *ZZ*ACME           *210901*1234*U*00801*000000001*0*T*>~\nGS*PO*SENDERGS*007326879*20210901*1234*1*X*008020~\nST*850*000000001~\nBEG*24*SP*PO-00001**20210901~\nN1*2L*STEDI INC.~\nREF*K6*A composable platform for building flexible EDI systems~\nPER*SR**EA*team@stedi.com~\nPO1**1*2P*0.0075*PE*GE*EDI Core~\nPO1**1*C0*0.001*PE*GE*Mappings~\nCTT*2~\nSE*9*000000001~\nGE*1*1~\nIEA*1*000000001~",
    },
    {
      headers: {
        "Authorization": `Key ${event.apiKey}`,
        "Content-Type": "application/json",
      },
    },
  );
  return response.data;
};
```

This code uses the Axios library, so it needs to be included in the package. The EDI Core API needs an API key and this function expects you to [pass it in using the `event` object](#passing-data-into-a-function).

```http
POST https://functions.cloud.us.stedi.com/2021-11-16/functions/example-function/invocations HTTP/1.1

Content-Type: application/json
Authorization: Key your-api-key
Accept: application/octet-stream

{
  "apiKey": "your-api-key"
}
```


Tutorial

> **Version Note:** This page covers the Functions Classic product; for the current generation of Functions please visit the [latest version of the Functions documentation](/docs/functions).

_Functions_ is a compute service that lets you run code without provisioning or managing servers. With Functions, Stedi runs your code on high-availability compute infrastructure that automatically scales up and down according to your usage. You can run code for virtually any type of integration or other standalone backend service – all you need to do is supply your source code.

Stedi runs your function only when needed and scales automatically, from a few requests per day to up to 50 concurrently by default. You pay only for the compute time that you consume — there is no charge to create functions, and there is no charge when your code isn't running.

## How can Functions be used?

You can invoke functions using the Functions Software Developer Kit (SDK). Another way that functions can run is [in response to activity within a Stedi Bucket](/docs/functions-classic/notifications#stedi-buckets). Here are a few ideas about what you could build:

- automatically process EDI files received via [SFTP](/docs/api/sftp) by sending them to the [EDI Translate API](/docs/edi-translate).
- send translated payloads to external API endpoints.
- call the [EDI Translate API](/docs/edi-translate) to translate EDI to JSON, and then transform the output using the [Mappings API](/docs/mappings).
- or do something completely unrelated to your other Stedi workflows!

## Features

Here’s what you can do with Functions.

- Execute code in a hosted environment.
- [Run code in response to supported events from other Stedi products.](/docs/functions-classic/notifications)
- Use third-party libraries.
- Call out to any external web API.

You can create, update, and invoke functions with the [Functions API](/docs/api/functions) or through the [web UI](https://www.stedi.com/app/functions). The API is more flexible and gives you access to create/update functions using a zip archive. You can follow [the deployment tutorial](/docs/functions-classic/tutorial) to learn more about that. The web UI gets you up and running quickly, but it doesn’t support third-party libraries and it makes it hard to keep your code in a version control system. We recommend you use the web UI to experiment with Functions, and the API for production-level usage.

## A real-world example

Let's say that you receive [EDI 850 purchase orders](https://www.stedi.com/edi/x12/transaction-set/850) from your trading partner. The trading partner delivers these files to you via Stedi SFTP and you need to transform it somehow into an XML document for your ERP.

Using Stedi Functions, you can convert the EDI file to JSON. Next, you can transform the JSON into the desired JSON schema and convert the document to XML. Finally, the XML document is posted to an external webhook of the ERP.

You could use variations of this pattern to convert documents between other file formats and extend the function further with additional features.

You can find instructions for how to deploy your first Stedi Function in the [GitHub repo](https://github.com/Stedi-Demos/simple-function). We would also encourage you to take a look at the other [Stedi Demos](https://github.com/Stedi-Demos).

## Supported languages

- JavaScript (or any other language that compiles to JavaScript, like TypeScript).



### Choosing a module system

> **Version Note:** You can only choose a module system for the functions labeled `New (v2)` in the Functions UI.

Functions support both CommonJS (CJS) and ECMAScript (ESM) modules. Stedi infers the module system from the file extension: .js for CJS and .mjs for ESM.

You cannot change the module system if your function package contains multiple files (usually the case if it's been bundled). Changing a function module system impacts how the function behaves, so ensure the function's code is compatible with the selected module system before updating it.

To edit the module system for a function, go to that function in the UI, click **Edit**, and then select a module system from the menu at the top of the editor.

Please [contact us](https://www.stedi.com/contact) to request support for addtional languages.

## Limitations

There are some restrictions you should keep in mind.

- The name of a function can be up to 64 characters long and can only contain characters that are valid in a URL.
- The maximum execution time of a function is 15 minutes. Your function is deployed with a 3-second timeout by default, which you can increase using the API.
- Functions that require packages and other assets can only be deployed as a single zip archive. The overall size of the zip file is limited to 3.25 MB, and zip files can only be uploaded via API. Our web UI only supports self-contained code consisting of a single source code file.
- When a function has not run for a while, or when a large burst of requests arrives, the initial invocation(s) of a function may take a few seconds longer than normal. After such a "cold start" the function will be "warm" and its latency will settle down to just the execution time of your own code.

## API documentation

For detailed descriptions please refer to the [API reference](/docs/api/functions).

Functions Classic


At Stedi, a product is labeled **Legacy** when there is a newer version of the product with significant changes, or an alternative product exists that better addresses the same use cases.

We will continue to support legacy products according to our SLAs. If you are new to Stedi, we strongly recommend using our latest products to build your integration.


Legacy products

Feedback