Purchase Order API Overview

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:

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:

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 IDTransaction Description
1Line of Credit Change
2Payment Requested
3Payment Collected
4Payment Voided
5Payment Refund
6Manual 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: