> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Publish partner guide

> Guide, immutable snapshot and audit committed together

### Path parameters

**id** `string` *required*

Tenant-owned partner

### Request body

`GuideUpdate`

**expected\_revision** `string` *required*

**note** `string,null`

**overlay** `PartnerOverlay,null` *required*

A per-partner outbound overlay: the configurable slice of a companion guide. Applied to a built X12 transaction set before enveloping, so the same codec serves every partner and their idiosyncrasies live on the partner record.

**PartnerOverlay**

**element\_overrides** `ElementOverride[]`

Force an element's value on the first matching segment of an outbound transaction (optionally scoped to a set) — e.g. a fixed qualifier.

**ElementOverride**

**element** `integer` *required*

1-based element position (element 1 is the first after the segment tag). Minimum: `0`.

**segment** `string` *required*

**transaction\_set** `string,null`

**value** `string` *required*

**extra\_segments** `OverlaySegment[]`

Extra segments appended to outbound transactions (optionally scoped to a transaction set) — e.g. a partner-required `REF`/`N9`/`DTM`.

**OverlaySegment**

**elements** `string[]`

**tag** `string` *required*

**transaction\_set** `string,null`

Restrict to one transaction set (e.g. `856`); `None` applies to all.

**validation** `PartnerValidation` *required*

Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.

**PartnerValidation**

**accepted\_inbound** `string[]`

If non-empty, inbound transaction sets not in this list are rejected (e.g. `['850', '860']` for a partner that only sends orders).

**accepted\_versions** `string[]`

If non-empty, an inbound functional group whose GS08 version is not in this list is rejected (SNIP level 2). Empty accepts any supported version — e.g. `['005010']` pins a partner certified only on 5010.

**conditional\_rules** `ConditionalRule[]`

If-then rules, e.g. 'when BEG02 is SA, a DTM segment is required'.

**ConditionalRule**

**equals** `string[]`

Trigger values. Empty means 'when the element is present (non-empty)'.

**require\_element** `ElementRef,null`

A (segment tag, 1-based element position) pair.

**require\_segment** `string,null`

Then this segment must be present somewhere in the transaction.

**when\_element** `integer` *required*

Minimum: `0`.

**when\_segment** `string` *required*

Trigger: segment tag + 1-based element position.

**count\_checks** `object`

Count-balancing rules per inbound transaction set — `CTT01` must equal the number of `PO1` segments and friends. Checked only when the counter segment is present (pair with `required_segments` to mandate it). Additional keys map to values of type `CountRule[]`.

**element\_constraints** `ElementConstraint[]`

Element-level constraints applied to matching segments anywhere in an inbound document — e.g. pin PO1-03 (unit of measure) to an allowed set.

**ElementConstraint**

**allowed** `string[]`

If non-empty, the element must be one of these values.

**component** `integer,null`

1-based component within an EDIFACT composite element, e.g. `2` for the reference value in `RFF+ON:<value>` (element 1). Unset checks the element itself: an X12 element, or an EDIFACT element's first component. X12 elements have only component 1. Minimum: `0`.

**element** `integer` *required*

1-based element position, e.g. `3` for the PO1 unit of measure. Minimum: `0`.

**format** `ElementFormat,null`

X12 data-type formats an element can be pinned to. Deliberately the high-value subset: numeric identifiers, decimal amounts, and the CCYYMMDD / HHMM(SS) date-time shapes that reject the malformed values retailers charge back over. Anything not listed validates as free text. Allowed values: `'numeric'`, `'decimal'`, `'date'`, `'time'`.

**max\_len** `integer,null`

Maximum length (in characters) when the element is present. Minimum: `0`.

**min\_len** `integer,null`

Minimum length (in characters) when the element is present. Minimum: `0`.

**qualifier\_element** `integer,null`

With `qualifier_value`: apply only to occurrences whose element at this position equals the qualifier (e.g. REF where REF01 = `DP`). Minimum: `0`.

**qualifier\_value** `string,null`

**required** `boolean`

If true, the element must be present (non-empty).

**segment** `string` *required*

Segment tag, e.g. `PO1`.

**sets** `string[]`

Transaction sets the rule applies to (e.g. `['850']`); empty = every set containing the segment. Shared segments (REF, N1, DTM) mean different things in different sets.

**enforce\_x12\_envelope\_identity** `boolean`

Require inbound X12 ISA sender/receiver qualifiers and IDs, plus ISA15, to match this partner even when the caller supplies an explicit partner ID.

**enforce\_x12\_group\_identity** `boolean`

Require every inbound X12 GS02/GS03 to match the configured application sender/receiver IDs (falling back to ISA IDs when GS IDs are unset).

**outbound\_rules** `OutboundRule[]`

Sourced checks for generated 855/856/810 wire, evaluated after overlays. Stored with guide snapshots and included in readiness fingerprints.

**OutboundRule**

**kind** `string` *required*

Allowed values: `'required_segment'`.

**qualifier** `string,null`

**segment** `string` *required*

**set** `string` *required*

The outbound transaction set the rule applies to (`856`, `810`).

**source** `string` *required*

Where the requirement comes from (document + section, or code site).

**required\_qualified** `object`

Qualified-segment requirements per inbound transaction set — the guide staple `required_references` can't reach beyond REF: 'a DTM\*002 (delivery date) must be present', 'an N1 loop with N101=ST'. The `'*'` key applies to every set. Additional keys map to values of type `QualifiedSegmentRule[]`.

**required\_references** `object`

REF qualifiers that must be present per inbound transaction set, e.g. `{'850': ['DP']}` to require a department-number reference on every PO. Additional keys map to values of type `string[]`.

**required\_segments** `object`

Segment tags that must be present per inbound transaction set, e.g. `{'850': ['DTM', 'REF']}` to require a date and reference on every PO. The `'*'` key applies to every inbound set. Additional keys map to values of type `string[]`.

**segment\_cardinality** `object`

Occurrence bounds per inbound transaction set, e.g. `{'850': [{'segment': 'BEG', 'min': 1, 'max': 1}]}` for 'exactly one BEG' or a guide's 'max 200 PO1 lines'. The `'*'` key applies to every set; a set-specific rule for the same segment takes precedence. Additional keys map to values of type `CardinalityRule[]`.

**warning\_codes** `string[]`

Validation issue codes (e.g. `too_long`, `value_not_allowed`) that are advisory for this partner: matching issues are reported on the accepted document and acknowledged `E` (accepted with errors) in the 997/999 instead of rejecting the transaction. For EDIFACT, a parsed, mapped message is accepted with findings in the report and ledger; CONTRL reports acceptance without inventing a syntax-error code. Unlisted guide codes and parser failures still reject.

### Response

`GuideResponse_GuidePublication`

**data** `object` *required*

**data**

**guide** `GuideDraft` *required*

**GuideDraft**

**overlay** `PartnerOverlay,null`

A per-partner outbound overlay: the configurable slice of a companion guide. Applied to a built X12 transaction set before enveloping, so the same codec serves every partner and their idiosyncrasies live on the partner record.

**publishing\_available** `boolean` *required*

Atomic guide publication is available on PostgreSQL deployments.

**revision** `string` *required*

Opaque revision of the partner settings, including its environment.

**validation** `PartnerValidation` *required*

Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.

**snapshot** `GuideSnapshot` *required*

An immutable snapshot of a partner's guide at a point in time.

**GuideSnapshot**

**author** `string` *required*

Who captured it (`admin`, `partner:{id}`).

**created\_at** `string (date-time)` *required*

**note** `string,null`

**overlay** `PartnerOverlay,null`

A per-partner outbound overlay: the configurable slice of a companion guide. Applied to a built X12 transaction set before enveloping, so the same codec serves every partner and their idiosyncrasies live on the partner record.

**partner\_id** `string` *required*

**tenant\_id** `string` *required*

**validation** `PartnerValidation` *required*

Per-partner inbound validation. Empty rules accept everything (the default), so existing partners are unaffected.

**version** `integer (int32)` *required*

Monotonic version, starting at 1. Minimum: `0`.

**warnings** `GuideIssue[]` *required*

**GuideIssue**

**field** `string` *required*

**message** `string` *required*

**severity** `string` *required*

`error` blocks publish; `warning` is advisory.

**success** `boolean` *required*

### Status codes

| Code | Meaning |
| - | - |
| `200` | Guide, immutable snapshot and audit committed together |
| `404` | Unknown partner |
| `409` | Guide or partner settings changed; reload before publishing |
| `422` | Invalid guide or durable guide publishing unavailable |

### Using this contract

Read the [source OpenAPI document](/spec/edi.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request PUT \
  --url 'https://api.edi.stateset.com/v1/partners/{id}/guide' \
  --header "Authorization: Bearer $EDI_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "expected_revision": "string",
  "note": "Two-person tent, green — replacement for damaged pole set.",
  "overlay": {
    "element_overrides": [
      {
        "element": 1,
        "segment": "string",
        "transaction_set": "string",
        "value": "49.00"
      }
    ],
    "extra_segments": [
      {
        "elements": [
          "string"
        ],
        "tag": "priority",
        "transaction_set": "string"
      }
    ]
  },
  "validation": {
    "accepted_inbound": [
      "string"
    ],
    "accepted_versions": [
      "string"
    ],
    "conditional_rules": [
      {
        "equals": [
          "string"
        ],
        "require_element": {
          "element": 1,
          "segment": "string"
        },
        "require_segment": "string",
        "when_element": 1,
        "when_segment": "string"
      }
    ],
    "count_checks": {},
    "element_constraints": [
      {
        "allowed": [
          "string"
        ],
        "component": 1,
        "element": 1,
        "format": "numeric",
        "max_len": 1,
        "min_len": 1,
        "qualifier_element": 1,
        "qualifier_value": "49.00",
        "required": true,
        "segment": "string",
        "sets": [
          "string"
        ]
      }
    ],
    "enforce_x12_envelope_identity": true,
    "enforce_x12_group_identity": true,
    "outbound_rules": [
      {
        "kind": "required_segment",
        "qualifier": "string",
        "segment": "string",
        "set": "string",
        "source": "string"
      }
    ],
    "required_qualified": {},
    "required_references": {},
    "required_segments": {},
    "segment_cardinality": {},
    "warning_codes": [
      "string"
    ]
  }
}'
```

```json 200 theme={null}
{
  "data": {
    "guide": {
      "overlay": {
        "element_overrides": [
          {
            "element": 1,
            "segment": "string",
            "transaction_set": "string",
            "value": "49.00"
          }
        ],
        "extra_segments": [
          {
            "elements": [],
            "tag": "priority",
            "transaction_set": "string"
          }
        ]
      },
      "publishing_available": true,
      "revision": "string",
      "validation": {
        "accepted_inbound": [
          "string"
        ],
        "accepted_versions": [
          "string"
        ],
        "conditional_rules": [
          {
            "equals": [],
            "require_element": {
              "element": null,
              "segment": null
            },
            "require_segment": "string",
            "when_element": 1,
            "when_segment": "string"
          }
        ],
        "count_checks": {},
        "element_constraints": [
          {
            "allowed": [],
            "component": 1,
            "element": 1,
            "format": "numeric",
            "max_len": 1,
            "min_len": 1,
            "qualifier_element": 1,
            "qualifier_value": "49.00",
            "required": true,
            "segment": "string",
            "sets": []
          }
        ],
        "enforce_x12_envelope_identity": true,
        "enforce_x12_group_identity": true,
        "outbound_rules": [
          {
            "kind": "required_segment",
            "qualifier": "string",
            "segment": "string",
            "set": "string",
            "source": "string"
          }
        ],
        "required_qualified": {},
        "required_references": {},
        "required_segments": {},
        "segment_cardinality": {},
        "warning_codes": [
          "string"
        ]
      }
    },
    "snapshot": {
      "author": "string",
      "created_at": "2026-08-31T14:22:05Z",
      "note": "Two-person tent, green — replacement for damaged pole set.",
      "overlay": {
        "element_overrides": [
          {
            "element": 1,
            "segment": "string",
            "transaction_set": "string",
            "value": "49.00"
          }
        ],
        "extra_segments": [
          {
            "elements": [],
            "tag": "priority",
            "transaction_set": "string"
          }
        ]
      },
      "partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "validation": {
        "accepted_inbound": [
          "string"
        ],
        "accepted_versions": [
          "string"
        ],
        "conditional_rules": [
          {
            "equals": [],
            "require_element": {
              "element": null,
              "segment": null
            },
            "require_segment": "string",
            "when_element": 1,
            "when_segment": "string"
          }
        ],
        "count_checks": {},
        "element_constraints": [
          {
            "allowed": [],
            "component": 1,
            "element": 1,
            "format": "numeric",
            "max_len": 1,
            "min_len": 1,
            "qualifier_element": 1,
            "qualifier_value": "49.00",
            "required": true,
            "segment": "string",
            "sets": []
          }
        ],
        "enforce_x12_envelope_identity": true,
        "enforce_x12_group_identity": true,
        "outbound_rules": [
          {
            "kind": "required_segment",
            "qualifier": "string",
            "segment": "string",
            "set": "string",
            "source": "string"
          }
        ],
        "required_qualified": {},
        "required_references": {},
        "required_segments": {},
        "segment_cardinality": {},
        "warning_codes": [
          "string"
        ]
      },
      "version": 1
    },
    "warnings": [
      {
        "field": "string",
        "message": "Two-person tent, green — replacement for damaged pole set.",
        "severity": "string"
      }
    ]
  },
  "success": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.