Creates (or updates) a trading partner from a retailer connector, filling in…

The created partner (key hash redacted)

POST /v1/connectors/{name}/partners/{id}

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.edi.stateset.com/v1/connectors/{name}/partners/{id}' \
  --header "Authorization: Bearer $EDI_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "our_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_qualifier": "string",
  "partner_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_qualifier": "string",
  "usage": "string"
}'

200

{
  "ack_sla_hours": 1,
  "ack_type": "string",
  "api_key_hash": "YOUR_API_KEY",
  "as1": {
    "partner_email": "string"
  },
  "as2": {
    "compress_outbound": true,
    "encrypt_outbound": true,
    "mdn_mode": "none",
    "mic_algorithm": "sha256",
    "our_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_cert_pem": "string",
    "partner_receipt_delivery_url": "string",
    "partner_url": "string",
    "receipt_delivery_url": "string",
    "request_signed_mdn": true,
    "require_encrypted_inbound": true,
    "require_signed_inbound": true,
    "sign_outbound": true
  },
  "auto_ack_855": "off",
  "delimiters": {
    "component": ">",
    "element": "*",
    "repetition": "string",
    "segment": "~"
  },
  "enforce_business_po_identity": true,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": {
    "darkness": 1,
    "height_dots": 1,
    "partner_mark": "string",
    "width_dots": 1
  },
  "name": "Two-Person Tent",
  "our_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_qualifier": "string",
  "outbound_compliance": "off",
  "overlay": {
    "element_overrides": [
      {
        "element": 1,
        "segment": "string",
        "transaction_set": "string",
        "value": "49.00"
      }
    ],
    "extra_segments": [
      {
        "elements": [
          "string"
        ],
        "tag": "priority",
        "transaction_set": "string"
      }
    ]
  },
  "packing_slip": {
    "footer_note": "string",
    "logo_text": "https://cdn.example.com/products/tent-2p.jpg",
    "seller_name": "string",
    "show_sscc": true
  },
  "partner_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_qualifier": "string",
  "require_asn_ack_before_invoice": true,
  "require_retail_v1": true,
  "retail_closure_policy": "standard",
  "retailer_profile": "string",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "usage": "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"
    ]
  },
  "van": {
    "mailbox": "string",
    "provider": "string"
  },
  "version": "2026-08-01"
}

Path parameters

name · string · required

Connector name, e.g. walmart

id · string · required

Internal partner ID to create

Request body

ConnectorPartnerParams

name · string,null

Override the display name.

our_isa_id · string · required

Our ISA interchange ID (our DUNS or the ID the retailer assigned us).

our_isa_qualifier · string · required

Our ISA qualifier for this relationship (often 01 DUNS or ZZ).

partner_isa_id · string · required

The retailer’s ISA interchange ID (their assigned identifier).

partner_isa_qualifier · string,null

Override the connector’s default partner ISA qualifier.

usage · string,null

P production (default) or T test.

Response

TradingPartner

ack_sla_hours · integer,null (int32)

Per-partner acknowledgment SLA in hours. Strict retailers chargeback on late 997s, so this overrides the global EDI_ACK_SLA_HOURS for monitoring and alerting. None falls back to the global SLA. Minimum: 0.

ack_type · string

Which functional acknowledgment this partner receives: 997 (default) or 999 (Implementation Acknowledgment with IK3/IK4 error detail).

api_key_hash · string,null

SHA-256 hex of this partner’s API key, set via POST /v1/partners/:id/api-key. The plaintext key is never stored.

as1 · As1Config,null

Per-partner AS1 settings: the address we email outbound documents to.

Show As1Config

partner_email · string · required

The partner mailbox that receives our EDI attachments.

as2 · As2Config,null

Per-partner AS2 relationship settings. Lives alongside the X12 envelope config on a trading partner; absent for partners that exchange files only.

Show As2Config

compress_outbound · boolean

Compress outbound payloads (CMS CompressedData, RFC 5402). Applied innermost: compress → sign → encrypt.

encrypt_outbound · boolean

Encrypt outbound payloads (S/MIME). Requires a [Security] signer.

mdn_mode · MdnMode

How the partner returns MDN receipts. Allowed values: 'none', 'sync', 'async'.

mic_algorithm · MicAlgorithm

MIC algorithm requested for the MDN and used to verify receipts. Allowed values: 'sha256', 'sha384', 'sha512'.

our_as2_id · string · required

Our AS2 identifier (the value partners address messages to).

partner_as2_id · string · required

The partner’s AS2 identifier.

partner_cert_pem · string,null

The partner’s X.509 certificate (PEM) — used to verify their inbound signatures, authenticate MDNs, and encrypt outbound payloads for them.

partner_receipt_delivery_url · string,null

Trusted partner HTTPS endpoint for receipts of inbound async messages. Must exactly match their Receipt-Delivery-Option. Distinct from our receipt_delivery_url, which receives receipts for outbound messages.

partner_url · string · required

The partner’s AS2 endpoint URL we POST outbound documents to.

receipt_delivery_url · string,null

Public HTTPS callback endpoint for asynchronous receipts. Required when mdn_mode is async; sent as Receipt-Delivery-Option (RFC 4130).

request_signed_mdn · boolean

Request a signed MDN (transport-level non-repudiation of receipt). Requires partner_cert_pem; unsigned or unverifiable receipts fail closed.

require_encrypted_inbound · boolean

Require inbound messages from this partner to be encrypted. When set, a cleartext inbound message is rejected with a failure MDN. Defaults to false.

require_signed_inbound · boolean

Require inbound messages from this partner to be signed. When set, an unsigned inbound message is rejected with a failure MDN instead of processed. Defaults to false (accept unsigned) to preserve existing behavior; enable it — together with partner_cert_pem — to mandate message authentication for a partner. Verification of the signature itself still depends on a configured certificate.

sign_outbound · boolean

Sign outbound payloads (S/MIME). Requires a [Security] signer.

auto_ack_855 · AutoAck855

Automatic 855 acknowledgment of accepted inbound 850s: off (default) or accept_all (855 AC with every line IA, dispatched after the inbound commit; failures never fail the inbound document). Allowed values: 'off', 'accept_all'.

delimiters · Delimiters

The four delimiters that frame an X12 interchange. The element separator and segment terminator are dictated by the ISA segment itself; the component separator is ISA16. The repetition separator (ISA11) only exists in 00501+ interchanges.

Show Delimiters

component · string · required

element · string · required

repetition · string,null

segment · string · required

enforce_business_po_identity · boolean

Reject a second original 850 for the same business PO, even with new control numbers. PostgreSQL retains this identity beyond document expiry.

id · string · required

Stable internal identifier, used in URLs and event payloads.

label · LabelProfile,null

Per-partner label placement profile — the label facet of a partner companion guide. Controls the physical label (print width, length, darkness) and an optional partner-required mark. Defaults to a 4×6’ thermal label at 203 dpi.

Show LabelProfile

darkness · integer,null (int32)

Print darkness (ZPL ^MD, 0–30); None leaves the printer default. Minimum: 0.

height_dots · integer (int32)

Label length in dots (ZPL ^LL). 1218 = 6’ at 203 dpi. Minimum: 0.

partner_mark · string,null

A partner-required mark printed at the label’s top edge (e.g. a routing or department code the retailer mandates).

width_dots · integer (int32)

Print width in dots (ZPL ^PW). 812 = 4’ at 203 dpi. Minimum: 0.

name · string · required

our_gs_id · string,null

our_isa_id · string · required

our_isa_qualifier · string · required

Our ISA qualifier/ID for this relationship.

outbound_compliance · OutboundCompliance

Pre-send compliance gate for outbound 855/856/810 checked against the stored 850 (+860 changes): off, warn (default — send and report the issues), or block (refuse with 422 when any error-level issue exists). Allowed values: 'off', 'warn', 'block'.

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.

Show 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.

Show 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.

Show OverlaySegment

elements · string[]

tag · string · required

transaction_set · string,null

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

packing_slip · PackingSlipProfile,null

Per-partner packing-slip presentation. Defaults are sensible for a generic slip; a partner overlay overrides the fields its companion guide mandates.

Show PackingSlipProfile

footer_note · string,null

Optional footer note (return policy, compliance marks, partner-required statements).

logo_text · string,null

Optional logo / brand line printed above the seller name.

seller_name · string · required

Seller / shipper name printed in the header (the ‘from’ identity).

show_sscc · boolean

When true, render each carton’s SSCC alongside its contents — required by retailers that scan the slip against the carton label.

partner_gs_id · string,null

GS application codes; default to the ISA IDs when omitted.

partner_isa_id · string · required

partner_isa_qualifier · string · required

The partner’s ISA qualifier/ID (they are the receiver on our outbound).

require_asn_ack_before_invoice · boolean

Require accepted functional acknowledgments for every recorded ASN before accepting invoice documents/events. Set from the agreed guide.

require_retail_v1 · boolean

Require explicit retail-v1 source facts for new ERP events. Previously accepted requests still replay their original receipt after enabling it.

retail_closure_policy · RetailClosurePolicy

Opt-in review of fully rejected or cancelled orders with no fulfillment. Does not assert financial settlement or retailer business acceptance. Allowed values: 'standard', 'unfulfilled_terminal_review'.

retailer_profile · string,null

Built-in retailer profile key (e.g. walmart, qvc-rithum) whose outbound rules the pre-send compliance check also enforces.

tenant_id · string

Owning tenant. Every partner belongs to exactly one tenant; an API key issued for the partner therefore implies its tenant. Defaults to default so single-tenant deployments and pre-tenancy records work unchanged.

usage · string

ISA15 usage indicator: P production, T test.

validation · PartnerValidation

Optional inbound validation rules — a subset of a partner’s EDI implementation guide, enforced before translation.

Show 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’.

Show 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.

Show 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.

Show 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.

van · VanConfig,null

Show VanConfig

mailbox · string · required

Mailbox slug under the provider.

provider · string

stateset-network for our native managed network, or an interconnect key such as sps-commerce when a bridge is configured.

version · string

GS08 version, e.g. 004010.

Status codes

Code	Meaning
200	The created partner (key hash redacted)
403	Admin credential required
404	Unknown connector

Using this contract

Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.

cURL

curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.edi.stateset.com/v1/connectors/{name}/partners/{id}' \
  --header "Authorization: Bearer $EDI_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Two-Person Tent",
  "our_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_qualifier": "string",
  "partner_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_qualifier": "string",
  "usage": "string"
}'

200

{
  "ack_sla_hours": 1,
  "ack_type": "string",
  "api_key_hash": "YOUR_API_KEY",
  "as1": {
    "partner_email": "string"
  },
  "as2": {
    "compress_outbound": true,
    "encrypt_outbound": true,
    "mdn_mode": "none",
    "mic_algorithm": "sha256",
    "our_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_as2_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "partner_cert_pem": "string",
    "partner_receipt_delivery_url": "string",
    "partner_url": "string",
    "receipt_delivery_url": "string",
    "request_signed_mdn": true,
    "require_encrypted_inbound": true,
    "require_signed_inbound": true,
    "sign_outbound": true
  },
  "auto_ack_855": "off",
  "delimiters": {
    "component": ">",
    "element": "*",
    "repetition": "string",
    "segment": "~"
  },
  "enforce_business_po_identity": true,
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "label": {
    "darkness": 1,
    "height_dots": 1,
    "partner_mark": "string",
    "width_dots": 1
  },
  "name": "Two-Person Tent",
  "our_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "our_isa_qualifier": "string",
  "outbound_compliance": "off",
  "overlay": {
    "element_overrides": [
      {
        "element": 1,
        "segment": "string",
        "transaction_set": "string",
        "value": "49.00"
      }
    ],
    "extra_segments": [
      {
        "elements": [
          "string"
        ],
        "tag": "priority",
        "transaction_set": "string"
      }
    ]
  },
  "packing_slip": {
    "footer_note": "string",
    "logo_text": "https://cdn.example.com/products/tent-2p.jpg",
    "seller_name": "string",
    "show_sscc": true
  },
  "partner_gs_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partner_isa_qualifier": "string",
  "require_asn_ack_before_invoice": true,
  "require_retail_v1": true,
  "retail_closure_policy": "standard",
  "retailer_profile": "string",
  "tenant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "usage": "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"
    ]
  },
  "van": {
    "mailbox": "string",
    "provider": "string"
  },
  "version": "2026-08-01"
}