This topic provide an overview of the purchase order REST API components.
Unified Commerce's purchase order functionality allows your shoppers to use a purchase order as a payment method on your storefront.
Refer to Purchase Orders in the Guides section for more information about purchase orders.
Because a purchase order is a payment method, the actual purchase order payment information is stored on an order's payment information. Purchase orders are also tied to specific customer accounts.
Purchase Order Payment Type Settings
The purchase order payment type settings are controlled at the site payment types level, which you can only interact with using Admin.
To interact with your site payment types, in Admin go to System > Settings > Payment Types.
Purchase Order Payment
You can interact with a purchase order payment and perform payment operations using the order payments resource: commerce/orders/payments.
The following example shows a purchase order payment body schema:
{
"id": "61d8c0542eb84322a65ea61300ea7af4",
"availableActions": [
"AuthorizePayment",
"VoidPayment"
],
"orderId": "0848fa085a573422dc45f0460000437e",
"paymentType": "PurchaseOrder",
"paymentWorkflow": "Mozu",
"billingInfo": {
"paymentType": "PurchaseOrder",
"paymentType": "PurchaseOrder",
"billingContact": {
"email": "johntest@test.com",
"firstName": "John",
"lastNameOrSurname": "Test",
"phoneNumbers": {
"home": "8888888888"
},
"address": {
"address1": "1835 Kramer Ln",
"address2": "",
"address3": "",
"address4": "",
"cityOrTown": "Austin",
"stateOrProvince": "tx",
"postalOrZipCode": "78758",
"countryCode": "US",
"addressType": "Residential",
"isValidated": false
}
},
"isSameBillingShippingAddress": false,
"purchaseOrder": {
"purchaseOrderNumber": "1234",
"paymentTerm": {
"code": "60-days",
"description": "60 days"
},
"customFields": [
{
"code": "Custom-2",
"label": "Custom 2:"
},
{
"code": "Department-Code",
"label": "Depart Code:",
"value": "Dep1"
}
]
},
"auditInfo": {
"updateDate": "2016-05-27T19:13:42.996Z",
"createDate": "2016-05-27T19:12:12.155Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
},
"status": "PaymentRequested",
"interactions": [
{
"id": "9ebc0b959f5f426e9150a61300ea804b",
"paymentId": "61d8c0542eb84322a65ea61300ea7af4",
"orderId": "0848fa085a573422dc45f0460000437e",
"currencyCode": "USD",
"interactionType": "RequestPayment",
"status": "PaymentRequested",
"paymentEntryStatus": "New",
"isRecurring": false,
"isManual": false,
"gatewayResponseText": "Request payment for purchase order. Amount:215.92",
"amount": 215.92,
"interactionDate": "2016-05-27T19:13:47.553Z",
"auditInfo": {
"updateDate": "2016-05-27T19:13:47.553Z",
"createDate": "2016-05-27T19:13:47.553Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}
],
"isRecurring": false,
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 215.92,
"changeMessages": [
{
"id": "ba66ec6dc9354e64a07da61300ea7b00",
"correlationId": "ea3e341c6ab249c9b7342ee70e0844bd",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "mozu",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.1613.4.0.Release",
"subjectType": "StateChange.Payment",
"success": true,
"identifier": "61d8c0542eb84322a65ea61300ea7af4",
"subject": "CreatePayment",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"transactionId": "61d8c0542eb84322a65ea61300ea7af4",
"paymentServiceTransactionId": null,
"paymentType": "PurchaseOrder",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 215.92,
"oldValue": "New",
"newValue": "New"
}
],
"oldValue": "New",
"newValue": "New",
"createDate": "2016-05-27T19:13:43.036Z"
},
{
"id": "75756d79d2cc43688329a61300ea8065",
"correlationId": "e55eb882d7e64175a01d6df678a00c89",
"userId": "355060a60a5e48eeb7f2fb8d92af2ba5",
"userFirstName": "mozu",
"userLastName": "admin",
"userScopeType": "Tenant",
"appId": "2e778ae20c7c433885c8e5e418774cb4",
"appKey": "mozu.MozuAdmin.1613.4.0.Release",
"subjectType": "StateChange.Payment",
"success": true,
"identifier": "61d8c0542eb84322a65ea61300ea7af4",
"subject": "RequestPayment",
"verb": "Applied",
"message": "Workflow action succeeded.",
"metadata": [
{
"transactionId": "61d8c0542eb84322a65ea61300ea7af4",
"paymentServiceTransactionId": null,
"paymentType": "PurchaseOrder",
"amountCollected": 0,
"amountCredited": 0,
"amountRequested": 215.92,
"oldValue": "New",
"newValue": "PaymentRequested"
}
],
"oldValue": "New",
"newValue": "PaymentRequested",
"createDate": "2016-05-27T19:13:47.640Z"
}
],
"auditInfo": {
"updateDate": "2016-05-27T19:13:42.996Z",
"createDate": "2016-05-27T19:13:42.996Z",
"updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
"createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
}
}}Purchase Order Payment Operations
You can perform the following operations on the purchase order payment:
- GET GetPayment
- GET GetPayments
- GET GetAvailablePaymentActions
- POST CreatePaymentAction
- POST PerformPaymentAction
Purchase Order Accounts
Purchase orders are also tied to specific customer accounts. You can enable a customer's account to the ability to use purchase orders, as well as specify their specific credit limit, and payment terms.
You can interact with a customer account's purchase order information using the purchase order account resource: commerce/customer/accounts/purchaseOrder.
The following example shows a customer account's purchase order account body schema:
{
"id": 524,
"accountId": 1001,
"isEnabled": true,
"creditLimit": 10000,
"availableBalance": 9970,
"overdraftAllowance": 10,
"overdraftAllowanceType": "Percent",
"customerPurchaseOrderPaymentTerms": [
{
"siteId": 21377,
"code": "30-days",
"auditInfo": {
"updateDate": "2016-06-01T19:45:22.973Z",
"createDate": "2016-06-01T19:45:22.973Z",
"updateBy": "bla",
"createBy": "bla"
}
}
],
"auditInfo": {
"updateDate": "2016-06-01T22:05:34.957Z",
"createDate": "2016-06-01T19:45:22.970Z",
"updateBy": "88318826167a438ab4bf32679971c561",
"createBy": "bla"
}
}
an>}
}Purchase Order Account Operations
You can perform the following operations on the purchase order account:
- GET GetCustomerPurchaseOrderAccount
- GET GetCustomerPurchaseOrderAccounts
- POST CreateCustomerPurchaseOrderAccount
- PUT UpdateCustomerPurchaseOrderAccount
Purchase Order Transactions
Kibo records each individual transaction that occurs on a customer's purchase order account.
You can either retrieve all transactions that have occurred on a purchase order account, or create a new transaction using the purchase order transaction resource: commerce/customer/accounts/{accountId}/PurchaseOrderTransaction.
Refer to the following table for all the possible purchase order transaction types:
| Type ID | Transaction Description |
|---|---|
| 1 | Line of Credit Change |
| 2 | Payment Requested |
| 3 | Payment Collected |
| 4 | Payment Voided |
| 5 | Payment Refund |
| 6 | Manual Adjustment |
The following example shows a purchase order transaction body schema:
{
"customerPurchaseOrderAccountId": 524,
"siteId": 21377,
"tenantId": 17304,
"transactionDate": "2016-06-06T19:36:28.833Z",
"orderId": "085208165a573408c86d9d4100004398",
"purchaseOrderNumber": "52",
"transactionAmount": -65,
"creditLimit": 10000,
"availableBalance": 9925,
"transactionTypeId": 2,
"transactionDescription": "Payment Requested",
"author": "mozu.CommerceWebApi.1613.4.0.Release"
}Purchase Order Transaction Operations
You can perform the following operations on purchase order transactions: