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.

DataElement Fields

Row / Edit Fields

Each Edit object supports:

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 it, 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 undocumented. Verified/inferred mapping from the definition's display list plus live data:

Only R (Requisition) is verified end-to-end; the rest are inferred from the display-name order and live data — treat them as strong hints, not confirmed. Environment: 26.1.5894.1 (play), July 2026.

Response Format

Success Response

{
    "Messages": ["Transaction 1:: "],
    "Results": {
        "Name": "Order",
        "Transactions": [
            {
                "DataElements": [
                    {
                        "Name": "TABPAGE_1.order",
                        "Rows": [{
                            "Edits": [
                                {"Name": "order_no", "Value": "1013938"}
                            ]
                        }]
                    }
                ],
                "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 writes are atomic as the table above shows, so this is specific to services that cascade.)

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.

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.

What makes a column disabled for a user: DynaChange data-change rules scoped to a role, Application Security settings, and window-level permissions — the same machinery documented under DynaChange and Popup Handling and Application Security settings. The API surfaces all of it as one undifferentiated message.

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 and on Order's LINE_NOTE.line_note — three unrelated surfaces, marking 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://your-server.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.)

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.p21server.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.p21server.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.p21server.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.p21server.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):

• 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 realistic header sets customer_id, sales_loc_id, source_loc_id, order_date, requested_date, po_no, taker, ship_to_id, and contact_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 cannot be entered via the Transaction API when they should explode or spawn a production order — the "add as assembly?" prompt is auto-answered No, killing the explode. Use the Interactive API for those lines: see Sales Order Entry with Assembly Lines.
• 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.

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)

Line Items -- JOBPRICELINE.jobpriceline (List, 29 fields)

pricing_method valid values:

Non-break vs break lines:

• Non-break (fixed price): Set pricing_method to "Price" and price to the value. Do NOT send source_price or multiplier.
• Break (quantity-based): Set pricing_method to "Source", source_price to "Supplier List Price" (or other source), and multiplier to 1 (or desired multiplier). Do NOT send price.

Values/Breaks -- VALUES.values (Form, 46 fields)

The VALUES DataElement defines quantity break tiers for a line item.

Stop before you build a payload around this element. On P21 26.1 every attempt to write VALUES.values through the Transaction API is refused, and IgnoreDisabled: true turns that refusal into a silent no-op. Read VALUES Writes Are Refused on 26.1 first — the field reference below is accurate, but the write path is not currently usable.

calculation_method_cd valid values: Difference, Multiplier, Mark up, Percentage, Fixed Price

Every tier field is numbered from 1. There is no unsuffixed calculation_value or other_cost — the first tier is calculation_value1 / other_cost1. Verified against definitions/JobContractPricing.json (both FieldDefinitions and the payload Template) and the live GET /api/v2/definition/JobContractPricing. The element also has no per-tier uom field — that is SalesPricePage, not this service.

Break Tier Structure

The service supports 15 price levels: 14 break thresholds (break1-break14) plus one catch-all tier. Break values represent the starting quantity of the next tier (advance thresholds).

Rules: - break1 should NOT be 0 -- it defines where the second tier starts - The last active tier has its break set to 0, signaling no further advance - calculation_value1 is the first tier; calculation_value2 through calculation_value14 are tiers 2-14; calculation_value15 is the 15th tier, which has no break threshold (there is no break15)

Example -- 3 tiers with Fixed Price method:

Tier 1 applies for quantities 1-9 (below break1=10). Tier 2 applies for 10-49 (below break2=50). Tier 3 applies for 50+ (break3=0 means no further advance).

Multi-Line Break Interleaving

VALUES is Type: Form (single row), so it applies to the current JOBPRICELINE cursor position. For contracts with multiple break lines, you must send a SEPARATE JOBPRICELINE DataElement (1 row) followed by its own VALUES DataElement for each line. Putting all lines in a single multi-row JOBPRICELINE causes only the last line to receive breaks.

Correct interleaving:

DataElements:
  1. FORM.d_dw_job_price_hdr (header)
  2. JOBPRICELINE.jobpriceline (Line A -- 1 row)
  3. VALUES.values (breaks for Line A)
  4. JOBPRICELINE.jobpriceline (Line B -- 1 row)
  5. VALUES.values (breaks for Line B)

Incorrect (only Line B gets breaks):

DataElements:
  1. FORM.d_dw_job_price_hdr (header)
  2. JOBPRICELINE.jobpriceline (Lines A and B -- 2 rows)
  3. VALUES.values (breaks -- applies only to last row)

VALUES Writes Are Refused on 26.1

Warning -- verified live on a P21 26.1 tenant, 2026-08-11. Every write path to VALUES.values is refused by the server, and IgnoreDisabled: true converts the refusal into a silent no-op that reports success. The break-tier documentation above describes the element's real schema; it does not currently describe a working write.

All three paths fail with the same error:

General Exception: Tab page is disabled and cannot be selected

which also surfaces per-element as:

VALUES.values: Error processing data element: values : Tab page is disabled and cannot be selected

The control, so you can size the damage. The identical create transaction with the VALUES.values DataElement removed succeeds: Summary: {"Succeeded": 1}, the contract is created, the Source-priced line is created, both confirmed by read-back. Contract and line creation through the Transaction API work fine. It is specifically the VALUES.values DataElement that is refused.

Other things checked, all on the same tenant:

• Resending the line's pricing_method / source_price / multiplier in the same transaction — an attempt to make the window "select" the tab the way a user would — does not help. Identical failure.
• Both calculation_value and calculation_value1 fail identically, so this is not a field-naming problem. (calculation_value1 is nonetheless the correct name — see above.)
• IgnoreDisabled: true at payload top level makes it worse. The response flips to Summary: {"Failed": 0, "Succeeded": 1} with Status: "Passed" — and nothing is written. Read-back shows the row unchanged (an existing tier value of 42.50 survived a "Passed" response) or still absent. The echoed response also silently drops the JOBPRICELINE and VALUES DataElements, echoing only the header, so even the echo does not reveal the omission.

Whether this is a 26.1 regression or long-standing behavior is unknown — no earlier build was available to compare against. Do not read it as a regression; read it as the behavior of the build in front of you, and re-test on yours.

Takeaway beyond this element: IgnoreDisabled: true is not a universal unlock. It genuinely unlocks some disabled columns and tabs (see IgnoreDisabled), but on this path it only converts a loud failure into a quiet one. Always read back after a write that used it — via POST /api/v2/transaction/get or OData — rather than trusting Succeeded.

Commission Costs

The JOBPRICECOST DataElement includes commission_cost_value and related commission fields. These columns are disabled by default -- without special handling the API returns "Column is disabled: commission_cost_value".

They are writable with IgnoreDisabled: true at the payload top level (see IgnoreDisabled). Key the element by item_id and set the cost type before the value -- verified live, including in the same transaction as a line insert:

Payload shape only -- drop this DataElement into a full program. Full runnable version: Updating an Existing Contract.

{
    "Name": "JOBPRICECOST.jobpricecost",
    "Type": "Form",
    "Keys": ["item_id"],
    "Rows": [{
        "Edits": [
            {"Name": "item_id", "Value": "WIDGET-001"},
            {"Name": "commission_cost_type_cd", "Value": "Value"},
            {"Name": "commission_cost_value", "Value": "17.19"}
        ]
    }]
}

commission_cost_type_cd accepts the display labels Order, Source, Value, None (with UseCodeValues: false). Setting only the commission cost leaves the element's other_cost_* fields (other_cost_type_cd, other_cost_value, other_cost_source_cd, other_cost_calc_method_cd, other_cost_calc_value) untouched.

Credit: Alex Westemeier verified the IgnoreDisabled commission-cost write path. The Interactive API (JobContractPricing window) remains an alternative.

Updating an Existing Contract

Use Status = "New" to update existing contracts -- there is no separate "Update" or "Existing" status. The Transaction API distinguishes create from update by whether the FORM key fields land on an existing record:

• Leave the FORM Keys array empty.
• Send the FORM key fields (company_id, contract_no, job_no) inside Edits.
• Also include end_date in Edits -- the API validates required fields on every submit and rejects with "Required value missing for End Date" if it's absent.
• On JOBPRICELINE, set Keys: ["item_id"] and put the item_id value in Edits alongside the fields you're changing.

Empirically verified 2026-05-14: 173 successful price updates against contract JOB-1001 on a production tenant. Each call returned HTTP 200 with Summary.Succeeded = 1, and OData confirmed each job_price_line.price matched the submitted value.

Example -- update one line's price:

"""Update one line's price on an existing job contract, then read it back."""
import re

import httpx

# ---- EDIT THESE -----------------------------------------------------------
BASE_URL = "https://play.p21server.com"   # your P21 server
USERNAME = "apiuser"
PASSWORD = "your-password"
VERIFY_SSL = False                        # True once you trust the cert chain
COMPANY_ID = "ACME"                       # FORM key fields go in Edits, not Keys
CONTRACT_NO = "JOB-1001"
JOB_NO = "31"                             # unique per header; survives renewals
END_DATE = "2030-01-01"                   # must be >= today -- validated every save
ITEM_ID = "WIDGET-001"                    # the line to update
UOM = "EA"
PRICE = "36.58"
# ---------------------------------------------------------------------------


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": "JobContractPricing",
        "UseCodeValues": False,
        "Transactions": [{
            "Status": "New",                          # still "New" for updates
            "DataElements": [
                {
                    "Name": "FORM.d_dw_job_price_hdr",
                    "Type": "Form",
                    "Keys": [],                       # empty
                    "Rows": [{
                        "Edits": [
                            {"Name": "company_id",  "Value": COMPANY_ID},
                            {"Name": "contract_no", "Value": CONTRACT_NO},
                            {"Name": "job_no",      "Value": JOB_NO},
                            {"Name": "end_date",    "Value": END_DATE},
                        ],
                        "RelativeDateEdits": [],
                    }],
                },
                {
                    "Name": "JOBPRICELINE.jobpriceline",
                    "Type": "List",
                    "Keys": ["item_id"],
                    "Rows": [{
                        "Edits": [
                            # pricing_method BEFORE price -- reversing them zeroes the price
                            {"Name": "item_id",        "Value": ITEM_ID},
                            {"Name": "uom",            "Value": UOM},
                            {"Name": "pricing_method", "Value": "Price"},
                            {"Name": "price",          "Value": PRICE},
                        ],
                        "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 price landed -------------------------
    read_back = client.post(
        f"{ui_server}/api/v2/transaction/get",
        headers=headers,
        json={
            "ServiceName": "JobContractPricing",
            "TransactionStates": [
                {
                    "DataElementName": "FORM.d_dw_job_price_hdr",
                    "Keys": [{"Name": "contract_no", "Value": CONTRACT_NO}],
                },
                {"DataElementName": "JOBPRICELINE.jobpriceline", "Keys": []},
            ],
        },
    )
    read_back.raise_for_status()

    wanted = {"contract_no", "job_no", "item_id", "pricing_method", "price"}
    for name, value in walk(read_back.json()):
        if name in wanted:
            print(f"  {name} = {value}")