Pleaxy

Raise purchase orders, approve and pay invoices, and set up your workspace.

API reference

Order fulfillment

Suppliers confirm orders and announce shipments; buyers see both on the order.

More about this resource

What a supplier says about an order after it is issued: whether it accepts it, when it will arrive, and what it has shipped. A supplier's ERP sends the same as cXML: post a ConfirmationRequest or ShipNoticeRequest (cXML 1.2.071 Fulfill DTD) to /v1/cxml/fulfillment with the API key in X-Api-Key or as the Sender's SharedSecret, and a To credential with domain PleaxyWorkspaceID naming the buyer; the answer is a cXML Status, and a resent payloadID changes nothing. Suppliers without either can answer by email: every order emailed to a supplier has its own address (ListPurchaseOrderEmails), where a reply or a cXML document is kept on the order. Nothing here changes the order: a refused order is the buyer's to cancel, and a shipment is never a receipt. The buyer's requester and receiver are notified, and the buyer's sync feed and webhooks get purchase_order.confirmed and purchase_order.shipped.

Endpoints

Get purchase order fulfillment

Returns the supplier's confirmations and shipments for an order.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • buyerstring

    Supplier callers: the buyer's Workspace ID, when two buyers issued the same id.

Returns

200 OK with the object shown in the response.

More details

What the supplier said about an order: its latest confirmation (outcome accepted, backordered, changed, partial or rejected, line by line, with the buyer's decision on changes), the earlier ones, and its shipments (planned, shipped or canceled, with carrier and tracking). Each shipment lists the approved goods receipts entered against it. shippedByLine adds up the shipped quantities; expectedDeliveryDate is the latest delivery date the supplier gave. A supplier whose buyers share a PO id adds ?buyer=<buyer Workspace ID>.

Response fields

  • confirmationOrderConfirmation

    The latest confirmation, absent until the supplier answers. Its outcome is the order's.

  • shippedByLineArray

    Per line, the quantity in shipped shipments. Planned and canceled ones aren't counted.

Errors

  • 404 Not Found - No purchase order with this id is yours.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/fulfillment" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "confirmation": OrderConfirmation,
   "confirmations": [
      {
         "id": "string",
         "poId": "string",
         "outcome": "accepted" | "backordered" | "changed" | "partial" | "rejected",
         "confirmId": "string",
         "deliveryDate": "YYYY-MM-DD",
         "note": "string",
         "lines": [ { "lineNo": number, "status": "accept" | "backordered" | "change" | "reject", "qty": number, "unitPrice": number, "substitute": { "supplierPartId": "string", "name": "string", "catalogItemId": "string" }, "shipmentDate": "YYYY-MM-DD", "deliveryDate": "YYYY-MM-DD", "reason": "string" } ],
         "decision": { "decision": "applied" | "declined", "at": "string", "version": number, "reason": "string" },
         "source": "portal" | "api" | "cxml",
         "createdAt": "string"
      }
   ],
   "shipNotices": [
      {
         "shipmentId": "string",
         "status": "planned" | "shipped" | "canceled",
         "shipmentDate": "YYYY-MM-DD",
         "deliveryDate": "YYYY-MM-DD",
         "carrier": "string",
         "trackingNumber": "string",
         "trackingUrl": "string",
         "lines": [ { "lineNo": number, "qty": number } ],
         "source": "portal" | "api" | "cxml",
         "createdAt": "string",
         "updatedAt": "string",
         "receipts": [ { "id": "string", "receivedAt": "YYYY-MM-DD" } ]
      }
   ],
   "shippedByLine": [ { "lineNo": number, "qty": number } ],
   "expectedDeliveryDate": "YYYY-MM-DD"
}

Apply confirmation changes

Takes the supplier's changed quantities and prices into the order.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • confirmationIdstringRequired

    The confirmation's id, from GetPurchaseOrderFulfillment.

Returns

200 OK with the object shown in the response.

More details

Applies the changes in the supplier's latest confirmation (outcome changed) to the order's lines. It is an ordinary line edit, as UpdatePurchaseOrder makes: the order gets a new version, goes back to approval when its rules say so, and the supplier hears po_changed. Answers { purchaseOrder, confirmation } with the decision applied and the order version it became.

Errors

  • 404 Not Found - No such order, or code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED (the supplier confirmed again since), CONFIRMATION_DECIDED (already applied or declined), NO_CHANGES, or ORDER_NOT_OPEN.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/apply" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "purchaseOrder": PurchaseOrder,
   "confirmation": OrderConfirmation
}

Decline confirmation changes

Keeps the order as it is instead of the supplier's changes.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • confirmationIdstringRequired

    The confirmation's id, from GetPurchaseOrderFulfillment.

Body

  • reasonstring

    Why, up to 500 characters. The supplier sees it.

Returns

200 OK with the object shown in the response.

More details

Declines the changes in the supplier's latest confirmation. The order doesn't change; the supplier is told, with your reason when you give one. Answers the confirmation with its decision.

Errors

  • 404 Not Found - No such order, or code CONFIRMATION_NOT_FOUND.
  • 409 Conflict - Code CONFIRMATION_SUPERSEDED, CONFIRMATION_DECIDED or NO_CHANGES.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/confirmations/{confirmationId}/decline" \
  -H "X-Api-Key: $PLEAXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
body.json
{
   "reason": "string"
}
Response · 200 OK
OrderConfirmation

List purchase order emails

Returns an order's own email address and the emails that reached it.

GET/v1/workspaces/{regionId}/purchase-orders/{poId}/emails

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • buyerstring

    Suppliers: the buyer's Workspace ID, when two buyers issued the same id.

Returns

200 OK with the object shown in the response.

More details

Every order emailed to its supplier gets its own address, a second Reply-To on the order email and printed on the PDF. A supplier's reply, or a cXML ConfirmationRequest or ShipNoticeRequest its system sends there, is kept on the order, newest first. A cXML document from a verified sender (the supplier's contact or its company domain, checked with SPF, DKIM and DMARC) is recorded at once (outcome applied). A plain email is read by the Pleaxy Assistant into a draft confirmation or ship notice, and a document from a sender Pleaxy can't verify is held: both wait for someone to record them with RecordPurchaseOrderEmail. address is absent until the order is issued.

Errors

  • 404 Not Found - No such purchase order.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
GET /v1/workspaces/{regionId}/purchase-orders/{poId}/emails
Request
curl "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
{
   "address": "string",
   "emails": [
      {
         "id": "string",
         "from": "string",
         "subject": "string",
         "receivedAt": "string",
         "trust": "verified" | "unverified",
         "kind": "cxml" | "text",
         "outcome": "applied" | "draft" | "held" | "noAction" | "test" | "failed" | "ignored",
         "reasonCode": "string",
         "summary": "string",
         "text": "string",
         "attachments": [ { "name": "string", "contentType": "string", "size": number } ],
         "draft": { "kind": "confirmation" | "shipNotice", "summary": "string", "confirmation": object, "shipNotice": object },
         "result": { "confirmationId": "string", "shipmentId": "string" },
         "decision": { "action": "recorded" | "dismissed", "by": "string", "at": "string" }
      }
   ]
}

Record purchase order email

Records an email's draft as the supplier's confirmation or ship notice.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • emailIdstringRequired

    The email's id, from ListPurchaseOrderEmails.

Returns

200 OK with the object shown in the response.

More details

Records the draft of an email with outcome draft or held as the supplier's order confirmation or ship notice, from email, with the same checks as ConfirmPurchaseOrder and SendShipNotice. Answers the email with its decision. A buyer needs to be able to edit purchase orders.

Errors

  • 400 Bad Request - The draft names an unknown line, or a line that can't ship.
  • 404 Not Found - No such order or email.
  • 409 Conflict - Code EMAIL_DECIDED (already recorded or dismissed), NOTHING_TO_RECORD, or ORDER_NOT_OPEN.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/record" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
InboundEmail

Dismiss purchase order email

Leaves the order as it is instead of recording what an email asks.

POST/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss

Parameters

  • poIdstringRequired

    The purchase order identifier.

  • emailIdstringRequired

    The email's id, from ListPurchaseOrderEmails.

Returns

200 OK with the object shown in the response.

More details

Marks an email as dismissed: nothing is recorded. Answers the email with its decision.

Errors

  • 404 Not Found - No such order or email.
  • 409 Conflict - Code EMAIL_DECIDED: already recorded or dismissed.
  • 401 Unauthorized - No credential was presented, or the Bearer token / X-Api-Key value is missing, invalid, expired, or revoked.
  • 403 Forbidden - The caller's Bearer token or API key doesn't grant access to this workspace (regionId), or lacks the required role.
POST /v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss
Request
curl -X POST "$PLEAXY_API_BASE_URL/v1/workspaces/{regionId}/purchase-orders/{poId}/emails/{emailId}/dismiss" \
  -H "X-Api-Key: $PLEAXY_API_KEY"
Response · 200 OK
InboundEmail
Talk to us