You can import subscriptions and their completed orders from your previous system via API so that those records are accessible in the Admin UI and future orders can be fulfilled through Kibo.
Subscriptions must be linked to a customer record, so you should import customers first if they are not already in your Kibo system. Likewise, price list codes and subscription product data are also required upon import and should be configured in your system before importing subscriptions.
Only Cancelled, Paused, Errored, and Active subscriptions are supported for import - Pending subscriptions cannot be imported and will result in an error.
Import Subscriptions
To import subscriptions, make a call to the Create Subscriptions API (POST .../commerce/subscriptions
) detailing the items in that subscription, payment and shipping information, and price list code.
Imported subscriptions should be flagged with isImport=true
in the request body, and may also support an External Subscription ID that allows them to remain accessible via their ID created by a system other than Kibo. The subscription mode and frequency should be defined as attribute properties, using the same format as the example below:
"properties": [ { "attributeFQN": "system~subscription-mode", "name": "Subscription Mode", "dataType": "String", "isMultiValue": false, "values": [ { "stringValue": "Subscription Only", "value": "SO" } ] }, { "attributeFQN": "system~subscription-frequency", "name": "Subscription Frequency", "dataType": "String", "isMultiValue": true, "values": [ { "stringValue": "30 days", "value": "D30" }, { "stringValue": "1 months", "value": "M1" }, ] }, ],
This example shows a full sample request to import a subscription:
{ "id": "133e954b7cb7f400017e236100004652", "siteId": 00000, "tenantId": 11111, "number": 334, "items": [ { "id": "add7ca1cf03d4b8083b3ae630165c440", "fulfillmentLocationCode": "W-1", "fulfillmentMethod": "Ship", "lineId": 1, "product": { "fulfillmentTypesSupported": [ "DirectShip", "InStorePickup" ], "options": [], "properties": [ { "attributeFQN": "system~subscription-mode", "name": "Subscription Mode", "dataType": "String", "isMultiValue": false, "values": [ { "stringValue": "Subscription Only", "value": "SO" } ] }, { "attributeFQN": "system~subscription-frequency", "name": "Subscription Frequency", "dataType": "String", "isMultiValue": true, "values": [ { "stringValue": "30 days", "value": "D30" }, { "stringValue": "45 days", "value": "D45" }, { "stringValue": "60 days", "value": "D60" }, { "stringValue": "90 days", "value": "D90" }, { "stringValue": "100 days", "value": "D100" }, { "stringValue": "1 months", "value": "M1" }, { "stringValue": "2 months", "value": "M2" }, { "stringValue": "3 months", "value": "M3" }, { "stringValue": "4 months", "value": "M4" }, { "stringValue": "5 months", "value": "M5" }, { "stringValue": "6 months", "value": "M6" }, { "stringValue": "7 months", "value": "M7" }, { "stringValue": "8 months", "value": "M8" }, { "stringValue": "9 months", "value": "M9" }, { "stringValue": "10 months", "value": "M10" }, { "stringValue": "11 months", "value": "M11" }, { "stringValue": "12 months", "value": "M12" }, { "stringValue": "1 weeks", "value": "W1" }, { "stringValue": "2 weeks", "value": "W2" }, { "stringValue": "3 weeks", "value": "W3" }, { "stringValue": "4 weeks", "value": "W4" } ] }, { "attributeFQN": "tenant~backorder-days", "name": "BackOrderDays", "dataType": "Number", "isMultiValue": false, "values": [ { "stringValue": "10", "value": 10 } ] } ], "categories": [ { "id": 2 } ], "price": { "price": 50, "priceListCode": "volumn_pl", "priceListEntryMode": "Bulk" }, "discountsRestricted": false, "isTaxable": true, "productType": "SubscriptionProductType", "productUsage": "Standard", "bundledProducts": [], "productCode": "ssp_01", "name": "Subscription Standard Product - 1", "goodsType": "Physical", "isPackagedStandAlone": false, "stock": { "manageStock": true, "isOnBackOrder": false, "stockAvailable": 28, "aggregateInventory": 0 }, "measurements": { "height": { "unit": "in", "value": 2 }, "width": { "unit": "in", "value": 2 }, "length": { "unit": "in", "value": 1 }, "weight": { "unit": "lbs", "value": 3 } }, "fulfillmentStatus": "PendingFulfillment" }, "quantity": 2, "subtotal": 100, "extendedTotal": 100, "taxableTotal": 100, "discountTotal": 0, "discountedTotal": 100, "itemTaxTotal": 8.25, "shippingTaxTotal": 0, "shippingTotal": 13.24, "feeTotal": 0, "total": 125.62, "unitPrice": { "extendedAmount": 50, "listAmount": 50 }, "productDiscounts": [], "shippingDiscounts": [], "auditInfo": { "updateDate": "2022-03-25T21:42:39.392Z", "createDate": "2022-03-25T21:42:39.392Z", "updateBy": "foo", "createBy": "foo" }, "shippingAmountBeforeDiscountsAndAdjustments": 13.24, "weightedOrderAdjustment": 0, "weightedOrderDiscount": 0, "adjustedLineItemSubtotal": 100, "totalWithoutWeightedShippingAndHandling": 108.25, "weightedOrderTax": 0, "weightedOrderShipping": 0, "weightedOrderShippingDiscount": 0, "weightedOrderShippingManualAdjustment": 0, "weightedOrderShippingTax": 0, "weightedOrderHandlingFee": 0, "weightedOrderHandlingFeeTax": 0, "weightedOrderHandlingFeeDiscount": 0, "weightedOrderDuty": 0, "totalWithWeightedShippingAndHandling": 121.49, "weightedOrderHandlingAdjustment": 0, "isAssemblyRequired": false } ], "payment": { "id": "cfcf870df4d2404db6d8ae630165c43b", "availableActions": [], "paymentType": "CreditCard", "paymentWorkflow": "Mozu", "billingInfo": { "paymentType": "CreditCard", "billingContact": { "id": 1000, "email": "gi_gi@ttt.com", "firstName": "Gi ", "lastNameOrSurname": "Gi", "phoneNumbers": { "home": "2222222222" }, "address": { "address1": "717 N Harwood St", "cityOrTown": "Dallas", "stateOrProvince": "TX", "postalOrZipCode": "75201", "countryCode": "US", "addressType": "Residential", "isValidated": false } }, "isSameBillingShippingAddress": true, "card": { "paymentServiceCardId": "7b050373640046e18d19011ecc13a85e", "isUsedRecurring": false, "nameOnCard": "Gi Gi", "isCardInfoSaved": false, "isTokenized": false, "paymentOrCardType": "VISA", "cardNumberPartOrMask": "************1111", "expireMonth": 2, "expireYear": 2022 }, "auditInfo": { "updateDate": "2022-02-09T23:49:36.922Z", "createDate": "2022-02-09T23:49:36.920Z", "updateBy": "2b3c42f21f4c431380f7281fba95d525", "createBy": "2b3c42f21f4c431380f7281fba95d525" } }, "status": "New", "subPayments": [], "interactions": [], "isRecurring": false, "amountCollected": 0, "amountCredited": 0, "amountRequested": 0, "changeMessages": [], "auditInfo": {} }, "priceListCode": "volumn_pl", "notes": [], "oneTimeCouponCodes": [], "changeMessages": [], "auditInfo": { "updateDate": "2022-03-25T21:42:39.392Z", "createDate": "2022-03-25T21:42:39.392Z", "updateBy": "foo", "createBy": "foo" }, "fulfillmentInfo": { "fulfillmentContact": { "id": 1004, "email": "chu_chu@ttt.com", "firstName": "Chu", "lastNameOrSurname": "Chu", "phoneNumbers": { "home": "2222222222" }, "address": { "address1": "717 N Harwood St", "cityOrTown": "Dallas", "stateOrProvince": "TX", "postalOrZipCode": "75201", "countryCode": "US", "addressType": "Residential", "isValidated": false } }, "shippingMethodCode": "fedex_FEDEX_GROUND", "shippingMethodName": "FedEx Ground®", "auditInfo": { "updateDate": "2021-12-14T16:45:06.922Z", "createDate": "2021-12-14T16:30:03.638Z", "updateBy": "1d6926a80a9b404183e35f37a1975e48", "createBy": "1d6926a80a9b404183e35f37a1975e48" } }, "userId": "e2c27de3f9004c2ab7c76303df455eba", "customerAccountId": 1004, "email": "chu_chu@ttt.com", "isTaxExempt": false, "currencyCode": "USD", "ipAddress": "172.16.254.114", "customerInteractionType": "Unknown", "frequency": { "unit": "Week", "value": 3 }, "ordinal": 0, "orderDiscounts": [], "subTotal": 100, "itemLevelProductDiscountTotal": 0, "orderLevelProductDiscountTotal": 0, "itemTaxTotal": 8.25, "itemTotal": 108.25, "total": 121.49, "shippingDiscounts": [], "itemLevelShippingDiscountTotal": 0, "orderLevelShippingDiscountTotal": 0, "shippingAmount": 0, "shippingSubTotal": 13.24, "shippingTax": 0, "shippingTaxTotal": 0, "shippingTotal": 13.24, "handlingDiscounts": [], "itemLevelHandlingDiscountTotal": 0, "orderLevelHandlingDiscountTotal": 0, "handlingSubTotal": 0, "handlingTax": 0, "handlingTaxTotal": 0, "handlingTotal": 0, "dutyTotal": 0, "feeTotal": 0, "status": "Pending", "invalidCoupons": [], "isImport": true }
Upon importing, validation will be performed on that required customer, price list, and product data. The validation will also check the shipping method and item-level pricing fields to ensure that order totals match up, and that the subscription frequency is supported.
Import Completed Orders
After importing the subscription information, you can upload any historical orders and their fulfilled shipments through the Create Order API.
Follow the instructions in that API guide, which will include enabling a site setting to creating shipment records for imported orders and supporting returns, refunds, and credits.