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 can be imported. Before importing, ensure that you are providing any required subscription attributes. If any required attributes are missing, then an error will be returned and the subscription will not be imported.
Customer API Field
You can use the migrationRequired flag on customer accounts in the Customers API to indicate whether or not their historical subscription data is going to be migrated into Kibo. This is false by default, but Kibo can assist you with updating the flag in bulk across your applicable customers via a script.
Setting the flag to true means that the migration has not happened yet and the subscriptions tab will not be visible in account details in the Customers UI. This example is an excerpt from the Add Account request that includes the migration flag:
{
"emailAddress": "example@kibocommerce.com",
"userName": "examplecustomer",
"firstName": "Example",
"lastName": "Customer",
"isAnonymous": false,
"isLocked": false,
"isActive": true,
"acceptsMarketing": false,
"hasExternalPassword": false,
"migrationRequired": true,
"customerSet": "default",
...You can also filter the Customer API by this flag to find customers whose subscriptions need to be migrated:
.../customer/accounts?filter=migrationrequired eq true
Once you import your historical subscriptions (as shown in the next section), you should switch the flag back to false via the Update Account call or the B2B equivalent. The tab will then appear in the Customers UI and all of the customer's subscription data will be displayed.
Import via Subscriptions API
To import subscriptions, make a call to the Create Subscriptions API detailing the items in that subscription, payment and fulfillment 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 fulfillment 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.