Orders API Overview

This topic provides an overview of the orders and order drafts REST API components. Refer to Orders in the Guides section for more information about orders, including order attributes, order statuses, and managing orders in the Admin interface.

Orders Resource

You can interact with orders and perform order operations using the orders resource: commerce/orders. There are a number of operations you can perform on orders and order subresources such as order items and order attribute, but key order-level operations include:

Note that there are two similar fields related to credit card numbers in the Create Order API: cardNumberPartOrMask and ccLastFour. Order Management-only configurations store the credit card token in the card number field, which may result in a different set of last four digits than the actual card number. Thus, they should use ccLastFour to record the actual last four digits of the card number so that these digits can be displayed in the order details of the Admin UI - if not provided, Kibo will display the last four digits of the tokenized number.

However, eCommerce and eCommerce+Order Management configurations use the cardNumberPartOrMask field as described in the Create Order API model in which its value is the actual or masked credit card number. Thus, ccLastFour is not required because Kibo will display the last four digits from cardNumberPartOrMask in the Admin UI. However, using either one or both fields is acceptable for validation - if both are provided, then ccLastFour will take priority.

Pricing Field Mappings

Some pricing fields use slightly different names in the Admin UI compared to the Orders API. The following table maps each item-level pricing field in the Admin to its corresponding API property.

Admin Field API Property
Base price of line item Order.items.UnitPrice (listAmount or saleAmount) - Order.items.product.bundledProducts.deltaPrice (The sum of the order price)
Manual adjustment on base price Order.items.UnitPrice.overrideAmount
Extras Order.items.product.bundledProducts.deltaPrice
Quantity Order.items.quantity
Weighted order adjustment Order.item.weightedOrderAdjustment
Weighted order discount Order.item.weightedOrderDiscount. This property only stores the discount's value. Order.orderDiscounts.discount.name stores the discount's name.
Adjusted line item subtotal Order.item.adjustedLineItemSubtotal
Line item tax Order.item.itemTaxTotal or
Order.item.weightedOrderTax
Line item total Order.item.totalWithoutWeightedShippingandHandling
Weighted order shipping fee Order.item.weightedOrderShipping
Weighted order shipping discount Order.item.weightedOrderShippingDiscount
Line item shipping fee Order.item.ShippingAmountBeforeDiscountAndAdjustments
Line item shipping discount Order.item.shippingDiscounts.discount.discount (id, name, and amount)
Shipping tax Order.item.shippingTax
Line item order handling fee Order.item.handlingAmount
Weighted order handling fee Order.item.weightedOrderHandlingFee
Handling tax Order.item.weightedOrderHandlingFeeTax
Weighted order handling discount Order.item.weightedOrderHandlingFeeDiscount
Weighted order duty Order.item.weightedOrderDuty
Line item total w/ shipping and handling Order.item.totalWithWeightedShippingandHandling

The following table maps each order-level pricing field in the Admin to its corresponding API property.

Admin Field API Property
Order adjustments Sum of all manual adjustments + all order discounts. Order discounts is a calculated value of all order level discounts.
Manual adjustment Order.adjustment
Order discounts Order.orderDiscounts (id, name, and amount)
Order subtotal Order.lineItemSubtotalsWithOrderAdjustments
Order shipping fees Order.shippingAmountBeforeDiscountsAndAdjustments
Order shipping discounts Order.shippingDiscounts
Order handling fees Order.handlingSubtotal
Order handling discounts Order.handlingDiscounts
Shipping tax Order.shippingTaxTotal
Handling tax Order.handlingTaxTotal
Order tax Order.itemTaxTotal
Duty Order.dutyTotal
Shipping Sum of order shipping fees + order shipping discounts + line item shipping fees + line item shipping discounts
Handling Sum of order handling fees + order handling discounts + line item handling fees + line item handling discounts
Tax Sum of order tax + shipping tax + handling tax + duty
Order total Order.total

Import Orders for OMS-Only

Order Management-only implementations that do not use Kibo eCommerce need to import orders from their front end. This process uses the Create Order API and requires the following basic information.

  • Email
  • Customer Account ID
  • Import Flag: The isImport flag should be set to "true."
  • Items: Provide as many product details from the API model as possible for the item, including pricing fields. 
  • Fulfillment Info: This contains the fulfillment contact and shipping address of the customer, as well as the shipping method name and code. Supported shipping methods will depend on the configurations you enabled in your shipping settings.
  • Payment Info: Credit card authorization will happen on the external front end, but details will need to be provided via API to perform subsequent operations such as capturing and crediting. It is your responsibility to tokenize the credit card with the gateway provider and send the tokenized card in clear text along with authorization details.
    • Authorization details are located in the interaction object, where the interactionType is "Authorization" and the status is "Authorized." Set the amount requested field to the authorized amount on the payment, and send required gateway information in gatewayResponseData.
    • Fraud check happens on your external front end system. Send the fraud results in the validationResults object, with the status as either "Pass" or "Review." Review will put the order in Pending Review status.
  • Billing Info: This should be populated for both order and payment objects, containing the billing contact, address, and card. The card details should indicate card.isTokenized=true while card.cardNumberPartOrMask will contain the tokenized card number.

This is a complete OMS import order request:

{
  "isTaxExempt": false,
  "email": "example@kibo.net",
  "ipAddress": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "type": "Offline",
  "externalId": "11182019_3",
  "handlingSubTotal": 0,
  "handlingTotal": 0,
  "notes": [],
  "items": [
    {
      "fulfillmentLocationCode": "AUS",
      "fulfillmentMethod": "Pickup",
      "product": {
        "fulfillmentTypesSupported": [
          "DirectShip",
          "InStorePickup"
        ],
        "imageAlternateText": "",
        "imageUrl": "//example.com/exampleImageURL",
        "options": [],
        "properties": [
          {
            "attributeFQN": "tenant~add-shipping",
            "name": "Add Shipping",
            "dataType": "String",
            "isMultiValue": false,
            "values": [
              {
                "stringValue": "3.50",
                "value": "3.50"
              }
            ]
          },
          {
            "attributeFQN": "tenant~free-shipping",
            "name": "Free Shipping",
            "dataType": "Bool",
            "isMultiValue": false,
            "values": [
              {
                "value": false
              }
            ]
          }
        ],
        "categories": [
          {
            "id": 2
          },
          {
            "id": 6,
            "parent": {
              "id": 5
            }
          }
        ],
        "price": {
          "price": 15
        },
        "discountsRestricted": false,
        "isTaxable": true,
        "productType": "Basic Standard",
        "productUsage": "Standard",
        "bundledProducts": [],
        "productCode": "sp_02",
        "name": "Standard Product - 2",
        "description": "Standard Product - 2",
        "goodsType": "Physical",
        "isPackagedStandAlone": false,
        "measurements": {
          "height": {
            "unit": "in",
            "value": 1
          },
          "width": {
            "unit": "in",
            "value": 1
          },
          "length": {
            "unit": "in",
            "value": 1
          },
          "weight": {
            "unit": "lbs",
            "value": 2.5
          }
        }
      },
      "quantity": 2,
      "subtotal": 30,
      "extendedTotal": 30,
      "taxableTotal": 30,
      "discountTotal": 0,
      "discountedTotal": 30,
      "itemTaxTotal": 0,
      "shippingTotal": 0,
      "shippingTaxTotal": 0,
      "handlingAmount": 0,
      "feeTotal": 0,
      "total": 30,
      "unitPrice": {
        "extendedAmount": 15,
        "listAmount": 15
      },
      "productDiscounts": [],
      "shippingDiscounts": [],
      "shippingAmountBeforeDiscountsAndAdjustments": 0,
      "weightedOrderAdjustment": 0,
      "weightedOrderDiscount": 0,
      "adjustedLineItemSubtotal": 30,
      "totalWithoutWeightedShippingAndHandling": 30,
      "weightedOrderTax": 0,
      "weightedOrderShipping": 0,
      "weightedOrderShippingDiscount": 0,
      "weightedOrderShippingManualAdjustment": 0,
      "weightedOrderShippingTax": 0,
      "weightedOrderHandlingFee": 0,
      "weightedOrderHandlingFeeTax": 0,
      "weightedOrderHandlingFeeDiscount": 0,
      "weightedOrderDuty": 0,
      "totalWithWeightedShippingAndHandling": 30,
      "weightedOrderHandlingAdjustment": 0
    },
    {
      "fulfillmentLocationCode": "AUS",
      "fulfillmentMethod": "Pickup",
      "product": {
        "fulfillmentTypesSupported": [
          "DirectShip",
          "InStorePickup"
        ],
        "imageAlternateText": "",
        "imageUrl": "//example.com/exampleImageURL",
        "options": [],
        "properties": [
          {
            "attributeFQN": "tenant~add-shipping",
            "name": "Add Shipping",
            "dataType": "String",
            "isMultiValue": false,
            "values": [
              {
                "stringValue": "3.50",
                "value": "3.50"
              }
            ]
          },
          {
            "attributeFQN": "tenant~free-shipping",
            "name": "Free Shipping",
            "dataType": "Bool",
            "isMultiValue": false,
            "values": [
              {
                "value": false
              }
            ]
          }
        ],
        "categories": [
          {
            "id": 2
          },
          {
            "id": 6,
            "parent": {
              "id": 5
            }
          }
        ],
        "price": {
          "price": 15
        },
        "discountsRestricted": false,
        "isTaxable": true,
        "productType": "Basic Standard",
        "productUsage": "Standard",
        "bundledProducts": [],
        "productCode": "sp_01",
        "name": "Standard Product - 1",
        "description": "Standard Product - 1",
        "goodsType": "Physical",
        "isPackagedStandAlone": false,
        "measurements": {
          "height": {
            "unit": "in",
            "value": 0.01
          },
          "width": {
            "unit": "in",
            "value": 0.01
          },
          "length": {
            "unit": "in",
            "value": 0.01
          },
          "weight": {
            "unit": "lbs",
            "value": 2.5
          }
        }
      },
      "quantity": 3,
      "subtotal": 45,
      "extendedTotal": 45,
      "taxableTotal": 45,
      "discountTotal": 0,
      "discountedTotal": 45,
      "itemTaxTotal": 0,
      "shippingTotal": 0,
      "shippingTaxTotal": 0,
      "handlingAmount": 0,
      "feeTotal": 0,
      "total": 45,
      "unitPrice": {
        "extendedAmount": 15,
        "listAmount": 15
      },
      "productDiscounts": [],
      "shippingDiscounts": [],
      "shippingAmountBeforeDiscountsAndAdjustments": 0,
      "weightedOrderAdjustment": 0,
      "weightedOrderDiscount": 0,
      "adjustedLineItemSubtotal": 45,
      "totalWithoutWeightedShippingAndHandling": 45,
      "weightedOrderTax": 0,
      "weightedOrderShipping": 0,
      "weightedOrderShippingDiscount": 0,
      "weightedOrderShippingManualAdjustment": 0,
      "weightedOrderShippingTax": 0,
      "weightedOrderHandlingFee": 0,
      "weightedOrderHandlingFeeTax": 0,
      "weightedOrderHandlingFeeDiscount": 0,
      "weightedOrderDuty": 0,
      "totalWithWeightedShippingAndHandling": 45,
      "weightedOrderHandlingAdjustment": 0
    }
  ],
  "validationResults": [],
  "billingInfo": {
    "paymentType": "CreditCard",
    "billingContact": {
      "email": "example@kibo.net",
      "firstName": "Ming",
      "lastNameOrSurname": "Ming",
      "phoneNumbers": {
        "mobile": "512-555-5555"
      },
      "address": {
        "address1": "123 ABC",
        "address2": "",
        "cityOrTown": "Austin",
        "stateOrProvince": "TX",
        "postalOrZipCode": "78758",
        "countryCode": "US",
        "addressType": "Residential",
        "isValidated": false
      }
    },
    "isSameBillingShippingAddress": false,
    "card": {
      "isUsedRecurring": false,
      "nameOnCard": "Ming Ming",
      "isCardInfoSaved": false,
      "paymentOrCardType": "VISA",
      "cardNumberPartOrMask": "0160184007701111",
      "isTokenized": true,
      "expireMonth": 12,
      "expireYear": 2020
    },
    "auditInfo": {
      "updateDate": "2017-05-24T00:50:52.926Z",
      "createDate": "2017-05-24T00:21:49.613Z",
      "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
      "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
    }
  },
  "payments": [
    {
      "paymentType": "CreditCard",
      "paymentWorkflow": "Mozu",
      "billingInfo": {
        "paymentType": "CreditCard",
        "billingContact": {
          "email": "example@kibo.net",
          "firstName": "Ming",
          "lastNameOrSurname": "Ming",
          "phoneNumbers": {
            "mobile": "512-555-5555"
          },
          "address": {
            "address1": "123 ABC",
            "cityOrTown": "Austin",
            "stateOrProvince": "TX",
            "postalOrZipCode": "78758",
            "countryCode": "US",
            "addressType": "Residential",
            "isValidated": false
          }
        },
        "isSameBillingShippingAddress": false,
        "card": {
          "isUsedRecurring": false,
          "nameOnCard": "Sam Billing",
          "isCardInfoSaved": false,
          "paymentOrCardType": "MC",
          "cardNumberPartOrMask": "0160184007701111",
          "isTokenized": true,
          "expireMonth": 12,
          "expireYear": 2021
        },
        "auditInfo": {
          "updateDate": "2018-09-17T17:54:21.027Z",
          "createDate": "2018-09-17T17:53:24.598Z",
          "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
          "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
        }
      },
      "status": "Authorized",
      "subPayments": [],
      "interactions": [
        {
          "gatewayInteractionId": 155627160,
          "paymentId": "d5abdc686f4b4247ae75a95e01271446",
          "currencyCode": "USD",
          "interactionType": "Authorization",
          "status": "Authorized",
          "paymentEntryStatus": "New",
          "isRecurring": false,
          "isManual": false,
          "gatewayTransactionId": "40018563191",
          "gatewayAuthCode": "ASQLVO",
          "gatewayAVSCodes": "Y",
          "gatewayCVV2Codes": "P",
          "gatewayResponseCode": "1",
          "gatewayResponseText": "This transaction has been approved.",
          "gatewayResponseData": [
            {
              "key": "AuthorizationRequestId",
              "value": "5642607567736184003012"
            },
            {
              "key": "AuthorizationRequestToken",
              "value": "Ahj/7wSTMeLpFwo2JFnENyzVs0ZNmDdq2bt2bZi4aMGDNgxZKNP3ock7AVGn70OSd6QNnBx/EMmkmW6QHez7QJyZjxdIuFGxIs4gLxmU"
            },
            {
              "key": "currencyCode",
              "value": "USD"
            }
          ],
          "amount": 30,
          "interactionDate": "2018-09-17T17:54:21.098Z"
        }
      ],
      "isRecurring": false,
      "amountCollected": 0,
      "amountCredited": 0,
      "amountRequested": 30
    },
    {
      "paymentType": "CreditCard",
      "paymentWorkflow": "Mozu",
      "billingInfo": {
        "paymentType": "CreditCard",
        "billingContact": {
          "email": "example@kibo.net",
          "firstName": "Ming",
          "lastNameOrSurname": "Ming",
          "phoneNumbers": {
            "mobile": "512-555-5555"
          },
          "address": {
            "address1": "123 ABC",
            "cityOrTown": "Austin",
            "stateOrProvince": "TX",
            "postalOrZipCode": "78758",
            "countryCode": "US",
            "addressType": "Residential",
            "isValidated": false
          }
        },
        "isSameBillingShippingAddress": false,
        "card": {
          "isUsedRecurring": false,
          "nameOnCard": "Sam Billing",
          "isCardInfoSaved": false,
          "paymentOrCardType": "VISA",
          "cardNumberPartOrMask": "0160184007701111",
          "isTokenized": true,
          "expireMonth": 12,
          "expireYear": 2021
        },
        "auditInfo": {
          "updateDate": "2018-09-17T17:54:21.027Z",
          "createDate": "2018-09-17T17:53:24.598Z",
          "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
          "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
        }
      },
      "status": "Authorized",
      "subPayments": [],
      "interactions": [
        {
          "gatewayInteractionId": 155627160,
          "paymentId": "d5abdc686f4b4247ae75a95e01271446",
          "currencyCode": "USD",
          "interactionType": "Authorization",
          "status": "Authorized",
          "paymentEntryStatus": "New",
          "isRecurring": false,
          "isManual": false,
          "gatewayTransactionId": "40018563191",
          "gatewayAuthCode": "ASQLVO",
          "gatewayAVSCodes": "Y",
          "gatewayCVV2Codes": "P",
          "gatewayResponseCode": "1",
          "gatewayResponseText": "This transaction has been approved.",
          "gatewayResponseData": [
            {
              "key": "AuthorizationRequestId",
              "value": "5642607567736184003012"
            },
            {
              "key": "AuthorizationRequestToken",
              "value": "Ahj/7wSTMeLpFwo2JFnENyzVs0ZNmDdq2bt2bZi4aMGDNgxZKNP3ock7AVGn70OSd6QNnBx/EMmkmW6QHez7QJyZjxdIuFGxIs4gLxmU"
            },
            {
              "key": "currencyCode",
              "value": "USD"
            }
          ],
          "amount": 45,
          "interactionDate": "2018-09-17T17:54:21.098Z"
        }
      ],
      "isRecurring": false,
      "amountCollected": 0,
      "amountCredited": 0,
      "amountRequested": 45
    }
  ],
  "isImport": true,
  "amountAvailableForRefund": 75,
  "amountRemainingForPayment": 0,
  "amountRefunded": 0,
  "tenantId": 19523,
  "siteId": 30207,
  "channelCode": "Online",
  "currencyCode": "USD",
  "customerInteractionType": "Unknown",
  "fulfillmentInfo": {
    "fulfillmentContact": {
      "email": "example2@kibo.net",
      "firstName": "Ga",
      "lastNameOrSurname": "Ga",
      "phoneNumbers": {
        "mobile": "1-512-739-1485"
      },
      "address": {
        "address1": "1900 W Girard Ave",
        "cityOrTown": "Sheridan",
        "stateOrProvince": "TX",
        "postalOrZipCode": "78717",
        "countryCode": "US",
        "addressType": "Residential",
        "isValidated": true
      }
    },
    "shippingMethodCode": "fedex_FEDEX_2_DAY",
    "shippingMethodName": "5% of order",
    "auditInfo": {
      "updateDate": "2017-05-24T00:42:02.211Z",
      "createDate": "2017-05-24T00:21:49.617Z",
      "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
      "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
    }
  },
  "isOptInForSms": true,
  "orderDiscounts": [],
  "subtotal": 195,
  "discountedSubtotal": 75,
  "discountTotal": 0,
  "discountedTotal": 75,
  "shippingTotal": 0,
  "shippingSubTotal": 0,
  "shippingTaxTotal": 0,
  "handlingTaxTotal": 0,
  "itemTaxTotal": 0,
  "taxTotal": 0,
  "feeTotal": 0,
  "total": 75,
  "lineItemSubtotalWithOrderAdjustments": 75,
  "shippingAmountBeforeDiscountsAndAdjustments": 0,
  "extendedProperties": []
}

The following sections detail some specific payment use cases.

Authorize.net Tokenization

The Authorize.net gateway adapter supports tokenization from Authorize.net using customer profiles. The required information is:

  • card.cardNumberPartOrMask
  • customerPaymentProfileId in payment.data
  • TransactionId and ApprovalCode (authCode) in interactions.gatewayResponseData
{
    "paymentType": "CreditCard",
    "paymentWorkflow": "Mozu",
    "billingInfo": {
        "paymentType": "CreditCard",
        "billingContact": {
            "email": "sam.billing@email.com",
            "firstName": "Sam",
            "middleNameOrInitial": "",
            "lastNameOrSurname": "Billing",
            "phoneNumbers": {
                "home": "1234567895",
                "mobile": "1234567895",
                "work": ""
            },
            "address": {
                "address1": "1845 Kramer Ln",
                "address2": "",
                "address3": "",
                "address4": "",
                "cityOrTown": "Austin",
                "stateOrProvince": "TX",
                "postalOrZipCode": "78758",
                "countryCode": "US",
                "addressType": "Residential",
                "isValidated": false
            }
        },
        "isSameBillingShippingAddress": false,
        "card": {
            "isUsedRecurring": false,
            "nameOnCard": "Sam Billing",
            "isCardInfoSaved": false,
            "paymentOrCardType": "VISA",
            "cardNumberPartOrMask": "1510780557",
            "isTokenized": true,
            "expireMonth": 12,
            "expireYear": 2021
        }
    },
    "status": "Authorized",
    "subPayments": [],
    "data": {
        "customerPaymentProfileId": "1510480795"
    },
    "interactions": [
        {
            "gatewayInteractionId": 155627160,
            "paymentId": "d5abdc686f4b4247ae75a95e01271446",
            "currencyCode": "USD",
            "interactionType": "Authorization",
            "status": "Authorized",
            "paymentEntryStatus": "New",
            "isRecurring": false,
            "isManual": false,
            "gatewayTransactionId": "40018563191",
            "gatewayAuthCode": "ASQLVO",
            "gatewayAVSCodes": "Y",
            "gatewayCVV2Codes": "P",
            "gatewayResponseCode": "1",
            "gatewayResponseText": "This transaction has been approved.",
            "gatewayResponseData": [
                {
                    "key": "TransactionId",
                    "value": "40045193885"
                },
                {
                    "key": "ApprovalCode",
                    "value": "C7TZL9"
                }
            ],
            "amount": 192.5,
            "interactionDate": "2018-09-17T17:54:21.098Z"
        }
    ],
    "isRecurring": false,
    "amountCollected": 0,
    "amountCredited": 0,
    "amountRequested": 192.5
}

No-Op and Third Party Payments

For no-operation payments, send the payment as a credit card with dummy payment details and set up a no-op gateway to process different card types. This gateway will return a success response for every transaction on the payment without any real interaction with the payment gateway. 

Paypal Express 2 is supported as a third party payment for imported orders. You need to have the Paypal Express 2 application installed on your tenant. The Create Order request should include:

  • The “PaypalExpress2” payment type
  • PayPal token in payment.externalTransactionId
  • Payer ID in payment.billingInfo.data
  • Auth transaction ID in payment.interaction.gatewayTransactionId

Below is a sample payment object with the PayPal payment.

{
  "paymentType": "PayPalExpress2",
  "paymentWorkflow": "PayPalExpress2",
  "externalTransactionId": "EC-74R44913L24993252",
  "billingInfo": {
    "paymentType": "PayPalExpress2",
    "paymentWorkflow": "PayPalExpress2",
    "isSameBillingShippingAddress": false,
    "billingContact": {
      "email": "example@kibocommerce.com"
    },  
    "data": {
      "paypal": {
        "payerId": "B373JG5S4Y388"
      }
    }
  },
  "status": "Authorized",
  "subPayments": [],
  "interactions": [
    {
      "id": "6cc37e2c8b6d41e8a2afaaf6010c3108",
      "paymentId": "b719cda9a6734d9599c3aaf6010bc5dc",
      "orderId": "0eba14f72bb54200014d8a720000433f",
      "target": {
        "targetType": "Order",
        "targetId": "0eba14f72bb54200014d8a720000433f",
        "targetNumber": 2022
      },
      "interactionType": "Authorization",
      "status": "Authorized",
      "paymentEntryStatus": "New",
      "isRecurring": false,
      "isManual": false,
      "gatewayTransactionId": "8AF73994TM546221D",
      "gatewayResponseCode": "200",
      "gatewayResponseText": "Success - c3b9386056e4a",
      "amount": 26.10,
      "interactionDate": "2019-10-30T16:16:27.329Z",
      "auditInfo": {}
    }
  ],
  "isRecurring": false,
  "amountCollected": 0,
  "amountCredited": 0,
  "amountRequested": 26.10
}

Import Completed Orders

Implementations that include eCommerce can import past orders from a previous system that have been completed. Importing these historical orders allows you to maintain their records in KCCP and perform returns, refunds, and credits on them.

Enable Site Setting

Before importing, you may want to enable a site setting to allow making returns and credits on imported completed orders. This will allow the system to create fulfilled shipments for these orders and process returns, refunds, and credits on them. 

  1. Go to System > Settings > General.
  2. Click the Site tab and locate the fulfiller settings section. 
  3. Toggle on Refund/Credit on imported orders.
    The Refund/Credit on Imported Orders toggle in site settings

If this setting is not enabled, then you will still be able to import completed orders. However, their shipment records will not be created and you will not be able to process any returns, refunds, or credits.

Import Data

In the Create Order payload, set the isHistoricalImport flag to "true" to indicate that it is a past order. When enabled, the order can only be set to the Completed or Canceled status. You must also include payment authorization and capture interaction information to support making refunds or credits on this order, the same data as provided in the standard order import.

Shipments will be created in the Fulfilled state and the isHistoricalImport flag will be passed to them, which will not trigger any events such as status change notifications. If you do not include fulfillment location codes in the order item data, KCCP will use the default location as configured in the shipping settings. If there is no provided location code or default location, then an error will be returned and the order will not be imported.

This is a full example request for importing a completed order:

{
 "isTaxExempt": false,
 "email": "example@kibocommerce.com",
 "customerAccountId": 1000,
 "ipAddress": "000.11.222.333",
 "status": "Completed",
 "type": "Offline",
 "externalId": "CCPayment",
 "isEligibleForReturns": true,
 "totalCollected": 0,
 "attributes": [],
 "shippingDiscounts": [],
 "handlingDiscounts": [],
 "handlingTotal": 0,
 "notes": [],
 "items": [
 {
  "id": "eb75a8fa9a354e66ae32ada300c9c5a1",
  "fulfillmentLocationCode": "Loc1",
  "fulfillmentMethod": "Ship",
  "lineId": 1,
  "product": {
   "fulfillmentTypesSupported": [
    "DirectShip",
    "InStorePickup"
   ],
   "options": [],
   "properties": [],
   "categories": [],
   "price": {
    "price": 10
   },
   "discountsRestricted": false,
   "isTaxable": true,
   "productType": "AllUsage",
   "productUsage": "Standard",
   "bundledProducts": [],
   "productCode": "sp_01",
   "name": "sp_01",
   "goodsType": "Physical",
   "isPackagedStandAlone": false,
   "stock": {
    "manageStock": true,
    "isOnBackOrder": false,
    "stockAvailable": 100,
    "aggregateInventory": 0
   },
   "measurements": {
    "height": {
     "unit": "in",
     "value": 1
    },
    "width": {
     "unit": "in",
     "value": 1
    },
    "length": {
     "unit": "in",
     "value": 1
    },
    "weight": {
     "unit": "lbs",
     "value": 1
    }
   },
   "fulfillmentStatus": "Fulfilled"
  },
  "quantity": 1,
  "subtotal": 10,
  "extendedTotal": 10,
  "taxableTotal": 10,
  "discountTotal": 0,
  "discountedTotal": 10,
  "itemTaxTotal": 0,
  "shippingTaxTotal": 0,
  "shippingTotal": 0,
  "feeTotal": 0,
  "total": 10,
  "unitPrice": {
   "extendedAmount": 10,
   "listAmount": 10
  },
  "productDiscounts": [],
  "shippingDiscounts": [],
  "auditInfo": {
   "updateDate": "2021-09-14T12:14:37.761Z",
   "createDate": "2021-09-14T12:14:37.761Z",
   "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
   "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
  },
  "shippingAmountBeforeDiscountsAndAdjustments": 0,
  "weightedOrderAdjustment": 0,
  "weightedOrderDiscount": 0,
  "adjustedLineItemSubtotal": 10,
  "totalWithoutWeightedShippingAndHandling": 10,
  "weightedOrderTax": 0,
  "weightedOrderShipping": 15,
  "weightedOrderShippingDiscount": 0,
  "weightedOrderShippingManualAdjustment": 0,
  "weightedOrderShippingTax": 0,
  "weightedOrderHandlingFee": 0,
  "weightedOrderHandlingFeeTax": 0,
  "weightedOrderHandlingFeeDiscount": 0,
  "weightedOrderDuty": 0,
  "totalWithWeightedShippingAndHandling": 10,
  "weightedOrderHandlingAdjustment": 0,
  "isAssemblyRequired": false,
   "inventoryTags": [
      {
         "name": "Amazon",
         "value": "Amazon-Del"
      },
      {
         "name": "Test",
         "value": "Test2"
      }
   ]
  
 }
 ],
 "validationResults": [],
 "billingInfo": {
 "billingContact": {
  "id": 1000,
  "email": "example@kibocommerce.com",
  "firstName": "example",
  "middleNameOrInitial": "",
  "lastNameOrSurname": "customer",
  "companyOrOrganization": "Example Company",
  "phoneNumbers": {
   "home": "5129991111",
   "mobile": "",
   "work": ""
  },
  "address": {
   "address1": "717 N. Harwood St.",
   "address2": "",
   "address3": "",
   "address4": "",
   "cityOrTown": "Dallas",
   "stateOrProvince": "TX",
   "postalOrZipCode": "75201",
   "countryCode": "US",
   "addressType": "Residential",
   "isValidated": false
  }
 },
 "isSameBillingShippingAddress": false
 
 },
 "payments": [
 {
        "paymentType": "CreditCard",
        "paymentWorkflow": "Mozu",
        "billingInfo": {
           "paymentType": "CreditCard",
           "billingContact": {
              "email": "example.customer@email.com",
              "firstName": "Example",
              "middleNameOrInitial": "",
              "lastNameOrSurname": "Customer",
              "phoneNumbers": {
                 "home": "1234567895",
                 "mobile": "1234567895",
                 "work": ""
              },
              "address": {
                 "address1": "111 Example Ln",
                 "address2": "",
                 "address3": "",
                 "address4": "",
                 "cityOrTown": "Austin",
                 "stateOrProvince": "TX",
                 "postalOrZipCode": "78758",
                 "countryCode": "US",
                 "addressType": "Residential",
                 "isValidated": false
              }
           },
           "isSameBillingShippingAddress": false,
           "card": {
              "isUsedRecurring": false,
              "nameOnCard": "Example Customer",
              "isCardInfoSaved": false,
              "paymentOrCardType": "VISA",
              "cardNumberPartOrMask": "4111111111111111",
               "ccLastFour":"1123",
              "isTokenized": true,
              "expireMonth": 1,
              "expireYear": 2023
           },
           "auditInfo": {
              "updateDate": "2018-09-17T17:54:21.027Z",
              "createDate": "2018-09-17T17:53:24.598Z",
              "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
              "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
           }
        },
        "status": "Collected",
        "subPayments": [],
        "interactions": [
           {
              "currencyCode": "USD",
              "interactionType": "AuthorizeAndCapture",
              "status": "Captured",
              "paymentEntryStatus": "New",
              "isRecurring": false,
              "isManual": false,
              "gatewayTransactionId": "111222333444",
              "gatewayAuthCode": "12345",
              "gatewayAVSCodes": "Y",
              "gatewayCVV2Codes": "P",
              "gatewayResponseCode": "1",
              "gatewayResponseText": "This transaction has been approved.",
              "gatewayResponseData": [
                 {
                    "key": "AuthorizationRequestId",
                    "value": "ABC123"
                 },
                 {
                    "key": "AuthorizationRequestToken",
                    "value": "ABCDEFGHIJK1234567890"
                 },
                 {
                    "key": "currencyCode",
                    "value": "USD"
                 }
              ],
              "amount": 65.1,
              "interactionDate": "2018-09-17T17:54:21.098Z"
           }
        ],
        "isRecurring": false,
        "amountCollected": 25,
        "amountCredited": 0,
        "amountRequested": 25
             
     }
 ],
 "refunds": [],
 "credits": [],
 "packages": [],
 "pickups": [],
 "digitalPackages": [],
 "isDraft": false,
 "hasDraft": false,
 "isImport": true,
 "isHistoricalImport": true,
 "isUnified": true,
 "couponCodes": [],
 "invalidCoupons": [],
 "amountAvailableForRefund": 0,
 "amountRemainingForPayment": 0,
 "amountRefunded": 0,
 "readyToCapture": false,
 "isOptInForSms": false,
 "userId": "11111",
 "id": "0123456",
 "tenantId": 11111,
 "siteId": 00000,
 "channelCode": "Online",
 "currencyCode": "USD",
 "customerInteractionType": "Unknown",
 "fulfillmentInfo": {
 "fulfillmentContact": {
  "id": 1000,
  "email": "example@kibocommerce.com",
  "firstName": "Example",
  "middleNameOrInitial": "",
  "lastNameOrSurname": "Customer",
  "companyOrOrganization": "Example Company",
  "phoneNumbers": {
   "home": "5129991111",
   "mobile": "",
   "work": ""
  },
  "address": {
   "address1": "717 N. Harwood St.",
   "address2": "",
   "address3": "",
   "address4": "",
   "cityOrTown": "Dallas",
   "stateOrProvince": "TX",
   "postalOrZipCode": "75201",
   "countryCode": "US",
   "addressType": "Residential",
   "isValidated": false
  }
 },
 "shippingMethodCode": "012345",
 "shippingMethodName": "Flat Rate",
 "auditInfo": {
  "updateDate": "2021-09-14T12:14:46.532Z",
  "createDate": "2021-09-14T12:14:08.129Z",
  "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
  "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
 }
 },
 "orderDiscounts": [],
 "suggestedDiscounts": [],
 "subtotal": 10,
 "discountedSubtotal": 10,
 "discountTotal": 0,
 "discountedTotal": 10,
 "shippingTotal": 15,
 "shippingSubTotal": 15,
 "shippingTaxTotal": 0,
 "handlingTaxTotal": 0,
 "itemTaxTotal": 0,
 "taxTotal": 0,
 "feeTotal": 0,
 "total": 25,
 "lineItemSubtotalWithOrderAdjustments": 10,
 "shippingAmountBeforeDiscountsAndAdjustments": 15,
 "lastValidationDate": "2021-09-14T12:14:42.613Z",
 "extendedProperties": [],
 "discountThresholdMessages": [],
 "auditInfo": {
 "updateDate": "2021-09-14T12:15:03.682Z",
 "createDate": "2021-09-14T12:14:08.162Z",
 "updateBy": "355060a60a5e48eeb7f2fb8d92af2ba5",
 "createBy": "355060a60a5e48eeb7f2fb8d92af2ba5"
 }
}

Once imported, you will be able to view the completed orders and shipments in the Admin UI and Fulfiller UI where you can also perform refunds, returns, and credits if enabled. In both interfaces, there will be a message indicating that the order/shipment is a historical import and cannot be edited.

Order Drafts

Order drafts let you make incremental modifications to the order without immediately committing those changes. You can use order drafts to make order item adjustments, change item quantities, or apply additional coupons or discounts. You cannot make changes to an order payment, package, shipment, or pickup using order drafts. 

Kibo stores the order draft separately from the original order, but the draft maintains a link to the original order. When performing the GetOrder operation, you can choose to retrieve the draft or the original using the draft parameter.

After either you or a shopper creates an order, you can use the following API order operations to create or update an order draft:

When you update an order draft, you can perform any of the following actions:

Apply to draft This action saves and applies any modifications made to the existing draft. If the draft includes previously saved modifications, the new modifications are added to the draft.
To perform this action, run the UpdateOrder operation and set the updateMode parameter to ApplyToDraft.
Apply to original This action saves and applies any modifications made to the draft to the original order and deletes the existing draft. If the draft included any previously saved modifications, these modifications are lost.
To perform this action, run the UpdateOrder operation and set the updateMode parameter to ApplyToOriginal.
Apply and commit This action applies all new and prior modifications associated with the draft to the original order and deletes the existing draft.
To perform this action, run the UpdateOrder operation and set the updateMode parameter to ApplyAndCommit.

Each time you save an order draft as the original, or apply and commit the order draft, Kibo creates a new version of the order and increments the version number by one. If multiple users make simultaneous modifications to an order draft, Kibo applies the modifications to the draft based on the first user to save or commit the changes.

Queued Orders

When orders are submitted to Kibo, they are placed into a queue and then processed on a first-in, first-out basis, allowing detection of any failures during order processing.

You can view the queued orders and historical queued orders by using the following APIs:

Edit and Cancellation Restrictions

After an order has been submitted, you can use the Update Order Restrictions API to set two flags which will determine whether a customer service representative is allowed to edit or cancel the order. These flags are restrictEdit and restrictCancellation. If either is set to true, then only roles with the Override Order Update Restriction user behavior will be able to edit and/or cancel the order. If not set, then they will default to false and the order will not be restricted.

If the user has been restricted from editing the order, then it will be displayed in a read-only state on the Admin (but they will still be able to edit internal order notes and initiate or process returns). If the user has been restricted from cancelling the order but they are still allowed to edit it, then they will be able to cancel shipment line items.

The call is made using the below format:

.../commerce/orders//updateorderrestrictions?restrictEdit=true&restrictCancellation=true

Related Articles

How would you rate this article?
Thank you for your feedback!