Transaction API

Disclaimer: This is unofficial, community-created documentation for Epicor Prophet 21 APIs. It is not affiliated with, endorsed by, or supported by Epicor Software Corporation. All product names, trademarks, and registered trademarks are property of their respective owners. Use at your own risk.

Original source: a large share of what this document verifies — upsert semantics and the Keys rules, IgnoreDisabled, report-service discovery, the Item window's nested location edits, the buy-side build → receive → vouch cycle — originates in Alex Westemeier's process work, re-verified here before publication. Section-level credits appear throughout.

Overview

The Transaction API is a stateless RESTful web service for bulk data manipulation in P21. It allows creating and updating records across any P21 window without maintaining session state.

Key Characteristics

• Stateless - No session management required
• Bulk operations - Process multiple records in single request
• Service-based - Each P21 window maps to a service
• JSON or XML - Supports both formats
• Async support - Long operations can run asynchronously

When to Use

• Creating multiple records (orders, invoices, etc.)
• Bulk updates
• Automated data import
• Integration with external systems

Endpoints

All Transaction API endpoints use the UI Server URL. First, obtain the UI Server URL:

GET https://{hostname}/api/ui/router/v1/?urlType=external

Note that the no-trailing-slash form can return a 307 redirect and the response may be XML on some middleware — use the trailing-slash form (/api/ui/router/v1/) and follow redirects; see 00-Authentication § UI Server URL.

Then use the returned URL as base:

The three discovery endpoints, and which one answers your question. definition, defaults and basics take the same {service_name} path segment and are the routine way to learn a window's shape without opening P21. Between them: definition returns the full schema — every DataElement, field, DataType, KeyFields, and the accepted values for dropdown/code fields, which is where valid values for site-specific fields such as carrier_id come from (see Get Service Definition); defaults returns the service's default values and a payload template you can fill in and post back; basics returns the same element list carrying only each element's headline fields, already shaped as a Status: "New" TransactionSet with Keys prefilled from the element's KeyFields and IgnoreIfEmpty: true on every edit — fill in the values and POST it. The abbreviation is severe and that is the point: on Order all three return the same 102 elements, but basics carries 103 fields against definition/defaults' 1,266.

The community session's warning about basics holds in both directions, so treat it as a starting point rather than a contract — verified on 26.1 with Order:

• It omits fields you need. Its header element lists order_no, sales_loc_id, contact_id, po_no, order_date, company_id, taker, requested_date — but a create also needs customer_id, source_loc_id and ship_to_id, none of which appear. Omitting ship_to_id fails the save with the unattributed message This column is required. (no column named).

• It includes fields you cannot write. company_id is in that same list and is refused on save with Column is disabled: company_id.

basics also answers for report services (m_*) — and there it shines: a report window carries only a handful of criteria fields, so basics returns a ready-to-fill criteria skeleton in a few hundred bytes (m_picktickets: 601 bytes against definition's 15.8 KB), the API-side equivalent of reading the criteria names out of SQL Help (see PDF Report Generation). An unknown service name returns an empty HTTP 500, the same shape definition and defaults give. (Endpoint and behavior verified against a 26.1 tenant, August 2026; originally surfaced in a community session, Felipe Maurer, 2026.)

basics is computed, not curated — and that explains both of its flaws. For every element it returns exactly the element's KeyFields ∪ the fields the definition marks Required: true. Verified across 220 elements in four services (Order, Item, JobContractPricing, PurchaseOrder) with zero mismatches.

So basics inherits the Required flag's unreliability wholesale (see What Required actually means): it lists company_id on Order because the definition marks it required — and company_id is a disabled column that fails the save. It omits customer_id, source_loc_id and ship_to_id because the definition doesn't mark them required, even though a create needs all three. The endpoint isn't wrong; it is faithfully reflecting metadata that is.

Practical consequence: basics tells you nothing the definition doesn't — you can generate it offline from definitions/*.json and save the round-trip. Its value is the shape (a ready-to-fill skeleton with Keys prefilled), not the field selection.

Service Explorer: The P21 middleware includes a web-based Transaction API Service Explorer tool for browsing available services and their definitions interactively. Access it from the SOA Middleware admin pages.

Definition endpoint 500s for unavailable windows: GET /api/v2/definition/{name} can return HTTP 500 with "Window <<X>> is not available or user does not have permission to open it" for a service that /api/v2/services lists. Despite the wording, this is usually not a grantable permission problem — the same window fails for fully-privileged users in the Service Explorer. It means the window isn't available in that environment (unlicensed or undeployed module), and which services fail differs per environment. On one 25.2 test system, 238 of the 299 listed services had fetchable definitions. (Credit: Alex Westemeier)

Read-after-write verification: POST /api/v2/transaction/get is also the recommended way to verify that an Interactive API write actually persisted — a save can report success without persisting a sub-record, and the read-back is the only way to recover a server-generated key. See Verifying Writes in the Interactive API guide.

Authentication

Include the Bearer token in the Authorization header:

POST /api/v2/transaction HTTP/1.1
Host: {ui-server-host}
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json
Accept: application/json

See Authentication for token generation.

Request Structure

TransactionSet

The main request body for create/update operations:

Payload shape only. Full runnable version: Create Order.

{
    "Name": "ServiceName",
    "UseCodeValues": false,
    "Transactions": [
        {
            "Status": "New",
            "DataElements": [
                {
                    "Name": "TABPAGE_1.table_name",
                    "Type": "Form",
                    "Keys": [],
                    "Rows": [
                        {
                            "Edits": [
                                {"Name": "field_name", "Value": "field_value"}
                            ],
                            "RelativeDateEdits": []
                        }
                    ]
                }
            ]
        }
    ]
}

TransactionSet Fields

Transaction Fields

Status: "New" is the only value the enum accepts

Status looks like it should have a create/update/delete vocabulary. It does not. P21.Transactions.Model.V2.TransactionStatus has exactly one string member — New — and the API's create/update distinction is carried by the keys, not by this field (see Upsert Semantics).

Enumerated on 26.1.5940.0 by posting each candidate with an empty DataElements list, so the probe measures only whether the model binder accepts the value and nothing can be written, and re-run unchanged on 26.1.5950.0:

The rejection is a clean model-binding failure that names the type, which is worth recognising on sight:

// POST /api/v2/transaction  with  "Status": "Existing"
HTTP 400
{"errors": {
   "Transactions[0].Status": [
     "Error converting value \"Existing\" to type 'P21.Transactions.Model.V2.TransactionStatus'. ..."]},
 "title": "One or more validation errors occurred.", "status": 400}

This used to be an HTTP 500. On builds before 26.1.5940.0 the same payload produced a NullReferenceException at ToInternalBeSpecification with no indication of the cause — a 500 that looked like a server fault rather than a bad request, and sent more than one integration hunting for a middleware bug. If you are on an older build you will still see the 500; the fix is the same either way. The 400 shape is unchanged on 26.1.5950.0.

The 400 body carries two errors, and the useful one is second. Alongside Transactions[0].Status the response also lists content: ["The content field is required."] — an artifact of the body failing to bind as a whole, not a separate problem with your payload. A client that logs only the first errors entry will report a missing body for what is actually a bad enum value.

Do not send Status as an integer. The binder accepts any integer because that is how .NET binds enums — it does not range-check, so out-of-range values bind silently to an undefined member rather than erroring. Every integer we probed returned HTTP 200. Send the string "New", which is the only value with defined behavior, and let a wrong value fail loudly at the binder instead of undefined-behaving inside the transaction.

The rule holds on /api/v2/process/pdfreport too. Report payloads bind to the same TransactionStatus enum, and the report services' own definition templates carry "Status": "New" and "Type": "Form". Verified on play 26.1.5950.0, 2026-10-10, with m_reprintpurchaseorders: "New", "new", 0, 1 and an omitted Status all returned the same PDF, "Type": "Form" and "Type": 0 returned byte-identical documents, and "Existing" returned the same HTTP 400 shown above. Earlier versions of this repo sent integer 0 on report payloads; it worked because 0 binds to New, but it is the unchecked integer path. Every report payload here now sends "New"; the Python and C# PO reprint examples (reprint_purchase_order.py, ReprintPurchaseOrder.cs) were re-run with it on the same build and date.

DataElement Fields

Row / Edit Fields

Each Edit object supports:

What a blank stores depends on the field. A Value of null, "" or a single space returned Succeeded: 1 on all three fields tested, with or without IgnoreIfEmpty: false, but each field stored something different:

Field (service)	null, "" or " " stores
inv_mast.extended_desc (Item)	SQL NULL: OData eq null finds the row and eq '' does not
oe_hdr.delivery_instructions (Order)	an empty string: eq '' finds the row and eq null does not
oe_hdr.po_no (Order)	nothing: the old value stays

A blank is not a reliable way to clear a field, and you can't predict the result from the request. Read the field back, and filter with both eq '' and eq null when you look for empty values. (Verified on play 26.1.5950.0, 2026-10-29, on a test item and a test order, each restored afterward; other fields not checked.)

Payload Anatomy -- Types, Nesting, and Common Mistakes

Most first-integration failures are payload shape mistakes, not wrong endpoints: a string where an array is expected, a field at the wrong nesting level, or a boolean in quotes. JSON indentation is cosmetic -- what matters is the nesting and the type at every level. This skeleton annotates both:

{                                       // ROOT: object
  "Name": "JobContractPricing",         // string  — the service name
  "UseCodeValues": false,               // boolean — NOT the string "false"
  "IgnoreDisabled": true,               // boolean — ONLY valid at THIS level
  "Transactions": [                     // ARRAY of Transaction objects
    {
      "Status": "New",                  // string — "New" for create AND update
      "DataElements": [                 // ARRAY of DataElement objects
        {
          "Name": "FORM.d_dw_job_price_hdr",  // string — "ELEMENT.datawindow"
          "Type": "Form",               // string — "Form" or "List"
          "Keys": ["item_id"],          // ARRAY of strings — even for ONE key
          "Rows": [                     // ARRAY of Row objects — even for ONE row
            {
              "Edits": [                // ARRAY of Edit objects
                { "Name": "item_id", "Value": "WIDGET-001" }   // Value: STRING
              ],
              "RelativeDateEdits": []   // array (may be empty)
            }
          ]
        }
      ]
    }
  ]
}

Common mistakes and their symptoms

Two tools take the guesswork out:

• Start from the service's Template — GET /api/v2/definition/{Service} (or the committed definitions/{Service}.json) contains a Template.TransactionSet skeleton with every element and field already correctly shaped. Copy the object inside TransactionSet, not the key itself: a body that still starts with "TransactionSet": is accepted and does nothing (see the table above). Fill the Edits you need, delete the rest.
• Validate before you POST — scripts/validate_payload.py checks a payload file (JSON or XML) offline against these rules and the definitions/ schema, with exact paths to each problem:

bash python scripts/validate_payload.py my_payload.json python scripts/validate_payload.py my_payload.xml

Keys -- Row Identity and the Collapse Trap

The Keys array on a DataElement is not an authentication key, a consumer key, or a database primary key. It is how the Transaction API decides which rows in a List element are the same row. Most payloads never need it, which is why it goes unnoticed — but when it matters, the failure is silent: the API returns Succeeded, and the record is simply not what you sent.

Provenance: first described in a community conference session on the P21 APIs (Felipe Maurer, 2026), then verified end-to-end against a 26.1 tenant (August 2026) — the collapse, the Keys fix, the over-keying failure and the stable-key update below are each a live Order create or update with a /transaction/get read-back. It is the same rule as the independently verified Upsert Semantics and contract bin behavior, seen from the row-identity side.

The collapse: two rows in, one row out

Send an order with the same item twice at different quantities and no Keys:

{
    "Name": "TP_ITEMS.items",
    "Type": "List",
    "Keys": [],
    "Rows": [
        {"Edits": [{"Name": "oe_order_item_id", "Value": "WIDGET-001"},
                   {"Name": "unit_quantity",    "Value": "5"}]},
        {"Edits": [{"Name": "oe_order_item_id", "Value": "WIDGET-001"},
                   {"Name": "unit_quantity",    "Value": "10"}]}
    ]
}

You do not get two lines of WIDGET-001. You get one line, quantity 10 — the two rows were treated as one row and the last value written for each field won. No error, no warning, Succeeded: 1.

Two different item IDs in the same payload behave exactly as you expect, which is why this trap stays hidden until the day a real order legitimately carries the same item on more than one line (different lengths cut from one stock item, separate scheduled releases, split shipping dates).

Keys are a GROUP BY

If you know SQL, the model is straightforward: the API is grouping the rows you send, and Keys is the GROUP BY list. Rows that agree on every key field are one row; name a field whose value differs between the rows and they split apart.

For the payload above, the field that actually differs is the quantity:

    "Keys": ["unit_quantity"],

Now the same two rows produce two lines — quantity 5 as user_line_no 001 and quantity 10 as 002. Two different item IDs need no Keys at all: with Keys: [] they already come back as two lines.

Choosing a key

• You cannot invent one, and you must send it. A key must be a real column on that element and appear in every row's Edits — there is no synthetic row-id or ascending-integer you can supply. Both failures are hard, not silent, and their messages are worth recognizing: naming a column you did not put in Edits fails the transaction with the opaque General Exception: Sequence contains no matching element; naming something that is not a column at all fails with the clearer Invalid column name: {name}. Either way Failed: 1, nothing is written.
• Pick the column that differs. On an order line, oe_order_item_id is a bad key for this problem precisely because it is the value that is the same. Fields that commonly work: quantity, a customer/user line number (user_line_no on TP_ITEMS.items), or a date field where the rows genuinely differ.
• Timestamp columns are a last resort. Some elements have no natural discriminator, leaving date_created-style columns as the only option. They usually differ, but rows written in the same operation — or loaded by an import — can share a timestamp, and then the collapse comes back.
• Compound keys are allowed — as many columns as it takes to make the rows unique.
• Surplus keys are accepted silently. A key that is real and sent but doesn't discriminate is not an error — Keys: ["unit_quantity", "oe_order_item_id"] splits the two rows above exactly as ["unit_quantity"] alone does, with no warning that the second key separated nothing. Adding keys until the behavior changes is a legitimate debugging tactic, but it means a wrong key set looks exactly like a right one.
• Deleted rows are still rows. Keying on a positional or UID-style line identifier read from the UI can miss soft-deleted lines that the window doesn't show, so the key you send points at a different row than the one you counted.

Over-keying breaks updates

Keys make rows unique in both directions. Because a keyed Status: "New" row is an upsert — update when the key matches, insert when it doesn't — a key set that is too specific stops matching the row you meant to change, and the "update" silently becomes a new line.

The classic case: keying on the quantity (the fix above) and then trying to change that quantity from 10 to 20. The new value doesn't match the existing row's key, so P21 appends a line instead of editing one. Verified against the two-line order created above:

{"Name": "TP_ITEMS.items", "Type": "List",
 "Keys": ["unit_quantity"],
 "Rows": [{"Edits": [{"Name": "oe_order_item_id", "Value": "WIDGET-001"},
                     {"Name": "unit_quantity",    "Value": "20"}]}]}

Succeeded: 1, no messages — and the order now has three lines (5, 10, 20) instead of two. Key on something stable when updating: the same edit keyed on user_line_no, with user_line_no sent in Edits, changes that line in place and leaves the line count alone.

{"Name": "TP_ITEMS.items", "Type": "List",
 "Keys": ["user_line_no"],
 "Rows": [{"Edits": [{"Name": "user_line_no",     "Value": "003"},
                     {"Name": "oe_order_item_id", "Value": "WIDGET-001"},
                     {"Name": "unit_quantity",    "Value": "33"}]}]}

Key on the discriminator when creating; key on something stable when updating.

Design for updates: assign your own line handles

user_line_no is caller-assignable at create time, which turns the stable-key advice from a debugging move into a design: give every line a handle you chose, and every later update is deterministic. Verified on 26.1 — an order created with the same item on handles 010 and 020 (Keys: ["user_line_no"], so it also solves the collapse), then updated by handle:

{"Name": "TP_ITEMS.items", "Type": "List",
 "Keys": ["user_line_no"],
 "Rows": [{"Edits": [{"Name": "user_line_no",     "Value": "020"},
                     {"Name": "oe_order_item_id", "Value": "WIDGET-001"},
                     {"Name": "unit_quantity",    "Value": "9"}]}]}

changes exactly that line in place — no phantom inserts, no dependence on P21's own numbering. Integrations that create-then-maintain order lines should assign handles on day one (gapped values like 010/020 leave room to insert between).

What the definition already tells you

Every element in definitions/{Service}.json carries a KeyFields array — the key fields P21 declares for that element. Read it before sending repeated rows: in the cases below the declared fields line up exactly with the behavior described above, which makes KeyFields the best available predictor of what your rows will be folded on. (Confirm with a read-back on a service you haven't tried — the correspondence is consistent across the services documented here, but the collapse itself was exercised live only on Order.) Across the committed definitions, 214 of 335 List elements declare key fields; the remaining third declare none.

Order's item grid declaring oe_order_item_id is exactly why the collapse above happens on the item ID. And JOBPRICELINE declaring ["item_id", "line_no"] is the same rule from the other side — which is why the verified contract-line guidance says to select by item_id and to add line_no as a second key when the same item appears on multiple lines (see Editing Bin Quantities).

Read them straight out of the JSON:

python -c "import json;d=json.load(open('definitions/Order.json'));[print(e['Name'],e.get('KeyFields')) for e in d['TransactionDefinition']['DataElementDefinitions'] if e['Type']=='List']"

The live endpoint carries the same field — see Get Service Definition, which prints KeyFields per element.

Elements that declare no KeyFields never fold. The collapse runs on the element's declared key fields, so on the ~third of List elements that declare none, repeated rows simply append in order. Verified on Order → TABPAGE_RELEASE.tabpage_release (scheduled releases — declared keys: none): two release rows with Keys: [] landed as two rows, and re-sending the same row twice was treated as a second new row — it failed business validation (The release date must be after the previous release date) rather than folding into the first. So the collapse trap lives only on keyed elements; on keyless ones the trap inverts — nothing deduplicates for you, and a retried payload appends duplicates instead of matching existing rows.

Debugging a key problem

The symptom is always the same shape: the write succeeded and the data is wrong — a line missing, a quantity belonging to a different line, or an update that appeared as a new row. When that happens:

1. Read the record back with POST /api/v2/transaction/get and compare it to what you sent, row for row.
2. Look up the element's KeyFields in its definition — that is what your rows were folded on.
3. Add the column that genuinely differs between your rows to Keys, resend, read back again.

Do this deliberately on a test system before you need it: send ten rows of the same item at ten quantities, predict the result, then compare. It is a fast way to build the instinct, and it is the one Transaction-API behavior that reads as the API being broken when it is doing exactly what it was told.

XML Payloads (Content Negotiation)

The Transaction API endpoints speak XML as well as JSON, in both directions, negotiated per-request with standard headers (verified live on 25.2, July 2026):

All four combinations are verified working on GET /definition, GET /services, POST /transaction, and POST /transaction/get. Error responses follow the Accept header too (RFC-7807 application/problem+xml / +json).

The XML request shape (DataContract)

The same TransactionSet as above, as a working XML body:

<?xml version="1.0" encoding="utf-8"?>
<TransactionSet xmlns="http://schemas.datacontract.org/2004/07/P21.Transactions.Model.V2">
  <IgnoreDisabled>false</IgnoreDisabled>
  <Name>JobContractPricing</Name>
  <Transactions>
    <Transaction>
      <DataElements>
        <DataElement>
          <Keys xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <a:string>item_id</a:string>
          </Keys>
          <Name>JOBPRICELINE.jobpriceline</Name>
          <Rows>
            <Row>
              <Edits>
                <Edit><Name>item_id</Name><Value>WIDGET-001</Value></Edit>
                <Edit><Name>pricing_method</Name><Value>Price</Value></Edit>
                <Edit><Name>price</Name><Value>36.58</Value></Edit>
              </Edits>
              <RelativeDateEdits />
            </Row>
          </Rows>
          <Type>List</Type>
        </DataElement>
      </DataElements>
      <Status>New</Status>
    </Transaction>
  </Transactions>
  <UseCodeValues>false</UseCodeValues>
</TransactionSet>

Three rules make or break XML bodies — all verified live:

1. The root namespace is mandatory. Without xmlns="http://schemas.datacontract.org/2004/07/P21.Transactions.Model.V2" the body deserializes to null and the server returns 400 "The content field is required."
2. Element order is ALPHABETICAL within each parent (WCF DataContract ordering) — note <Name> before <Transactions> before <UseCodeValues>, <Keys> before <Name> inside a DataElement, <Name> before <Value> inside an Edit. Violations are not politely rejected: a misordered top-level element returns HTTP 500, and a misordered element deeper down is silently dropped — the transaction then fails with "Object reference not set to an instance of an object."
3. Keys items use the arrays namespace: <a:string> with xmlns:a="http://schemas.microsoft.com/2003/10/Serialization/Arrays".

Don't hand-build the shape — ask the server for it. GET /api/v2/definition/{Service} with Accept: application/xml returns the service's Template as XML in exactly the required element order. Fill in the <Value>s and post it back.

Other verified XML specifics:

• POST /api/v2/transaction/get XML bodies use the root <TransactionStateRequest> (same namespace).
• Response roots: <TransactionSetResult> from /transaction, <ServiceDefinition> from /definition, <ArrayOfServiceInfo> from /services.
• scripts/validate_payload.py checks XML payloads offline — namespace, element order, Keys item namespace, and all the JSON-level semantic rules.

Common Services

Report Services

Production, Assembly & Labor Services

See Production & Labor API for detailed field definitions and examples.

Purchase Order Types and the disabled po_hdr_po_type column

You cannot choose a PO type by setting po_hdr_po_type on the PurchaseOrder service — it is a disabled column and sending it fails with Column is disabled: po_hdr_po_type. The PO type is selected by choosing the type-specific service instead (each maps to the same PO Entry window, w_purchase_order_entry_sheet, with the type preset). RequisitionPurchaseOrder is the verified example; see create-requisition-po.

The po_hdr_po_type ValidValues in the definition carry display names only, no code list — the stored po_hdr.po_type letters are not in the definition. The mapping below comes from P21's own report views (which label each letter) and po_hdr.source_type, which records the program that created the PO:

source_type stores a code_p21 number: 948 PO Entry, 949 PO Generation, 950 Process Transactions, 951 Order Entry. Don't confuse po_type with oe_line.disposition, the sales-line field where B really is Backorder and S is Special Order.

A deleted PO stays in the table. Deleting a PO sets po_hdr.delete_flag = 'Y' and po_hdr.complete = 'Y', and sets cancel_flag = 'Y' and complete = 'Y' on each of its po_line rows. Filter on delete_flag when you count open or historical POs. The PO's links to sales-order lines are soft-deleted too — see 02 § oe_line_po.

Credit: @mrwuss — R verified end to end on play 26.1.5894.1, July 2026. The other letters, source_type codes and the deleted-PO flags verified against production data 26.1, September 2026 (#178).

Response Format

Success Response

{
    "Messages": ["Transaction 1:: "],
    "Results": {
        "Name": "Order",
        "Transactions": [
            {
                "DataElements": [
                    {
                        "Name": "TABPAGE_1.order",
                        "Rows": [{
                            "Edits": [
                                {"Name": "order_no", "Value": "1001234"}
                            ]
                        }]
                    }
                ],
                "Status": "Passed"
            }
        ]
    },
    "Summary": {
        "Succeeded": 1,
        "Failed": 0,
        "Other": 0
    }
}

Error Response

{
    "Messages": [
        "Transaction 1:: Customer ID is required"
    ],
    "Results": null,
    "Summary": {
        "Succeeded": 0,
        "Failed": 1,
        "Other": 0
    }
}

Transactions pass/fail independently. In a bulk POST, each Transaction in the array is processed on its own: one failing does not roll back the others (no cascade), and Summary tallies the outcomes (Succeeded/Failed/Other). Check Results.Transactions[].Status ("Passed"/"Failed") to see which specific transactions landed — never the HTTP status, which is 200 either way. (Exception: transactions that each re-save the same shared header record can collide — see Upsert Semantics.)

What Failed actually guarantees

"Check Summary" is the rule this documentation repeats everywhere, and it is right — but it is worth being exact about what a failure count does and does not promise, because two different things get conflated. Verified on a 26.1 tenant (August 2026), each with a /transaction/get read-back:

The practical trap is the second row. A Summary with Failed ≥ 1 does not mean "nothing happened" — if Succeeded is also non-zero, part of your batch is live. A client that reads only Failed and retries the whole POST will re-apply everything that already worked. Branch on Results.Transactions[].Status per transaction, not on the tally.

⚠️ Atomicity covers the record, not the consequences. Some services do substantial downstream work on save — writing related records, completing linked documents, generating invoices. Those side effects are not rolled back by a later validation failure in the same Transaction.

The reported case is DirectShipConfirmation, which returned Summary: {"Failed": 1} — tripped by a disabled c_email_invoice column — after it had already written the inventory receipt, completed the purchase-order line, invoiced the sales-order line, and created the customer AR invoice. The failure was real; so was everything it had done first. (Reported by Alex Westemeier; not reproduced here — ordinary Order edits are atomic as the table above shows, so this is specific to services that cascade; failed Order creates are a separate case, below.)

The same shape appears in the Interactive API, where an in-window wizard can commit at an intermediate step: the PO/RFQ generation wizard creates and links the PO at cb_next, before cb_finish, so an abandoned wizard is not a no-op.

On any write that triggers downstream documents, read the record back — Failed is a reason to go and look, not proof that nothing landed.

A failed create leaves rows behind

The atomicity row above holds for edits to existing records. A Transaction that creates a document and then fails does not vanish: rows it already wrote stay in the table, flagged deleted, and the document number it drew is used up. Verified on the Order service on 26.1.5950.0:

The Interactive API behaves the same way once rows are committed mid-session:

• A never-saved session with one line leaves nothing.
• add_row commits the header and line 1 mid-session (delete_flag = 'N', completed = 'T' — the in-edit state that blocks other writes). Ending the session without saving then flips them to delete_flag = 'Y'. An unsaved multi-line session is not a dry run.

What to do about it:

• Filter every read-back on delete_flag = 'N' (and cancel_flag = 'N' where the table has one). Unfiltered, the leftovers count as real lines.
• Before retrying a failed create, look for the stray document — it already has a number, and a blind retry creates a second one. Expect gaps in the order-number sequence.
• A failed multi-row append to a saved order leaves its rows soft-deleted the same way.

Credit: verified here by the maintainer on 26.1.5950.0 (October 2026), originally reported by Alex Westemeier (soft-deleted residue from failed appends and unsaved sessions) and in #169 (a stray header after a failed create).

Field Order Matters

For some services, the order of fields in the request is significant. The API processes fields sequentially and mirrors the window's UI cascades — some fields trigger validation, auto-population, or clearing of other fields, exactly as they would when typed into the window in that order.

Example: SalesPricePage

Fields must be set in this order: 1. price_page_type_cd - Triggers type-specific validation 2. company_id - Required before product group 3. product_group_id or discount_group_id 4. supplier_id 5. Other fields...

Example: JobContractPricing — pricing_method before price

Changing pricing_method clears the typed price, just like in the UI. If a line row's Edits send price before pricing_method, the line is created/updated with price = $0 — and the transaction still reports Succeeded. Order the Edits item_id, pricing_method, price. Verified live: reversing the order silently zeroes the price.

Rule of thumb: when a write "succeeds" but a value doesn't stick, suspect a field-order cascade. Order Edits the way a user would fill in the window, and verify written values with OData or POST /api/v2/transaction/get after the first run.

Credit: Alex Westemeier for the JobContractPricing ordering discovery.

Column is disabled Can Mean "Disabled For You"

This is the most-seen error in the whole API surface, and its wording invites the wrong conclusion. Column is disabled: <column> is not always a property of the field. The same payload, against the same tenant, at the same moment, can be accepted for one user and refused for another.

Verified on 26.1 (August 2026) with a controlled A/B — identical request sequence, identical field order, two consumer-key tokens differing only in the username they carried:

Both users could open the window, load the order, and set every other field on the line. Only this column differed, and nothing in the response says why.

Check allocation first. A re-test on play 26.1.5950.0 (2026-10-17) found a stronger cause for this particular refusal: disposition is disabled on any line that holds allocated stock, for every user. The same service account set D on unallocated lines, and on allocated lines after TP_EXTDINFO.extd_info.allocated_qty = 0. The general rule in this section still stands: Column is disabled can come from roles and DynaChange rules. Rule out the record's own state before you change a role. See Changing a saved line to direct ship.

What makes a column disabled for a user: DynaChange data-change rules scoped to a role, Application Security settings, window-level permissions, and screen versions, including the web client's Version Manager versions, which are stored apart from the classic ones (see 04 § The locked Units of Measure grid for where they live and a query that finds them) — the same machinery documented under DynaChange and Popup Handling and Application Security settings. The API surfaces all of it as one undifferentiated message.

Check the record's other flags. Another field on the same record can disable a column for every user. customer.job_pricing is disabled while customer.use_vendor_contracts_flag is Y; see Customer Service — Turning On Job/Contract Pricing.

What this means in practice:

• A payload that works in development can fail in production purely because the service account there has a different role. The error will look like a schema problem and send you hunting through definitions.
• Required: true in the definition tells you nothing about this — the definition is static metadata; disabled-ness is evaluated per session (see What Required actually means).
• Test with the account that will run the integration, not with an admin login or your own. This is the single cheapest way to avoid a class of late surprise.
• When a column is refused for your service account and you need it, the fix is a P21 configuration change — a role permission or a DynaChange rule exemption — not a payload change. IgnoreDisabled: true is not a substitute and can silently write nothing.

A worked example of the split. Granting a service account a Buyer ID in User Maintenance cleared the To create a PO, you must have a valid Buyer ID. gate on c_create_po — but the same account still could not set disposition, which a CSR login set without trouble. One permission was configuration; the other is a different gate entirely. Do not assume a single setting unlocks a whole workflow — see Driving an In-Window Wizard.

IgnoreDisabled

IgnoreDisabled: true does more than suppress errors — it is the documented unlock for writing through system-disabled columns and disabled sub-tabs that the Transaction API otherwise cannot touch:

• Forms whose defaults carry read-only/system columns (e.g. bin maintenance flags) fail with General Exception: Column is disabled: <column> unless the flag is set.
• Some grids that live on a disabled sub-tab (e.g. job contract BINS quantities) accept keyed edits once the flag is set — see Editing Bin Quantities.

Two placement rules:

1. IgnoreDisabled goes at the payload top level — alongside Name and Transactions. Placed inside a Transaction object it is silently ignored, and every transaction fails with Column is disabled: <column>.
2. It applies to the whole TransactionSet — there is no per-transaction form.

{
    "Name": "JobContractPricing",
    "UseCodeValues": false,
    "IgnoreDisabled": true,
    "Transactions": [ ... ]
}

Caution: the flag lets edits through columns P21 normally protects. Only send fields you intend to change, and verify results after the first run.

Credit: Alex Westemeier for mapping the placement failure mode and the disabled-tab unlock behavior.

It is not a universal unlock — and it can hide the failure. On P21 26.1, writes to the JobContractPricing VALUES.values element are refused with General Exception: Tab page is disabled and cannot be selected. Adding IgnoreDisabled: true flips the response to Summary: {"Failed": 0, "Succeeded": 1} / Status: "Passed" and writes nothing — the echoed response even drops the affected DataElements, so the omission is invisible in the response body. The same false success reproduces on the JobContractPricing header column corp_address_id, on Order's LINE_NOTE.line_note, on ProductionOrder's header-note grid (PROD_ORDER_HDR_NOTE_TAB.prod_order_hdr_note_tab), and on SalesPricePage's USED BY.price_book_x_page link. That is five surfaces across four services, which marks it as platform behavior. Always read back after a write that used this flag. Detail: VALUES Writes Are Refused on 26.1 and Breaking Changes entry 8.

UseCodeValues

This setting controls how dropdown/checkbox values are interpreted:

Recommendation: Use false (display values) for better readability — this is also Epicor's own guidance: "It is recommended to use display value using UseCodeValues = false (which is the default)." The accepted display values for a field are published as ValidValues in its service definition. (Exception: some report services require code values — see PDF Report Generation.)

Labels vs What the Database Stores (code_p21)

For enum-style columns, the API's display labels come from the code_p21 table (language_id = 9), but the database stores the integer code_no — which is what OData reads return. When you verify a write via OData, map the numbers back to labels with:

SELECT code_no, code_description
FROM code_p21
WHERE language_id = '9';

Verified examples (JobContractPricing cost/pricing enums):

(Credit: Alex Westemeier — maps verified against code_p21.)

The mapping is for reading, not writing. row_status_flag is typed Long, which invites sending the integer — but under UseCodeValues: false the API rejects "700" and "704" alike with Invalid row_status_flag value. Use these numbers to interpret an OData read; send the label. See Customer Service — Removing a Salesrep Grid Row.

Reading One Record -- POST /transaction/get

POST /api/v2/transaction/get is the Transaction API's read side. It is a POST despite being called "get" — the key you are looking up travels in the body, not the query string, so a GET against this path is not the call you want.

Give it a service name and the key identifying one record, and it returns that record as a complete TransactionSet — every populated field across every tab of the window, in the same shape you would POST back to /transaction. Examples throughout this doc use it as the read-back after a write; the same call is also the fastest way to see what a window actually holds.

When this, and when OData

Both read data and neither writes. They differ in shape, and the choice is usually obvious once stated:

The practical difference is the assembly. Pulling one item's full picture over OData means knowing that inv_mast, inv_loc, inventory_supplier and friends go together and querying each; /transaction/get returns what the window shows, already joined. Past one record, that advantage inverts and OData wins outright.

Clone an existing record

Because the response is shaped like a request, the read output is a ready-made template: read one record, change the key field, POST the result to /transaction. It is the practical way to duplicate a well-configured record rather than reconstructing it field by field — a "standard CSR" user copied to a new hire, a customer or location modeled on an existing one, an item cloned from its nearest sibling.

Expect to edit the payload rather than replaying it verbatim, and budget for these:

• Disabled and auto-generated fields come back in the response even though you cannot write them. On Order the replay stops one field at a time — Column is disabled: customer_name, then Column is disabled: company_id — because the read returns display columns the window computes rather than accepts. IgnoreDisabled: true is the usual reach, but it is not a reliable unlock and it can report success while writing nothing; see IgnoreDisabled and Breaking Changes entry 8. Deleting the offending fields is the cleaner fix, and GET /api/v2/basics/{name} is a good filter to delete them by — intersecting the read-back with the basics field list (then adding back the keys basics omits) turned a failing verbatim replay of a two-line order into a clean clone in one pass.
• Popups, locked tabs and stale references (a location that no longer exists, say) stop the replay the same way they would stop any other transaction. So does ordinary cross-field validation on values that were fine on the original record: a verbatim replay of a same-day order failed on The Expedite Date must be on or before the Required Date, because the read hands back both dates and the window re-validates them on the way in.
• Read the clone back before treating it as done. A partially-applied clone reports success like any other transaction.

Reading several records in one call

TransactionStates is a list, and it behaves like one: give it N key sets and the response carries N Transactions, each a complete record.

{
  "ServiceName": "Order",
  "TransactionStates": [
    {"DataElementName": "TABPAGE_1.order", "Keys": [{"Name": "order_no", "Value": "1000001"}]},
    {"DataElementName": "TABPAGE_1.order", "Keys": [{"Name": "order_no", "Value": "1000002"}]}
  ]
}

Size the request with that in mind — one Order record is a few hundred KB of JSON, so this is a way to fetch a handful of records, not a bulk export. For anything wider, use OData.

There is no server-side subsetting (probed on 26.1): the response envelope's Query, FieldMap and TransactionSplitMethod fields are echo-only on this endpoint — sending them back populated, or adding element-list fields, changes nothing (byte-identical response). Keying a TransactionState on a List element (TP_ITEMS.items by oe_order_item_id) fails the read outright. You always get the whole window; filter client-side.

(Section contributed from a community session, Felipe Maurer, 2026; verified against a 26.1 tenant, August 2026 — 102 elements returned for one Order, and two TransactionStates returning two Transactions.)

Async Operations

For long-running operations, use the async endpoint. Async requests run in a dedicated session (avoiding session pool contamination) but have a limited queue.

Queue capacity: The server defaults to only 2 concurrent async requests (AsyncRequests.QueueCapacity in Web.config). Additional requests are queued and may time out under heavy load. Plan batch operations accordingly.

Submit Async Request

POST /api/v2/transaction/async

The body is the same TransactionSet you would POST to /transaction. The response (verified 26.1, August 2026 — HTTP 200, not the 202 documented for earlier versions) is a status wrapper, the same shape the status GET returns:

{
    "RequestId": "c27a95d8-4a4e-4183-9d86-7be1dd242f92",
    "RequestType": "V2 Transaction",
    "Key": "N/A",
    "StartDate": "2026-08-19T19:55:58.78-05:00",
    "CompletedDate": null,
    "Status": 3,
    "CallbackResult": null,
    "Messages": null
}

Check Status

GET /api/v2/transaction/async?id={RequestId}

Once the run finishes, CompletedDate is set and Status flips to 2:

{
    "RequestId": "c27a95d8-...",
    "CompletedDate": "2026-08-19T19:56:00.317",
    "Status": 2,
    "Messages": "{\"Results\": {...}, \"Messages\": [], \"Summary\": {\"Failed\": 0, \"Succeeded\": 1, \"Other\": 0}}"
}

Two traps in this wrapper, both verified by running a valid and an invalid transaction side by side:

• Status is queue state, not outcome. 3 = queued/running, 2 = completed — and it is 2 for a transaction that failed exactly as for one that succeeded. Do not branch on it.

(Epicor's SDK describes this field as the strings Active, Complete or Failed. On 26.1 it is an integer, and there is no Failed state — a failed transaction completes as 2 and reports its failure only in the inner envelope. Handle both spellings if you support older builds.) - The outcome is double-encoded. Messages is a JSON string containing the complete synchronous-style envelope (Results / Messages / Summary) — parse the wrapper, then json.loads(wrapper["Messages"]), and read Summary.Failed and the inner Messages there. The failed run's business-rule text appears only at that inner level.

What the immediate response does and does not tell you. The submit returns in milliseconds with a request ID, and that is an acknowledgement of queueing only — not of validation, and not of success. A transaction that the synchronous endpoint would have rejected returns a perfectly normal request ID here. The status GET is where the outcome lives, and it carries the same Messages the synchronous call would have returned — a request that failed shows its Failed count and the business-rule text ("You cannot cancel an order that is fully invoiced", for instance) only once you go and read it. Treat the request ID as something you must persist and follow up on; work submitted and never checked is work whose outcome nobody knows.

Callbacks instead of polling

/async makes you poll. /async/callback doesn't — it takes a webhook spec alongside the transaction and calls you when the work finishes. This is the endpoint to reach for when "persist the request ID and follow up" is awkward, which is most of the time.

The body wraps the ordinary TransactionSet in an envelope:

POST /api/v2/transaction/async/callback
{
  "Content": { "Name": "Order", "UseCodeValues": false, "Transactions": [ ... ] },
  "Callback": {
    "Url": "https://your-listener.example.com/p21-hook",
    "Method": "POST",
    "ContentType": "application/json",
    "Headers": [ {"Name": "X-Api-Key", "Value": "..."} ]
  }
}

• ContentType is application/xml or application/json
• Headers is a list — use it to authenticate the call into your own receiver
• What P21 posts to your URL is the AsyncRequest — the same object the status GET returns, so parse it exactly as described above (including the double-encoded Messages string)

CallbackResult on the status object then tells you how your endpoint responded — e.g. Success : 200 (OK). On a plain /async submit it stays null, which is why it looks like a dead field until you use callbacks.

(Envelope from the Epicor SDK Transaction API reference guide, served at {middleware}/docs/p21sdk/index.html#/transaction/reference-guide. Not exercised here — it needs a P21-reachable listener.)

There is no cancel. Once transactions are queued there is no endpoint to stop them — probed on a 26.1 tenant, every cancel-shaped route 404s (DELETE /api/v2/transaction/async/{id}, DELETE /api/v2/transaction/{id}, POST /api/v2/transaction/async/cancel), and DELETE /api/v2/transaction/async returns 405: the route exists, for POST only — a loop that submits 50,000 wrong requests will run all 50,000, and every one fires the same DynaChange rules, alerts and event rules a synchronous call would. This is the endpoint's real hazard: it removes the natural backpressure of waiting for each response, so a payload bug that a synchronous run would have surfaced on record one instead surfaces after the whole batch has landed. Validate the payload synchronously against a single record before submitting a batch async. (Community session, Felipe Maurer, 2026.)

With Callback

Use the callback endpoint to receive notification when complete:

{
    "Content": {
        "Name": "Order",
        "Transactions": [...]
    },
    "Callback": {
        "Url": "https://p21.example.com/webhook",
        "Method": "POST",
        "ContentType": "application/json",
        "Headers": [
            {"Name": "X-API-Key", "Value": "your-key"}
        ]
    }
}

Commands Endpoint

Some P21 services cannot use the standard /api/v2/transaction endpoint. These must use the commands endpoint instead:

POST /api/v2/commands

Services Requiring Commands Endpoint

Important: If you send these services to the standard /transaction endpoint, they will fail. Always check the service documentation or test with the Service Explorer to determine which endpoint to use.

Request Shape

/commands does not take a TransactionSet. It takes an ordered list of interactive commands — it is the Interactive API's window-driving model exposed as one stateless POST. That is exactly why these services live here: they need row selection, tool clicks and drag-and-drop controls that a declarative TransactionSet cannot express.

POST /api/v2/commands
{
  "Requests": [
    {"Action": 0, "DetailLevel": 0, "Args": {"ServiceName": "ItemNotepad"}},
    {"Action": 2, "DetailLevel": 0, "Args": {"List": [
        {"DatawindowName": "tp_1_dw_1", "FieldName": "inv_mast_item_id", "Value": "WIDGET-001"},
        {"DatawindowName": "tp_1_dw_1", "FieldName": "topic",            "Value": "API NOTE"},
        {"DatawindowName": "tp_1_dw_1", "FieldName": "note",             "Value": "Note text"}]}},
    {"Action": 5, "DetailLevel": 0, "Args": {"DatawindowName": "tp_17_dw_dragdrop", "Row": 2}},
    {"Action": 9, "DetailLevel": 0, "Args": {"ToolName": "cb_select", "Row": 0}},
    {"Action": 6, "DetailLevel": 0},
    {"Action": 1, "DetailLevel": 0}
  ]
}

Each entry runs in order against one implicit window; the response returns one Result per request, carrying the same Events the Interactive API emits:

{"Status": 1, "Results": [
  {"Result": {"WindowId": "...", "Status": 1, "Events": [{"Name": "windowopened", ...}], "Messages": []}, "Data": null},
  ...
]}

Watch the save entry's events for savesucceeded, and read the record back — Status: 1 on the envelope is not proof, exactly as on /transaction.

Action codes

Verified against a 26.1 tenant (August 2026) by running each value and reading the response:

3 and 4 are real but unmapped: 4 with a DatawindowName returns Status: 2 (Failure), while 3 with any argument shape — and 4 with none — returns HTTP 204. 7, 8, and 10+ return an empty HTTP 500, the not-implemented signature seen elsewhere on 26.1.

A 204 empties the entire response, not just that step. One unrecognised action mid-batch and you get a zero-length body — no Results array, no per-step statuses, nothing to inspect about the steps that did run. Parse defensively: check for a body before calling .json(), and treat a 204 as "the batch told you nothing", not as success. DetailLevel was 0/1/2 across these probes with no observable difference; its effect is undocumented.

This is the sanctioned path for notepads. Verified end-to-end on 26.1 (August 2026): the payload above wrote an item note — including satisfying the mandatory drag-and-drop area selector via Action 5 (select a row in tp_17_dw_dragdrop) then Action 9 (cb_select) — returned savesucceeded, and the row was confirmed in the note table. See Limitations for how this relates to the /transaction endpoint's refusal of the same services.

Special Scenarios

Field and DataElement Ordering

Some services require specific ordering of DataElements or Edits within a request. The API processes them sequentially, and some fields trigger validation or auto-population of other fields.

The general rule: repeat the element pair, don't batch it

The Transaction API replays a payload the way an operator would work the window: it applies elements top to bottom, and a child element attaches to whichever parent row is current at that point in the sequence. So when several parent rows each need child data on another tab, repeat the pair per row rather than sending all the parents and then all the children:

Correct:  item A → its detail A → item B → its detail B
Wrong:    item A → item B → detail A → detail B

The second form doesn't error — it applies both details to whatever row was current, which is the last one. Verified on a 26.1 tenant with a two-line order and TP_EXTDINFO.extd_info: sending item A → item B → extd "EXT-FOR-A" → extd "EXT-FOR-B" returns Succeeded: 1 with no messages and lands both descriptions on line 2, last one winning, leaving line 1's extended_desc null. The interleaved sequence puts each description on its own line. An element may appear as many times as you need in a single transaction; a ten-line order that also sets extended info per line is ten repetitions of the pair, in order. This is the same rule the lot-item and break-line cases below are specific instances of. (General statement of the rule: community session, Felipe Maurer, 2026; verified August 2026.)

Credit Card Payment Orders: DataElements must appear in this order — the two payment elements go after every other element in the request, not in window order: 1. Order header (TABPAGE_1.order) 2. Items (TP_ITEMS.items) 3. Remittances (TP_REMITTANCES.remittances) — payment_type_id, payment_amount, payment_desc 4. CC Transaction Response (TP_CCTRANSACTIONRESPONSE.cctransactionresponse)

The CC element carries the result of an authorization performed elsewhere — the API takes the outcome, never card entry (see Limitations). Its fields: auth_amount, cc_authorized_number, cc_authorized_date, retrieval_ref_number, payment_account_id (the stored-payment token), cc_number (masked, e.g. ************6781), cc_expiration_date, payment_number. The token plausibly originates from the api/cardstorage REST family listed on the middleware's API Reference page; that link is unverified here.

Task — target_date before start_date: The Task window validates that start ≤ target, and both default to today. Setting start_date first validates it against a target that is still the default, and the transaction fails. Put target_date (and target_minute) earlier in the Edits array than start_date. Same class of bug as pricing_method before price — the API replays edits in order and each one validates as it lands.

The Task service form is Form.form, keyed on activity_trans_no, carrying subject, target_date/target_minute, start_date/start_minute, completed_flag, reminder_time_offset + reminder_time_offset_cd (e.g. "Minute(s)"), activity_id, assigned_to_id, contact_id, transaction_type_cd. (From the Epicor SDK Transaction API reference guide; the ordering rule is Epicor's own, not re-tested here.)

Customer — use_vendor_contracts_flag before job_pricing: On TABPAGE_7.tp_7_dw_7, job_pricing is disabled until use_vendor_contracts_flag is N. Put use_vendor_contracts_flag = N earlier in the Edits array than job_pricing = Y; see Customer Service — Turning On Job/Contract Pricing.

Multiple Lot Items: When creating items with lot tracking, interleave item and lot DataElements: 1. Item 1 → Lot 1 2. Item 2 → Lot 2 3. (not: Item 1 → Item 2 → Lot 1 → Lot 2)

SalesPricePage Fields: 1. price_page_type_cd — triggers type-specific validation 2. company_id — required before product group 3. product_group_id or discount_group_id 4. supplier_id 5. Other fields...

Examples

Get Service Definition

What Required actually means

The definition is the authoritative field map — element names, DataType, KeyFields, and the ValidValues behind dropdowns are all reliable. Required is not. It reflects the window's field metadata, not the API's contract, and it is wrong in both directions:

Marked required, must be omitted. Order's TABPAGE_1.order marks company_id as Required: true — and company_id is a disabled column that fails the whole transaction with Column is disabled: company_id. The same pattern is reported on PurchaseOrder (division_id) and ConvertPOToVoucher (company_id, branch_id, period, year_for_period), all of which default correctly when left out. Across the committed definitions, 571 of 7,539 fields (7.6%) carry the flag, so this is not a rare mislabel.

Marked optional, actually required. The reverse also happens — JobContractPricing's contract_no is marked optional and a create without it fails outright (see its service entry).

Derive the minimum payload empirically. Start from a known-good example, add fields until the write passes, and stop. Padding a payload to satisfy Required is a reliable way to hit Column is disabled — and because a Transaction is atomic, one padded field fails the entire thing.

This is also why GET /api/v2/basics/{name} both omits fields you need and includes fields you cannot write: it is generated as KeyFields ∪ Required, so it inherits every one of these errors.

Probing a field in isolation can give a false negative. Whether a column is disabled is decided after the window loads its record, so a minimal probe that fails validation earlier never reaches the check. Sending company_id to ConvertPOToVoucher with no valid PO fails on No receipts have been selected — looking, misleadingly, like an accepted field. Send the same field in a complete, otherwise-valid payload and you get the truth: Column is disabled: company_id. Both observed here on the same tenant an hour apart. Test disabled-ness in context, never in isolation.

(Verified on a 26.1 tenant, August 2026. The PurchaseOrder / ConvertPOToVoucher cases were reported by Alex Westemeier and are confirmed here — including the company_id refusal, once probed in a full voucher payload.)

"""Print a Transaction API service definition -- elements, keys, and field names."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.example.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
SERVICE_NAME = "Order"                    # any name from GET /api/v2/services
# ---------------------------------------------------------------------------


def get_token(client: httpx.Client) -> str:
    """v2 token endpoint — credentials go in the body, never in headers."""
    r = client.post(
        f"{BASE_URL}/api/security/token/v2",
        json={"username": USERNAME, "password": PASSWORD},
        headers={"Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["AccessToken"]
    except (ValueError, KeyError):  # some middleware answers in XML
        match = re.search(r"<AccessToken>([^<]+)</AccessToken>", r.text)
        if not match:
            raise ValueError(f"No AccessToken in response: {r.text[:200]}") from None
        return match.group(1)


def get_ui_server(client: httpx.Client, token: str) -> str:
    """Transaction and Interactive calls go to the UI server, not BASE_URL."""
    r = client.get(
        f"{BASE_URL}/api/ui/router/v1/?urlType=external",  # trailing slash avoids a 307
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["Url"].rstrip("/")
    except (ValueError, KeyError):
        match = re.search(r"<Url>([^<]+)</Url>", r.text)
        if not match:
            raise ValueError(f"No Url in router response: {r.text[:200]}") from None
        return match.group(1).rstrip("/")


with httpx.Client(verify=VERIFY_SSL, timeout=120, follow_redirects=True) as client:
    token = get_token(client)
    ui_server = get_ui_server(client, token)
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",       # without this you get XML, not JSON
        "Content-Type": "application/json",
    }

    response = client.get(
        f"{ui_server}/api/v2/definition/{SERVICE_NAME}", headers=headers
    )
    response.raise_for_status()
    definition = response.json()

    # definition["Template"] is a blank payload template for creating records.
    # The elements live under TransactionDefinition.DataElementDefinitions.
    elements = definition["TransactionDefinition"]["DataElementDefinitions"]
    print(f"{SERVICE_NAME}: {len(elements)} DataElements")
    for element in elements:
        print(f"  {element.get('Name')}"
              f"  Type={element.get('Type')}"
              f"  Datawindow={element.get('DatawindowName')}"
              f"  Keys={element.get('KeyFields')}")

    # The API field Name is frequently NOT the underlying column name --
    # DbColumnName is what maps a field back to the table you know.
    first = elements[0]
    print(f"\nFirst 10 fields on {first.get('Name')}:")
    for field in first.get("FieldDefinitions", [])[:10]:
        print(f"  {str(field.get('Name')):<30}"
              f" db={str(field.get('DbColumnName')):<30}"
              f" type={field.get('DataType')} required={field.get('Required')}")

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.example.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string ServiceName = "Order";                    // any name from GET /api/v2/services
// ---------------------------------------------------------------------------

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var response = await client.GetAsync($"{uiServer}/api/v2/definition/{ServiceName}");
response.EnsureSuccessStatusCode();

using var definition = JsonDocument.Parse(await response.Content.ReadAsStringAsync());

// definition.RootElement.GetProperty("Template") is a blank payload template for
// creating records. The elements live under TransactionDefinition.DataElementDefinitions.
var elements = definition.RootElement
    .GetProperty("TransactionDefinition")
    .GetProperty("DataElementDefinitions");

Console.WriteLine($"{ServiceName}: {elements.GetArrayLength()} DataElements");
foreach (var element in elements.EnumerateArray())
{
    Console.WriteLine(
        $"  {element.GetProperty("Name")}" +
        $"  Type={element.GetProperty("Type")}" +
        $"  Datawindow={element.GetProperty("DatawindowName")}" +
        $"  Keys={element.GetProperty("KeyFields")}");
}

// The API field Name is frequently NOT the underlying column name --
// DbColumnName is what maps a field back to the table you know.
var first = elements[0];
Console.WriteLine($"\nFirst 10 fields on {first.GetProperty("Name")}:");
foreach (var field in first.GetProperty("FieldDefinitions").EnumerateArray().Take(10))
{
    Console.WriteLine(
        $"  {field.GetProperty("Name"),-30}" +
        $" db={field.GetProperty("DbColumnName"),-30}" +
        $" type={field.GetProperty("DataType")} required={field.GetProperty("Required")}");
}

// --- helpers ---------------------------------------------------------------

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}

The definition is the authoritative schema map for a service. The response shape is {"Name": ..., "TransactionDefinition": {"KeyDefinitions": [...], "DataElementDefinitions": [...]}, "Template": {...}} — the elements live under TransactionDefinition.DataElementDefinitions. Each element carries:

Use it to discover which tab/datawindow a given table lives on and exactly which column names and required fields a write needs. The API field Name is frequently not what you'd guess from the underlying table column — check DbColumnName in FieldDefinitions to map between the two.

Warning — don't derive TABPAGE_N from the visible tab order: TABPAGE_N names are not sequential with the tabs visible in the P21 UI — windows carry many disabled/hidden tab pages (PurchaseOrder has 37), so the grid that looks like the second tab can be TABPAGE_17 (tp_17_dw_17). When cross-referencing the definition against live Interactive calls, match on the datawindow name (tp_N_dw_N / d_...) or read the Interactive window's TabPageList (GET /api/ui/interactive/v2/window?id={windowId}) — never count tabs on screen. On the servers tested (25.2/26.x), the Interactive window's TABPAGE_N names matched the definition's 1:1.

Create Order

"""Create a sales order, then read the created order back by its order_no."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.example.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
CUSTOMER_ID = "100198"                    # customer the order is placed for
SOURCE_LOC_ID = "100"                     # effectively required -- see the gotchas below
SALES_LOC_ID = "100"                      # selling location
ITEM_ID = "WIDGET-001"                    # item on the first line
QUANTITY = "1"                            # unit quantity for that line
# ---------------------------------------------------------------------------


def get_token(client: httpx.Client) -> str:
    """v2 token endpoint — credentials go in the body, never in headers."""
    r = client.post(
        f"{BASE_URL}/api/security/token/v2",
        json={"username": USERNAME, "password": PASSWORD},
        headers={"Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["AccessToken"]
    except (ValueError, KeyError):  # some middleware answers in XML
        match = re.search(r"<AccessToken>([^<]+)</AccessToken>", r.text)
        if not match:
            raise ValueError(f"No AccessToken in response: {r.text[:200]}") from None
        return match.group(1)


def get_ui_server(client: httpx.Client, token: str) -> str:
    """Transaction and Interactive calls go to the UI server, not BASE_URL."""
    r = client.get(
        f"{BASE_URL}/api/ui/router/v1/?urlType=external",  # trailing slash avoids a 307
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )
    r.raise_for_status()
    try:
        return r.json()["Url"].rstrip("/")
    except (ValueError, KeyError):
        match = re.search(r"<Url>([^<]+)</Url>", r.text)
        if not match:
            raise ValueError(f"No Url in router response: {r.text[:200]}") from None
        return match.group(1).rstrip("/")


def walk(node):
    """Yield every {"Name": ..., "Value": ...} pair anywhere in a response."""
    if isinstance(node, dict):
        if "Name" in node and "Value" in node:
            yield node["Name"], node["Value"]
        for value in node.values():
            yield from walk(value)
    elif isinstance(node, list):
        for item in node:
            yield from walk(item)


with httpx.Client(verify=VERIFY_SSL, timeout=120, follow_redirects=True) as client:
    token = get_token(client)
    ui_server = get_ui_server(client, token)
    headers = {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json",       # without this you get XML, not JSON
        "Content-Type": "application/json",
    }

    payload = {
        "Name": "Order",
        "UseCodeValues": False,
        "Transactions": [{
            "Status": "New",
            "DataElements": [
                {
                    "Name": "TABPAGE_1.order",
                    "Type": "Form",
                    "Keys": [],
                    "Rows": [{
                        "Edits": [
                            {"Name": "customer_id", "Value": CUSTOMER_ID},
                            # Omit source_loc_id and the save fails with a
                            # "Jurisdiction ID for Order Header Tax" error.
                            {"Name": "sales_loc_id", "Value": SALES_LOC_ID},
                            {"Name": "source_loc_id", "Value": SOURCE_LOC_ID},
                        ],
                        "RelativeDateEdits": []
                    }]
                },
                {
                    "Name": "TP_ITEMS.items",
                    "Type": "List",
                    "Keys": [],
                    "Rows": [{
                        "Edits": [
                            {"Name": "oe_order_item_id", "Value": ITEM_ID},
                            {"Name": "unit_quantity", "Value": QUANTITY}
                        ],
                        "RelativeDateEdits": []
                    }]
                }
            ]
        }]
    }

    response = client.post(f"{ui_server}/api/v2/transaction", headers=headers, json=payload)
    response.raise_for_status()          # HTTP 200 does NOT mean the write succeeded
    result = response.json()
    print("Summary:", result.get("Summary"))
    for transaction in result.get("Results", {}).get("Transactions", []):
        print("  Transaction status:", transaction.get("Status"))
    for message in result.get("Messages") or []:
        print("  Message:", message)

    # ---- read-back: the only proof the order landed -------------------------
    # The generated order_no comes back in the result rows.
    order_no = next((value for name, value in walk(result) if name == "order_no"), None)
    print("Created order_no:", order_no)

    if order_no:
        read_back = client.post(
            f"{ui_server}/api/v2/transaction/get",
            headers=headers,
            json={
                "ServiceName": "Order",
                "TransactionStates": [{
                    "DataElementName": "TABPAGE_1.order",   # KeyFields: ["order_no"]
                    "Keys": [{"Name": "order_no", "Value": order_no}],
                }],
            },
        )
        read_back.raise_for_status()

        wanted = {"order_no", "customer_id", "order_date"}
        for name, value in walk(read_back.json()):
            if name in wanted:
                print(f"  {name} = {value}")

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

// ---- EDIT THESE -----------------------------------------------------------
const string BaseUrl = "https://play.example.com";   // your P21 server
const string Username = "apiuser";
const string Password = "your-password";
const string CustomerId = "100198";                    // customer the order is for
const string SourceLocId = "100";                      // effectively required -- see gotchas
const string SalesLocId = "100";                       // selling location
const string ItemId = "WIDGET-001";                    // item on the first line
const string Quantity = "1";                           // unit quantity for that line
// ---------------------------------------------------------------------------

var handler = new HttpClientHandler
{
    // Test tenants often present a self-signed cert. Delete this line in production.
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator,
};
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromMinutes(2) };
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var token = await GetTokenAsync(client);
var uiServer = await GetUiServerAsync(client, token);
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

var payload = new
{
    Name = "Order",
    UseCodeValues = false,
    Transactions = new[] {
        new {
            Status = "New",
            DataElements = new object[] {
                new {
                    Name = "TABPAGE_1.order",
                    Type = "Form",
                    Keys = Array.Empty<string>(),
                    Rows = new[] {
                        new { Edits = new[] {
                            new { Name = "customer_id", Value = CustomerId },
                            // Omit source_loc_id and the save fails with a
                            // "Jurisdiction ID for Order Header Tax" error.
                            new { Name = "sales_loc_id", Value = SalesLocId },
                            new { Name = "source_loc_id", Value = SourceLocId },
                        }}
                    }
                },
                new {
                    Name = "TP_ITEMS.items",
                    Type = "List",
                    Keys = Array.Empty<string>(),
                    Rows = new[] {
                        new { Edits = new[] {
                            new { Name = "oe_order_item_id", Value = ItemId },
                            new { Name = "unit_quantity", Value = Quantity }
                        }}
                    }
                }
            }
        }
    }
};

var response = await client.PostAsync(
    $"{uiServer}/api/v2/transaction",
    new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();     // HTTP 200 does NOT mean the write succeeded

using var result = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine($"Summary: {result.RootElement.GetProperty("Summary")}");
if (result.RootElement.TryGetProperty("Results", out var results)
    && results.TryGetProperty("Transactions", out var resultTransactions))
{
    foreach (var transaction in resultTransactions.EnumerateArray())
        Console.WriteLine($"  Transaction status: {transaction.GetProperty("Status")}");
}
if (result.RootElement.TryGetProperty("Messages", out var messages))
{
    foreach (var message in messages.EnumerateArray())
        Console.WriteLine($"  Message: {message}");
}

// ---- read-back: the only proof the order landed ---------------------------
// The generated order_no comes back in the result rows.
string? orderNo = null;
foreach (var (name, value) in Walk(result.RootElement))
{
    if (name == "order_no") { orderNo = value; break; }
}
Console.WriteLine($"Created order_no: {orderNo}");

if (!string.IsNullOrEmpty(orderNo))
{
    var getPayload = new
    {
        ServiceName = "Order",
        TransactionStates = new[]
        {
            new
            {
                DataElementName = "TABPAGE_1.order",     // KeyFields: ["order_no"]
                Keys = new[] { new { Name = "order_no", Value = orderNo } },
            }
        }
    };

    var readBackResponse = await client.PostAsync(
        $"{uiServer}/api/v2/transaction/get",
        new StringContent(JsonSerializer.Serialize(getPayload), Encoding.UTF8, "application/json"));
    readBackResponse.EnsureSuccessStatusCode();

    using var readBack = JsonDocument.Parse(await readBackResponse.Content.ReadAsStringAsync());
    var wanted = new HashSet<string> { "order_no", "customer_id", "order_date" };
    foreach (var (name, value) in Walk(readBack.RootElement))
    {
        if (wanted.Contains(name))
            Console.WriteLine($"  {name} = {value}");
    }
}

// --- helpers ---------------------------------------------------------------

// Yield every {"Name": ..., "Value": ...} pair anywhere in a response.
static IEnumerable<(string Name, string Value)> Walk(JsonElement node)
{
    if (node.ValueKind == JsonValueKind.Object)
    {
        if (node.TryGetProperty("Name", out var name) && node.TryGetProperty("Value", out var value))
            yield return (name.ToString(), value.ToString());
        foreach (var property in node.EnumerateObject())
            foreach (var pair in Walk(property.Value))
                yield return pair;
    }
    else if (node.ValueKind == JsonValueKind.Array)
    {
        foreach (var item in node.EnumerateArray())
            foreach (var pair in Walk(item))
                yield return pair;
    }
}

// v2 token endpoint — credentials go in the body, never in headers.
static async Task<string> GetTokenAsync(HttpClient client)
{
    var payload = JsonSerializer.Serialize(new { username = Username, password = Password });
    var response = await client.PostAsync(
        $"{BaseUrl}/api/security/token/v2",
        new StringContent(payload, Encoding.UTF8, "application/json"));
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "AccessToken");
}

// Transaction and Interactive calls go to the UI server, not BaseUrl.
static async Task<string> GetUiServerAsync(HttpClient client, string token)
{
    using var request = new HttpRequestMessage(
        HttpMethod.Get, $"{BaseUrl}/api/ui/router/v1/?urlType=external");
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
    var response = await client.SendAsync(request);
    response.EnsureSuccessStatusCode();
    return ReadField(await response.Content.ReadAsStringAsync(), "Url").TrimEnd('/');
}

// Some middleware answers these two endpoints in XML even when asked for JSON.
static string ReadField(string payload, string field)
{
    try
    {
        var value = JsonDocument.Parse(payload).RootElement.GetProperty(field).GetString();
        if (!string.IsNullOrEmpty(value)) return value;
    }
    catch (Exception ex) when (ex is JsonException or KeyNotFoundException) { }

    var match = System.Text.RegularExpressions.Regex.Match(payload, $"<{field}>([^<]+)</{field}>");
    if (!match.Success)
        throw new InvalidOperationException(
            $"No {field} in response: {payload[..Math.Min(200, payload.Length)]}");
    return match.Groups[1].Value;
}

Order Service Gotchas

All verified live (credit: Alex Westemeier):

• Send quote = OFF as the first header edit. On play 26.1.5950.0, 2026-10-10, an Order create without it saved a quote (oe_hdr.projected_order = 'Y') for the password user, and a pick ticket for it was then refused. With quote = OFF the same payload saved a real order (projected_order = 'N'). This is the Transaction API side of Set quote to OFF first; read projected_order back after the save.
• source_loc_id is effectively required. Omitting it fails with a "Jurisdiction ID for Order Header Tax" error — the tax jurisdiction does not auto-populate through the API the way it does in the UI. A ship-to with no tax jurisdiction fails the same way even with source_loc_id set, once the order is real (quote = OFF) and a line is taxable; a quote saves without it. A realistic header sets quote, customer_id, sales_loc_id, source_loc_id, order_date, requested_date, po_no, taker, ship_to_id, and contact_id. Fix: send the jurisdiction yourself as a TP_TAX.tp_tax List row keyed jurisdiction_id (for example the ship-to's state code) in the same transaction — the order then saves with the matching oe_hdr_tax row. The header's own taxable column is disabled (Column is disabled: taxable), so you can't switch tax off instead. (play, 26.1.5950.0, 2026-10-11 — closes #197)

json {"Name": "TP_TAX.tp_tax", "Type": "List", "Keys": ["jurisdiction_id"], "Rows": [{"Edits": [{"Name": "jurisdiction_id", "Value": "KS"}], "RelativeDateEdits": []}]}

Add it to the order's DataElements after the header element; the value is any valid tax_jurisdiction.jurisdiction_id. - requested_date must be after order_date. The same date trips a date-cascade prompt, which the stateless API can't answer. - company_id is a disabled column on the Order window — don't send it. - DynaChange prompts are auto-answered with the default (usually "No"), which silently discards the affected line — e.g. "order line does not have a PO Cost… proceed? [No]". On multi-item orders the remaining lines then cascade-fail. This is a P21 configuration matter (exempt the rule for the API user, or fix the data), not something a payload change can work around — see DynaChange and Popup Handling. - Assembly items explode through the Transaction API on 26.1.5950.0. There is no prompt to answer: an assembly item on TP_ITEMS.items is saved the way the Interactive "add as assembly?" Yes answer saves it. On play 26.1.5950.0, 2026-10-10, a quote = OFF Order create with one kit item (production_order_processing = N) saved a B parent line plus N component lines, and one with a production-order assembly (production_order_processing = Y, auto_create_prod_order = N) saved an assembly = 'P' line (disposition = 'P') plus its component lines. Earlier versions of this page said the prompt is auto-answered No and the explode is lost; that is not what this build does. What you cannot do here is choose: a plain stock line for an assembly item (the Interactive No, cb_2) needs the Interactive API — see Sales Order Entry with Assembly Lines. Whether an auto_create_prod_order = Y item also creates and links its production order on this path was not tested. - RMAs are not Order records. An order with rma_flag = 'Y' is refused outright: General Exception: You cannot retrieve an RMA from the Order Entry/Front Counter window. Use the RMA service. - The same item on two lines collapses to one with Keys: [] — TP_ITEMS.items folds rows on its declared key (oe_order_item_id), last value wins, Succeeded: 1, no warning. Add Keys: ["unit_quantity"] (or another differing column) when an order legitimately repeats an item — see Keys — Row Identity and the Collapse Trap. - The created order_no comes back in the result rows; check Summary.Succeeded, not the HTTP status. - A document with oe_hdr.completed = 'T' refuses every write — the record-lock prompt fires and the stateless API answers it No. See Order Service — Reassigning the Salesrep for the pre-screen. The holder can be your own API user: a client that was killed mid-request, or an Interactive session that was never ended, keeps the order locked until the server finishes — see Locks and orphaned sessions.

Order Service — Line Appends, Cancels, Holds, and Item Lookup

Field-verified on the Order service. Unless marked otherwise, credit Alex Westemeier — verified on play and production, September 2026. The append, cancel and Hold-release bullets were re-run here with the examples below (play 26.1.5950.0, 2026-10-10); the others were not.

• Append many lines to a saved order in one Transaction, not one per line. Key the header on order_no (TABPAGE_1.order, Keys: ["order_no"]) and send the new lines as multiple rows of one TP_ITEMS.items element (Keys: []). One Transaction per line fails: the rows collide with the existing line and the server answers "Item ID X has been saved; therefore, the Item ID cannot be edited". (The same message also appears, transiently, when an orphaned Interactive session for the same user is still open — end it first; see Locks and orphaned sessions.) Re-run: a two-row TP_ITEMS.items element appended lines 2 and 3 to a saved one-line order (Succeeded: 1). Two single-row Transactions in one POST came back Failed: 1, Succeeded: 1 — the first refused with the message above, the second appended — so per-line Transactions are not even consistently wrong.
• A row whose item is already on the order edits that line instead of adding one. TP_ITEMS.items folds rows on its declared key oe_order_item_id: appending an item ID the order already carries changed the existing line's qty_ordered and reported Succeeded: 1. Check the order's live lines before an append, as the examples do; to add a genuine second line for the same item, over-key the rows (Keys — Row Identity and the Collapse Trap).
• Per-line cost grows with the size of the order. P21 re-reads the whole document after every Transaction, so appending to a large order slows down as it grows. Split very large line lists into orders of about 100 lines — measured numbers and the pattern are in Batch Processing § Large Sales Orders.
• A failed append soft-deletes its rows. Filter read-backs on delete_flag = 'N' AND cancel_flag = 'N' — see A failed create leaves rows behind.
• Cancel an order through the header cancel_flag. TABPAGE_1.order keyed on order_no with the edit cancel_flag = "ON" sets oe_hdr.cancel_flag = 'Y' and completed = 'Y' and releases every line's allocation. P21 reloads the whole order first, so cancelling a very large order takes minutes. Re-run: on a three-line order the header went to cancel_flag = 'Y', completed = 'Y' and every oe_line to cancel_flag = 'Y', with delete_flag still N and qty_canceled left at 0 — so a cancel read-back must check cancel_flag, not qty_canceled. The throwaway items had no stock, so allocation release was not exercised.
• Release a Hold through Ship Info when the header copy is disabled. On some tenants the header packing_basis is a disabled column for the API user ("Column is disabled: packing_basis"). The same field on TP_SHIPINFO.shipinfo (Type: Form, Keys: [], after the keyed TABPAGE_1.order row) is enabled: set it to Partial to release the Hold. Allocation is untouched. Re-run: the TP_SHIPINFO edit moved oe_hdr.packing_basis from Hold to Partial. On the test tenant the header copy was enabled too (an order was created with header packing_basis = Hold), so the TP_SHIPINFO path is the one that works on either kind of tenant.
• TP_SALESREPS on a new order adds rows; it does not replace the default. The customer's default rep row is created at save, after the element is processed (a keyed edit finds "row 0 not found"), and any rep row you send is added on top of it. Two 100% rows then trip the "Do not use the Full Commission flag" rule and the create fails. Rep changes on a new order need either a customer or ship-to whose default rep already satisfies your rules, or the Interactive window (TP_SALESREPS, select row 1, set salesrep_id). Add-then-retire on a saved order is unaffected.
• Item IDs are prefix-matched. An ID that matches more than one item fails with "Ambiguous data detected (PopUp encountered)" — check for near-duplicates that differ only in spacing (ITEM-001 3/8 NPT versus ITEM-001 3/8NPT) and send the exact ID.
• A merged-away item fails with "'X' has been deleted". After an item merge the old ID stays in inv_mast with delete_flag = 'Y', and inv_mast.extended_desc names the survivor. Build line lists from live data at run time, not from a saved spreadsheet.
• A failed create consumes an order number and can leave a soft-deleted header and lines. Look for the stray order before retrying — see A failed create leaves rows behind (verified by the maintainer on 26.1.5950.0).

The append, keyed on the saved order, with every new line a row of one element:

{ "Name": "Order", "UseCodeValues": false,
  "Transactions": [{ "Status": "New", "DataElements": [
    { "Name": "TABPAGE_1.order", "Type": "Form", "Keys": ["order_no"],
      "Rows": [{ "Edits": [ {"Name": "order_no", "Value": "1001234"} ], "RelativeDateEdits": [] }] },
    { "Name": "TP_ITEMS.items", "Type": "List", "Keys": [],
      "Rows": [
        { "Edits": [ {"Name": "oe_order_item_id", "Value": "ITEM-001"},
                     {"Name": "unit_quantity",    "Value": "2"} ], "RelativeDateEdits": [] },
        { "Edits": [ {"Name": "oe_order_item_id", "Value": "ITEM-002"},
                     {"Name": "unit_quantity",    "Value": "3"} ], "RelativeDateEdits": [] }
      ] }
  ]}]
}

The Hold release swaps the second element for TP_SHIPINFO.shipinfo (Form, Keys: [], edit packing_basis = Partial); the cancel drops it and adds cancel_flag = ON to the header row.

Runnable: order_append_hold_cancel.py · OrderAppendHoldCancel.cs (Recipes menu 24) · payloads order-append-lines.json, order-release-hold.json, order-cancel.json. Modes append, release-hold, cancel. Before writing they refuse an order that is deleted, canceled or held open (completed = 'T'), and an append item that is not an exact live item ID or is already on the order; afterwards they read oe_hdr and the live (delete_flag = 'N') oe_line rows back over OData. Python and C# examples run on play 26.1.5950.0, 2026-10-10, each on its own throwaway order (created on Hold): append two lines, release the Hold, cancel.

Order Service — Reassigning the Salesrep

There is no salesrep column on oe_hdr. The rep on a sales order or quote lives in the oe_hdr_salesrep grid, which the Order service exposes as TP_SALESREPS.tp_salesreps — Type: List, keyed on salesrep_id in the service definition. Per-line splits live in oe_line_salesrep. Verified live on production 26.1 across 66 successful writes (sales orders and quotes).

Add-then-retire works the way it does for ship-tos, and this grid has a real delete_flag — unlike customer_salesrep, which needs row_status_flag: "Delete":

{
  "Name": "Order",
  "UseCodeValues": false,
  "Transactions": [{
    "Status": "New",
    "DataElements": [
      {
        "Name": "TABPAGE_1.order",
        "Type": "Form",
        "Keys": ["order_no"],
        "Rows": [{"Edits": [{"Name": "order_no", "Value": "123456"}], "RelativeDateEdits": []}]
      },
      {
        "Name": "TP_SALESREPS.tp_salesreps",
        "Type": "List",
        "Keys": ["salesrep_id"],
        "Rows": [
          {"Edits": [
            {"Name": "salesrep_id", "Value": "1001"},
            {"Name": "primary_salesrep", "Value": "Y"},
            {"Name": "commission_split", "Value": "100"}
          ], "RelativeDateEdits": []},
          {"Edits": [
            {"Name": "salesrep_id", "Value": "1002"},
            {"Name": "delete_flag", "Value": "Y"}
          ], "RelativeDateEdits": []}
        ]
      }
    ]
  }]
}

TABPAGE_1.order only loads the document — order_no is its sole edit and nothing on the order itself is modified. Have the incoming rep inherit the outgoing row's primary_salesrep and commission_split rather than hardcoding 100, or a split-commission order silently becomes a single-rep order.

Failure detail is in the top-level Messages, not on the transaction

Results.Transactions[0] comes back Status: "Failed" with its own Messages set to null. The reason is in the sibling top-level Messages array on the response object. Read the wrong one and the API looks like it failed for no stated reason, which sends you hunting for a payload bug that isn't there.

oe_hdr.completed = 'T' is what blocks the write

If the document is in an in-progress editing state, the write raises a record-lock prompt that the stateless API auto-answers No:

Transaction 1:: General Exception: Order 123456 may currently be edited by JSMITH.
Please verify with that user first, otherwise your change to this order may not be saved
successfully. Do you want to continue to retrieve? [Response: No]

completed is not a boolean — it has a rarely-seen third state. Company-wide on production (September 2026): Y 639,247 · N 184,408 · T 308. In a 66-write run, the single failure was the single T.

• Pre-screen with WHERE completed <> 'T'. This is the check that works; process_in_progress_lock is the wrong table and was empty throughout (0 rows) while the prompt fired, so it cannot be used to screen a batch.
• These locks are usually abandoned, not live. The T rows on production were last modified across every year from 2011 to 2026, only 31 of the 308 in the current year, under usernames that in many cases have long since left. "Wait for the user to finish" is generally wrong advice, and retrying never clears it on its own.
• To clear one: have someone open and properly close the document in P21, or drive it through the Interactive API, which can answer the response window.
• Both <> 'Y' and = 'N' filters treat T differently — pick deliberately.

Credit: @mrwuss — filed as #156; element name, keys, delete_flag, and the completed distribution re-verified here against the service definition and the production catalogue.

Service Reference

JobContractPricing Service

The JobContractPricing service creates and updates job contract price pages -- customer-specific pricing agreements with optional quantity breaks. It has 25 DataElements; the key ones are documented below.

Service Definition

GET /api/v2/definition/JobContractPricing

Header -- FORM.d_dw_job_price_hdr (Form)

Important: corp_address_id must be set during initial creation — it is read-only once the contract is saved. Verified on 26.1.5910.3 (2026-08-11): changing it on a saved contract fails with General Exception: Column is disabled: corp_address_id, and adding IgnoreDisabled: true does not unlock it — the transaction then reports Succeeded: 1 while leaving the value untouched (see entry 8).

Customer/Ship To -- CUSTOMER_SHIP_TO.customer_ship_to (List)

Attaching a ship-to to an existing contract

Contract pricing follows this grid, not the header. On a saved contract, job_price_hdr.customer_id and ship_to_id are NULL; the customers and ship-tos the contract serves are rows in job_price_customer_shipto. A sales order line gets the contract price only when the order's customer and ship-to are a row here — a ship-to missing from the grid prices as if the contract did not exist.

To add one, load the header by job_no + contract_no (header Keys: [], both in Edits, no end_date) and send a CUSTOMER_SHIP_TO.customer_ship_to row keyed on customer_id + ship_to_id:

Runnable: contract_shipto_line_no.py attach-ship-to · ContractShipToLineNo.cs (Recipes menu 23) · payload contract-attach-ship-to.json. Both read the grid and the header back over OData before and after.

{
  "Name": "JobContractPricing", "UseCodeValues": false,
  "Transactions": [{ "Status": "New", "DataElements": [
    { "Name": "FORM.d_dw_job_price_hdr", "Type": "Form", "Keys": [],
      "Rows": [{ "Edits": [
        {"Name": "job_no",      "Value": "1001"},
        {"Name": "contract_no", "Value": "JOB-1001"}
      ], "RelativeDateEdits": [] }] },
    { "Name": "CUSTOMER_SHIP_TO.customer_ship_to", "Type": "List",
      "Keys": ["customer_id", "ship_to_id"],
      "Rows": [{ "Edits": [
        {"Name": "customer_id", "Value": "100198"},
        {"Name": "ship_to_id",  "Value": "100199"}
      ], "RelativeDateEdits": [] }] }
  ]}]
}