{"openapi":"3.1.0","info":{"title":"KSS API","version":"v2","description":"Programmatic access to KSS purchase workflows."},"servers":[{"url":"https://api.kssdata.com/api/v2","description":"Production"},{"url":"https://api.test.kssdata.com/api/v2","description":"Test"}],"tags":[{"name":"Purchases"},{"name":"Purchase Transactions"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"ApiError":{"type":"object","required":["code","detail"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"detail":{"type":"string","description":"Human-readable explanation of the error."},"field_errors":{"type":"array","items":{"$ref":"#/components/schemas/FieldError"}}},"additionalProperties":true},"FieldError":{"type":"object","required":["field","code","detail"],"properties":{"field":{"type":"string"},"code":{"type":"string"},"detail":{"type":"string"},"message":{"type":"string"},"index":{"type":"number"},"product_id":{"type":"number"}},"additionalProperties":true},"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/ApiError"}]}}},"PaginationEnvelope":{"type":"object","required":["data","page","page_size","has_next_page"],"properties":{"data":{"description":"Response payload."},"page":{"type":"number","minimum":1},"page_size":{"type":"number","minimum":1,"maximum":500},"has_next_page":{"type":"boolean"}}},"Purchase":{"type":"object","required":["purchase_id","receive_date","shipment_num","shipment_id","to_location_id","to_location_name","vendor_name","vendor_id","post_date","status","po_num","freight","tax","other_cost","total","total_cases","public_pdf_link","purchase_pdf_url_api_key_id","memo","last_edit_time","last_calc_time","time_updated","invoice_date","due_date","terms","term_id","time_created","purchase_global_id","receiving_num"],"properties":{"purchase_id":{"type":["number","null"],"description":"Numeric ERP purchase ID. Null until an API-originated purchase is synced."},"receive_date":{"type":["string","null"],"format":"date-time"},"shipment_num":{"type":["string","null"]},"shipment_id":{"type":["number","null"]},"to_location_id":{"type":"number"},"to_location_name":{"type":["string","null"]},"vendor_name":{"type":["string","null"]},"vendor_id":{"type":"number"},"post_date":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["New","Accepted","Received","Confirmed","Verified","InProgress","Submitted"]},"po_num":{"type":"string"},"freight":{"type":["string","null"],"description":"Decimal value serialized as a string."},"tax":{"type":["string","null"],"description":"Decimal value serialized as a string."},"other_cost":{"type":["string","null"],"description":"Decimal value serialized as a string."},"total":{"type":["string","null"],"description":"Decimal value serialized as a string."},"total_cases":{"type":["string","null"],"description":"Total case count serialized as a string."},"public_pdf_link":{"type":["string","null"]},"purchase_pdf_url_api_key_id":{"type":["number","null"]},"memo":{"type":["string","null"]},"last_edit_time":{"type":["string","null"],"format":"date-time"},"last_calc_time":{"type":["string","null"],"format":"date-time"},"time_updated":{"type":["string","null"],"format":"date-time"},"invoice_date":{"type":["string","null"],"format":"date-time"},"due_date":{"type":["string","null"],"format":"date-time"},"terms":{"type":["string","null"]},"term_id":{"type":["number","null"]},"time_created":{"type":["string","null"],"format":"date-time"},"purchase_global_id":{"type":["string","null"],"description":"Permanent global purchase identifier."},"receiving_num":{"type":["string","null"]},"purchase_transactions":{"type":"array","description":"Line items are included by default. Send includeTransactions=false on purchases GET endpoints to omit them.","items":{"oneOf":[{"$ref":"#/components/schemas/PurchaseTransaction"},{"$ref":"#/components/schemas/PurchaseDraftTransaction"}]}}},"additionalProperties":false,"example":{"purchase_id":70001,"receive_date":"2026-06-02T06:00:00.000Z","shipment_num":"Example PO 70001","shipment_id":72001,"to_location_id":40001,"to_location_name":"Alameda","vendor_name":"EXAMPLE DISTRIBUTORS LLC (Example Location)","vendor_id":50001,"post_date":"2026-06-02T06:00:00.000Z","status":"Verified","po_num":"Example PO 70001","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"35726.38","total_cases":"184.00","public_pdf_link":null,"purchase_pdf_url_api_key_id":94001,"memo":null,"last_edit_time":null,"last_calc_time":"2026-06-04T10:20:14.000Z","time_updated":"2026-08-21T18:06:57.930Z","invoice_date":"2026-06-01T06:00:00.000Z","due_date":"2026-08-30T06:00:00.000Z","terms":"Driver Accounts","term_id":80002,"time_created":"2026-06-15T22:09:09.921Z","purchase_global_id":"00000AAAAAFFFFF00000AAAAAF","receiving_num":null}},"PurchaseResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Purchase"}}},"PaginatedPurchaseResponse":{"allOf":[{"$ref":"#/components/schemas/PaginationEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Purchase"}}}}]},"PurchaseDraftTransaction":{"type":"object","required":["product_id","num_units"],"properties":{"id":{"type":"number"},"product_id":{"type":"number"},"num_units":{"type":"number"},"batch_code":{"type":["string","null"]},"expiration_date":{"type":["string","null"],"format":"date"},"needs_activation":{"type":"boolean"},"activation_task_id":{"type":["number","null"]}},"additionalProperties":false},"PurchaseTransaction":{"type":"object","properties":{"purchase_trans_id":{"type":"number"},"purchase_id":{"type":"number"},"product_id":{"type":"number"},"ordered":{"type":["string","null"],"description":"Decimal value serialized as a string."},"num_units":{"type":["string","null"],"description":"Decimal value serialized as a string."},"fob":{"type":["string","null"],"description":"Decimal value serialized as a string."},"deposit_cost":{"type":["string","null"],"description":"Decimal value serialized as a string."},"ext_price":{"type":["string","null"],"description":"Decimal value serialized as a string."},"expiration_date":{"type":["string","null"],"format":"date-time"},"code_date":{"type":["string","null"],"format":"date-time"},"batch_code":{"type":["string","null"]},"laid_in_cost":{"type":["string","null"],"description":"Decimal value serialized as a string."},"pallet_tag":{"type":["string","null"]},"cases":{"type":["string","null"],"description":"Decimal value serialized as a string."},"weight":{"type":["string","null"],"description":"Decimal value serialized as a string."},"time_updated":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"PaginatedPurchaseTransactionResponse":{"allOf":[{"$ref":"#/components/schemas/PaginationEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseTransaction"}}}}]},"PurchaseWriteTransaction":{"type":"object","required":["product_id"],"properties":{"product_id":{"type":"number","description":"Product to add to the purchase."},"cases":{"type":"number","description":"Case quantity. Send exactly one of Cases or Units."},"units":{"type":"number","description":"Unit quantity. Send exactly one of Cases or Units."},"batch_code":{"type":"string","description":"Batch code. Required when the vendor requires batch codes."},"expiration_date":{"type":"string","format":"date","description":"Expiration date as YYYY-MM-DD."}},"additionalProperties":false},"CreatePurchaseRequest":{"type":"object","required":["vendor_id","to_location_id","supplier_id","delivery_date","po_num"],"properties":{"vendor_id":{"type":"number","description":"The vendor the purchase order is placed with."},"to_location_id":{"type":"number","description":"The location receiving the purchase."},"supplier_id":{"type":"number","description":"The supplier the purchase is for. Must be one of your authorized suppliers."},"supplier_name":{"type":"string","description":"Supplier name used in the purchase memo. Falls back to the vendor's name when omitted."},"delivery_date":{"type":"string","format":"date","description":"Requested delivery date as YYYY-MM-DD."},"po_num":{"type":"string","description":"Your purchase order number. Must be unique for the vendor."},"purchase_transactions":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseWriteTransaction"},"maxItems":200},"created_by_user_id":{"type":"number","description":"Honored for Employee keys only; other keys use the key's own user."}},"additionalProperties":false},"UpdatePurchaseRequest":{"type":"object","properties":{"vendor_id":{"type":"number","description":"The vendor the purchase order is placed with."},"to_location_id":{"type":"number","description":"The location receiving the purchase."},"delivery_date":{"type":"string","format":"date","description":"Requested delivery date as YYYY-MM-DD."},"po_num":{"type":"string","description":"Your purchase order number. Must remain unique for the vendor."},"purchase_transactions":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseWriteTransaction"},"maxItems":200,"description":"When present, replaces all line items on the draft purchase."}},"additionalProperties":false},"PurchaseValidationResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["valid","total_cases"],"properties":{"valid":{"type":"boolean"},"total_cases":{"type":"number"}}}}}},"parameters":{"Page":{"name":"page","in":"query","required":false,"description":"Page number to retrieve. Defaults to 1.","schema":{"type":"number","minimum":1,"default":1}},"PageSize":{"name":"page_size","in":"query","required":false,"description":"Number of rows to return per page. Defaults to 50; maximum is 500.","schema":{"type":"number","minimum":1,"maximum":500,"default":50}},"States":{"name":"states","in":"query","required":false,"description":"Comma-separated list of state abbreviations to filter by. Example: \"CA,NJ\".","schema":{"type":"string","pattern":"^[^,]+(,[^,]+)*$","example":"CA,NJ"},"example":"CA,NJ"},"CustomerIDs":{"name":"customer_ids","in":"query","required":false,"description":"Comma-separated list of customer IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},"SupplierIDs":{"name":"supplier_ids","in":"query","required":false,"description":"Comma-separated list of supplier IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},"ProductIDs":{"name":"product_ids","in":"query","required":false,"description":"Comma-separated list of product IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},"LocationIDs":{"name":"location_ids","in":"query","required":false,"description":"Comma-separated list of location IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Optional for POST and PATCH requests. Send a unique key for each logical mutation so an exact retry can replay the original response instead of running the operation again.","schema":{"type":"string"}},"Prefer":{"name":"Prefer","in":"header","required":false,"description":"Use return=minimal to omit the response body; return=representation is the default. Use handling=lenient to ignore unrecognized fields where supported.","schema":{"type":"string"}}},"responses":{"BadRequest":{"description":"The request is missing required input or contains invalid input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"The request is missing a valid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"The API key is not authorized to access this resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"The request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"The request is well-formed but could not be accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PayloadTooLarge":{"description":"The request body is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnsupportedMediaType":{"description":"The request content type is not supported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"TooManyRequests":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"ServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/purchases":{"get":{"tags":["Purchases"],"operationId":"getPurchasesPurchases","description":"Returns purchase orders filtered by purchase ID, vendor, location, status, and date range. purchase_transactions are included by default; send include_transactions=false to return headers only. Omitting statuses returns everything: purchases the ERP has posted, and the purchase orders originated here (including drafts that have not been submitted yet). Filtering statuses to InProgress and/or Submitted returns only the purchase orders originated here; filtering to other statuses returns only ERP-posted purchases; combining both kinds of status returns both sources merged into one paginated list. Not accessible to Customer API keys.","parameters":[{"name":"purchase_ids","in":"query","required":false,"description":"Comma-separated list of purchase identifiers to filter by. Each value may be a numeric ERP purchase_id or a purchase_global_id.","schema":{"type":"string","pattern":"^([1-9]\\d*|[0-9A-HJKMNP-TV-Z]{26})(,([1-9]\\d*|[0-9A-HJKMNP-TV-Z]{26}))*$","example":"70002,11111BBBBBEEEEE11111BBBBBE"},"example":"70002,11111BBBBBEEEEE11111BBBBBE"},{"name":"vendor_ids","in":"query","required":false,"description":"Comma-separated list of vendor IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},{"name":"location_ids","in":"query","required":false,"description":"Comma-separated list of destination location IDs to filter by.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},{"name":"statuses","in":"query","required":false,"description":"Comma-separated list of purchase statuses to filter by. Omitted, returns purchase orders from every status and both sources. InProgress and Submitted select the purchase orders originated here; other statuses select ERP-posted purchases; combining both kinds returns both sources merged into one list.","schema":{"type":"string","pattern":"^[^,]+(,[^,]+)*$","example":"Verified,Received"},"example":"Verified,Received"},{"name":"start_date","in":"query","required":false,"description":"ISO 8601 date string. Returns posted purchases with a post_date on or after this date, and API-originated drafts with a delivery_date on or after this date.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"ISO 8601 date string. Returns posted purchases with a post_date on or before this date, and API-originated drafts with a delivery_date on or before this date.","schema":{"type":"string","format":"date"}},{"name":"include_transactions","in":"query","required":false,"description":"Line items are included by default. Send false to omit purchase_transactions from each purchase.","schema":{"type":"boolean","default":true}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPurchaseResponse"},"example":{"data":[{"purchase_id":70001,"receive_date":"2026-06-02T06:00:00.000Z","shipment_num":"Example PO 70001","shipment_id":72001,"to_location_id":40001,"to_location_name":"Alameda","vendor_name":"EXAMPLE DISTRIBUTORS LLC (Example Location)","vendor_id":50001,"post_date":"2026-06-02T06:00:00.000Z","status":"Verified","po_num":"Example PO 70001","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"35726.38","total_cases":"184.00","public_pdf_link":null,"purchase_pdf_url_api_key_id":94001,"memo":null,"last_edit_time":null,"last_calc_time":"2026-06-04T10:20:14.000Z","time_updated":"2026-08-21T18:06:57.930Z","invoice_date":"2026-06-01T06:00:00.000Z","due_date":"2026-08-30T06:00:00.000Z","terms":"Driver Accounts","term_id":80002,"time_created":"2026-06-15T22:09:09.921Z","purchase_global_id":"00000AAAAAFFFFF00000AAAAAF","receiving_num":null,"purchase_transactions":[{"purchase_trans_id":71001,"purchase_id":70001,"product_id":30006,"ordered":"10","num_units":"120","fob":"12.50","deposit_cost":"0.00","ext_price":"1500.00","expiration_date":"2026-01-01T00:00:00.000Z","code_date":"2025-01-15T00:00:00.000Z","batch_code":"BCH-001","laid_in_cost":"13.00","pallet_tag":null,"cases":"10","weight":"120.00","time_updated":"2025-03-02T10:00:00.000Z"}]},{"purchase_id":null,"receive_date":null,"shipment_num":null,"shipment_id":null,"to_location_id":40002,"to_location_name":null,"vendor_name":null,"vendor_id":50002,"post_date":null,"status":"InProgress","po_num":"PO-2026-00000","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"0.00","total_cases":"30","public_pdf_link":null,"purchase_pdf_url_api_key_id":null,"memo":"Acme Brands - Submitted via KSS Live by Jamie Example","last_edit_time":null,"last_calc_time":null,"time_updated":"2026-08-13T15:04:05.000Z","invoice_date":null,"due_date":null,"terms":null,"term_id":null,"time_created":"2026-08-13T15:04:05.000Z","purchase_global_id":"11111BBBBBEEEEE11111BBBBBE","receiving_num":null,"purchase_transactions":[{"id":71101,"product_id":30008,"num_units":288,"batch_code":"B-1042","expiration_date":"2027-01-15","needs_activation":false,"activation_task_id":null}]}],"page":1,"page_size":50,"has_next_page":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":true,"x-kss-beta":true,"summary":"Returns purchase orders filtered by purchase ID, vendor, location, status, and date range."},"post":{"tags":["Purchases"],"operationId":"createPurchase","description":"Creates a purchase order. By default the purchase is created as an editable draft; pass submit=true as a query parameter to create and submit it in a single call. The response carries the new purchase's global ID, and a Location header pointing at the purchase, which is how you address it for later reads, edits, and submission. Not accessible to Customer API keys.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/Prefer"},{"name":"submit","in":"query","required":false,"description":"When true, creates the purchase directly in Submitted status after validating it is ready to submit.","schema":{"type":"boolean","default":false}}],"responses":{"201":{"description":"Created. If Prefer: return=minimal is sent, the Location header is returned with no response body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"},"example":{"data":{"purchase_id":null,"receive_date":null,"shipment_num":null,"shipment_id":null,"to_location_id":40002,"to_location_name":null,"vendor_name":null,"vendor_id":50002,"post_date":null,"status":"InProgress","po_num":"PO-2026-00000","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"0.00","total_cases":"30","public_pdf_link":null,"purchase_pdf_url_api_key_id":null,"memo":"Acme Brands - Submitted via KSS Live by Jamie Example","last_edit_time":null,"last_calc_time":null,"time_updated":"2026-08-13T15:04:05.000Z","invoice_date":null,"due_date":null,"terms":null,"term_id":null,"time_created":"2026-08-13T15:04:05.000Z","purchase_global_id":"11111BBBBBEEEEE11111BBBBBE","receiving_num":null}}}},"headers":{"Location":{"description":"Canonical URL for the created purchase, addressed by purchase_global_id.","schema":{"type":"string"}},"Idempotency-Replayed":{"description":"true when this response was replayed from a previous request with the same Idempotency-Key.","schema":{"type":"string"}},"Preference-Applied":{"description":"Echoes honored Prefer tokens, such as return=minimal or handling=lenient.","schema":{"type":"string"}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"VALIDATION_FAILED","detail":"PurchaseTransactions[0].ProductID is required.","field_errors":[{"field":"purchase_transactions[0].product_id","message":"ProductID is required."}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The request conflicts with an existing purchase or idempotency key.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"DUPLICATE_PO_NUMBER","detail":"PONum PO-2026-00000 already exists for vendor 50002 on purchase 11111BBBBBEEEEE11111BBBBBE."}}}}},"413":{"description":"The purchase body is too large.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"REQUEST_TOO_LARGE","detail":"The request body exceeds the maximum size for a purchase. A purchase may contain at most 200 line items."}}}}},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseRequest"},"example":{"vendor_id":50002,"to_location_id":40002,"supplier_id":20001,"supplier_name":"Acme Brands","delivery_date":"2026-08-20","po_num":"PO-2026-00000","purchase_transactions":[{"product_id":30008,"cases":12,"batch_code":"B-1042","expiration_date":"2027-01-15"},{"product_id":30009,"units":48}]}}}},"x-kss-callout":"po_num must be unique for the vendor, and that is what makes a retry safe: if a request times out after the purchase was already created, sending it again with the same po_num returns 409 DUPLICATE_PO_NUMBER instead of creating a second purchase order. The error's detail names the existing purchase's global ID, so you can go read it directly rather than searching for it.","x-kss-fieldDefinitions":[{"name":"purchase_global_id","description":"The purchase's permanent identifier. Use it to read, edit, submit, or delete the purchase."},{"name":"purchase_id","description":"The numeric ERP purchase ID. Null until a purchase originated here has synced into the ERP."},{"name":"status","description":"InProgress for an editable draft, Submitted once it has been handed off for import."},{"name":"total_cases","description":"Total case count across all line items."}],"summary":"Creates a purchase order."}},"/purchases/validate":{"post":{"tags":["Purchases"],"operationId":"validatePurchase","description":"Validates a purchase order without creating anything, returning whether it is acceptable and its computed totals. Validates against the rules that apply at submit time: the purchase must have at least one line item, every quantity must be positive, and batch codes must be present where the vendor requires them, po_num must be unique for the vendor. Not accessible to Customer API keys.","parameters":[{"$ref":"#/components/parameters/Prefer"}],"responses":{"200":{"description":"Validation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseValidationResponse"},"example":{"data":{"valid":true,"total_cases":30}}}}},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"VALIDATION_FAILED","detail":"PurchaseTransactions[0].ProductID is required.","field_errors":[{"field":"purchase_transactions[0].product_id","message":"ProductID is required."}]}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The purchase conflicts with an existing purchase.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"DUPLICATE_PO_NUMBER","detail":"PONum PO-2026-00000 already exists for vendor 50002 on purchase 11111BBBBBEEEEE11111BBBBBE."}}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseRequest"},"example":{"vendor_id":50002,"to_location_id":40002,"supplier_id":20001,"supplier_name":"Acme Brands","delivery_date":"2026-08-20","po_num":"PO-2026-00000","purchase_transactions":[{"product_id":30008,"cases":12,"batch_code":"B-1042","expiration_date":"2027-01-15"},{"product_id":30009,"units":48}]}}}},"x-kss-fieldDefinitions":[{"name":"valid","description":"True when the purchase passed every validation check."},{"name":"total_cases","description":"Total case count derived across all line items."}],"summary":"Validates a purchase order without creating anything, returning whether it is acceptabl..."}},"/purchases/{purchaseID}":{"get":{"tags":["Purchases"],"operationId":"getPurchasesPurchasesPurchaseID","description":"Returns a single purchase order. purchase_transactions are included by default; send include_transactions=false to return the purchase header only. Accepts either the purchase's global ID or its numeric ERP purchase ID, and resolves a purchase order originated here as readily as one the ERP has posted. A global ID resolves for the whole life of the purchase: while it is still a draft that has not reached the ERP, and afterwards once the ERP has posted it, so the URL returned when a purchase is created never stops working. The numeric ERP purchase ID resolves the ERP-posted purchase, and also resolves a purchase order originated here once it carries that ID.","parameters":[{"name":"purchaseID","in":"path","required":true,"description":"The purchase's global ID or its numeric ERP purchase ID. Either resolves a purchase order originated here as well as one the ERP has posted.","schema":{"type":"string"}},{"name":"include_transactions","in":"query","required":false,"description":"Line items are included by default. Send false to omit purchase_transactions.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"},"example":{"data":{"purchase_id":70001,"receive_date":"2026-06-02T06:00:00.000Z","shipment_num":"Example PO 70001","shipment_id":72001,"to_location_id":40001,"to_location_name":"Alameda","vendor_name":"EXAMPLE DISTRIBUTORS LLC (Example Location)","vendor_id":50001,"post_date":"2026-06-02T06:00:00.000Z","status":"Verified","po_num":"Example PO 70001","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"35726.38","total_cases":"184.00","public_pdf_link":null,"purchase_pdf_url_api_key_id":94001,"memo":null,"last_edit_time":null,"last_calc_time":"2026-06-04T10:20:14.000Z","time_updated":"2026-08-21T18:06:57.930Z","invoice_date":"2026-06-01T06:00:00.000Z","due_date":"2026-08-30T06:00:00.000Z","terms":"Driver Accounts","term_id":80002,"time_created":"2026-06-15T22:09:09.921Z","purchase_global_id":"00000AAAAAFFFFF00000AAAAAF","receiving_num":null,"purchase_transactions":[{"purchase_trans_id":71001,"purchase_id":70001,"product_id":30006,"ordered":"10","num_units":"120","fob":"12.50","deposit_cost":"0.00","ext_price":"1500.00","expiration_date":"2026-01-01T00:00:00.000Z","code_date":"2025-01-15T00:00:00.000Z","batch_code":"BCH-001","laid_in_cost":"13.00","pallet_tag":null,"cases":"10","weight":"120.00","time_updated":"2025-03-02T10:00:00.000Z"}]}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"summary":"Returns a single purchase order."}},"/purchases/{purchaseGlobalID}":{"patch":{"tags":["Purchases"],"operationId":"updatePurchase","description":"Updates a draft purchase order. Send only the fields you want to change; anything you omit is left as it is. Only drafts can be edited: a purchase that has already been submitted returns 409. Not accessible to Customer API keys.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"purchaseGlobalID","in":"path","required":true,"description":"The global ID of the draft purchase to update.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Prefer"}],"responses":{"200":{"description":"Updated draft purchase with the updated representation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"},"example":{"data":{"purchase_id":null,"receive_date":null,"shipment_num":null,"shipment_id":null,"to_location_id":40002,"to_location_name":null,"vendor_name":null,"vendor_id":50002,"post_date":null,"status":"InProgress","po_num":"PO-2026-00000-REV2","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"0.00","total_cases":"45","public_pdf_link":null,"purchase_pdf_url_api_key_id":null,"memo":"Acme Brands - Submitted via KSS Live by Jamie Example","last_edit_time":null,"last_calc_time":null,"time_updated":"2026-08-13T16:20:11.000Z","invoice_date":null,"due_date":null,"terms":null,"term_id":null,"time_created":"2026-08-13T15:04:05.000Z","purchase_global_id":"11111BBBBBEEEEE11111BBBBBE","receiving_num":null}}}},"headers":{"Idempotency-Replayed":{"description":"true when this response was replayed from a previous request with the same Idempotency-Key.","schema":{"type":"string"}},"Preference-Applied":{"description":"Echoes any honored Prefer tokens, such as return=minimal or handling=lenient.","schema":{"type":"string"}}}},"204":{"description":"Updated draft purchase. Returned when Prefer: return=minimal is sent."},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"VALIDATION_FAILED","detail":"Only one of Cases or Units may be supplied."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Purchase not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_FOUND","detail":"Purchase 11111BBBBBEEEEE11111BBBBBE was not found."}}}}},"409":{"description":"The purchase cannot be edited in its current state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_EDITABLE","detail":"Only draft purchases can be updated."}}}}},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"415":{"description":"Unsupported request content type.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","detail":"PATCH bodies must be application/json."}}}}},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePurchaseRequest"},"example":{"delivery_date":"2026-08-22","po_num":"PO-2026-00000-REV2","purchase_transactions":[{"product_id":30008,"cases":15,"batch_code":"B-1042","expiration_date":"2027-01-15"}]}}}},"x-kss-callout":"Including purchase_transactions replaces every line item on the purchase with the array you send, and an empty array removes them all. Leave the field out entirely to keep the existing line items. Status is never set here, use the submit action instead.","summary":"Updates a draft purchase order."},"delete":{"tags":["Purchases"],"operationId":"deletePurchase","description":"Deletes a draft purchase order. Responds 204 with no body. Only drafts can be deleted: a purchase that has already been submitted returns 409, and a purchase that does not exist or has already been deleted returns 404. Not accessible to Customer API keys.","parameters":[{"name":"purchaseGlobalID","in":"path","required":true,"description":"The global ID of the draft purchase to delete.","schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Purchase not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_FOUND","detail":"Purchase 11111BBBBBEEEEE11111BBBBBE was not found."}}}}},"409":{"description":"The purchase cannot be deleted in its current state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_EDITABLE","detail":"Only draft purchases can be deleted."}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"summary":"Deletes a draft purchase order."}},"/purchases/{purchaseGlobalID}/submit":{"post":{"tags":["Purchases"],"operationId":"submitPurchase","description":"Submits a draft purchase order, handing it off for import. The purchase's own contents are re-checked at this point: it must have at least one line item, every quantity must be positive, and batch codes must be present where the vendor requires them. A purchase that has already been submitted returns 409. A successful submit starts the import to the ERP in the background; the response does not wait for it to finish. Not accessible to Customer API keys.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"name":"purchaseGlobalID","in":"path","required":true,"description":"The global ID of the draft purchase to submit.","schema":{"type":"string"}},{"$ref":"#/components/parameters/Prefer"}],"responses":{"200":{"description":"Submitted purchase with the updated representation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseResponse"},"example":{"data":{"purchase_id":null,"receive_date":null,"shipment_num":null,"shipment_id":null,"to_location_id":40002,"to_location_name":null,"vendor_name":null,"vendor_id":50002,"post_date":null,"status":"Submitted","po_num":"PO-2026-00000","freight":"0.00","tax":"0.00","other_cost":"0.00","total":"0.00","total_cases":"30","public_pdf_link":null,"purchase_pdf_url_api_key_id":null,"memo":"Acme Brands - Submitted via KSS Live by Jamie Example","last_edit_time":null,"last_calc_time":null,"time_updated":"2026-08-13T17:02:44.000Z","invoice_date":null,"due_date":null,"terms":null,"term_id":null,"time_created":"2026-08-13T15:04:05.000Z","purchase_global_id":"11111BBBBBEEEEE11111BBBBBE","receiving_num":null}}}},"headers":{"Idempotency-Replayed":{"description":"true when this response was replayed from a previous request with the same Idempotency-Key.","schema":{"type":"string"}},"Preference-Applied":{"description":"Echoes any honored Prefer tokens, such as return=minimal or handling=lenient.","schema":{"type":"string"}}}},"204":{"description":"Submitted purchase. Returned when Prefer: return=minimal is sent."},"400":{"description":"Validation failed.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"VALIDATION_FAILED","detail":"At least one line item is required before submitting."}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"Purchase not found.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_FOUND","detail":"Purchase 11111BBBBBEEEEE11111BBBBBE was not found."}}}}},"409":{"description":"The purchase cannot be submitted in its current state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"error":{"code":"PURCHASE_NOT_EDITABLE","detail":"Only draft purchases can be submitted."}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":false,"x-kss-beta":true,"summary":"Submits a draft purchase order, handing it off for import."}},"/purchaseTrans":{"get":{"tags":["Purchase Transactions"],"operationId":"getPurchaseTrans","description":"Returns purchase order line items for one or more purchases. purchase_ids is required. Not accessible to Customer API keys.","parameters":[{"name":"purchase_ids","in":"query","required":true,"description":"Comma-separated list of purchase IDs to retrieve line items for.","schema":{"type":"string","pattern":"^\\d+(,\\d+)*$","example":"1,2,3"},"example":"1,2,3"},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PageSize"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPurchaseTransactionResponse"},"example":{"data":[{"purchase_trans_id":71001,"purchase_id":70002,"product_id":30006,"ordered":"10","num_units":"120","fob":"12.50","deposit_cost":"0.00","ext_price":"1500.00","expiration_date":"2026-01-01T00:00:00.000Z","code_date":"2025-01-15T00:00:00.000Z","batch_code":"BCH-001","laid_in_cost":"13.00","pallet_tag":null,"cases":"10","weight":"120.00","time_updated":"2025-03-02T10:00:00.000Z"}],"page":1,"page_size":50,"has_next_page":false}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/ServerError"}},"x-kss-auth":{"supplierRestricted":false,"customerRestricted":true},"x-kss-pagination":true,"x-kss-beta":true,"summary":"Returns purchase order line items for one or more purchases."}}}}