kedge-js

A Javascript SDK for integrating with the Kedge API.

Installation

Using Yarn:

yarn add kedge-js

Using NPM:

npm i -save kedge-js

Usage

Once the package has been installed, import the getKedgeClient function and use it to create client. Note that you will need to provide a Kedge API Key to the function or it will throw an error.

import { getKedgeClient } from 'kedge-js'

try {
  const kedge = getKedgeClient('your-kedge-api-key-here')
} catch(e) {
  console.error('failed to create kedge client:', e)
}

Kedge provides merchants with two API keys, one for production and another for a staging environment. Merchants can use the staging environment for testing or developing integrations with Kedge. Merchants should always use the production API key on their live store, as orders created in the staging environment will never be covered by Kedge. If you do not have Kedge API keys, contact your Kedge representative.

To interact with the staging environment, call getKedgeClient with your staging API key as the first parameter and an options object with an env key with a value other than 'prod' as the second parameter.

You should always use the staging environment outside of your production environment since you may be charged for any orders created with the production Kedge API.

import { getKedgeClient } from 'kedge-js'

try {
  const kedge = getKedgeClient('your-development-kedge-api-key-here', { env: 'staging' })
} catch(e) {
  console.error('failed to create kedge client:', e)
}

Insuring Orders

Once you have an instance of the Kedge client, you can interact with the Kedge API. Kedge offers two integration options to merchants, Opt-In and Bundled. With the Opt-In option, the merchant offers Kedge coverage to the customer as an optional add-on during checkout. During checkout, a quote is generated and the customer can choose to accept it ("opt-in") or decline it. With the Bundled approach, the merchant includes the cost of Kedge coverage in every order so the customer never needs to accept a quote.

If you are using the Bundled option, you will only need to make one Kedge API call to fully record an order.

If you are using the Opt-In option, you will need to make up to three calls to fully record an order.

For both Bundled and Opt-In, you will need to call the Kedge API again to record shipping information when an order is fulfilled.

Bundled Order Process

After an order is completed, call the createOrderBundled function with the order data. This will create an order and transaction details in the Kedge database. Make sure to store the Kedge order and item ids returned in the response as you will need these when recording shipping information when you fulfill the customer's order.

After completing this step, you will need to

import { getKedgeClient } from 'kedge-js'

try {
  const data = {
    merchant_billing_option: 'bundled',
    client_ip: '127.0.0.1',
    base_cost: 120.00,
    base_value: 130.20,
    currency_code: 'USD',
    type: 'product',
    merchant_order_id: 'RandomOrderId',
    merchant_order_status: 'pending',
    platform: 'Shopify',
    customer_email: '[email protected]',
    items: [
      {
      item_cost: 10.00,
      item_value: 10.10,
      currency_code: 'USD',
      merchant_product_id: 'RandomItemID1',
      name: 'insurable item 1',
      quantity: 1,
      sku: 'good-sku-1',
      },
      {
      item_cost: 10.00,
      item_value: 10.10,
      currency_code: 'USD',
      merchant_product_id: 'RandomItemID2',
      name: 'insurable item 2',
      quantity: 1,
      sku: 'good-sku-2',
      },
      {
      item_cost: 100.00,
      item_value: 110.00,
      currency_code: 'USD',
      merchant_product_id: 'RandomItemID3',
      name: 'insurable item 3',
      quantity: 1,
      sku: 'good-sku-3',
      },
    ],
    transactions: [
      {
        status: 'pending',
        base_amount: 20.00,
        shipping_amount: 2.00,
        handling_amount: 3.00,
        sales_tax_amount: 1.10,
        payment: {
          type: 'credit card',
          amount: 26.10,
          currency: 'USD',
          card_last_four: '0123',
          card_expiration: '2022-03-01',
          billing_first_name: 'Testy',
          billing_last_name: 'McGee',
          billing_address: {
            line_1: '123 Test St.',
            line_2: '',
            city: 'Testland',
            state: 'TX',
            postal_code: '12345',
            country: 'US',
          },
        },
        item_skus: ['good-sku-1', 'good-sku-2'],
      },
      {
        status: 'pending',
        base_amount: 100.0,
        shipping_amount: 9.00,
        handling_amount: 3.00,
        sales_tax_amount: 1.10,
        payment: {
          type: 'credit card',
          amount: 113.10,
          currency: 'USD',
          card_last_four: '7890',
          card_expiration: '2022-06-01',
          billing_first_name: 'Testy',
          billing_last_name: 'McGee',
          billing_address: {
            line_1: '123 Test St.',
            line_2: '',
            city: 'Testland',
            state: 'TX',
            postal_code: '12345',
            country: 'US',
          },
        },
        item_skus: ['good-sku-3'],
      },
    ],
  }
  const kedge = getKedgeClient('your-kedge-api-key-here')
  kedge
    .createOrderBundled(data)
    .then(r => console.log('response data:', r.data))
    .catch(e => console.log('api call failed:', e))
} catch (e) {
  console.error('failed to create kedge client:', e)
}

Opt-In Order Process

If you are using the Opt-In option, you will have to make multiple Kedge API calls during checkout, one to record the order details and generate a quote, and one to record the customer's payment details if they accept the quote.

1. When a customer views their cart, call the createOrder function with the order data to generate a quote, which will be returned in the response. You will need to display the quote to the customer and give them the option to accept it ("opt-in"). If the customer does not accept the quote, no further action is required. If the quote is accepted, make sure to store the Kedge order and item ids returned in the createOrder response and relate them to your order information, as you will need them when recording the customer's payment and shipping information.

import { getKedgeClient } from 'kedge-js'

try {
  const data = {
    merchant_billing_option: 'opt-in',
    platform: 'Shopify',
    client_ip: '127.0.0.1',
    base_cost: 150.00,
    base_value: 150.50,
    shipping_cost: 1.00,
    handling_cost: 0.10,
    sales_tax_cost: 0.50,
    currency_code: 'USD',
    type: 'product',
    merchant_order_id: 'RandomOrderId',
    merchant_order_status: 'pending',
    customer_email: '[email protected]',
    items: [
      {
        item_cost: 100.00,
        item_value: 100.10,
        currency_code: 'USD',
        merchant_product_id: 'RandomItemID1',
        name: 'insurable item 1',
        quantity: 1,
        sku: 'good-sku-1',
      },
      {
        item_cost: 100.00,
        item_value: 100.10,
        currency_code: 'USD',
        merchant_product_id: 'RandomItemID2',
        name: 'insurable item 2',
        quantity: 1,
        sku: 'good-sku-2',
      },
    ],
  }
  const kedge = getKedgeClient('your-kedge-api-key-here')
  kedge
    .createOrder(data)
    .then(r => console.log('response data:', r.data))
    .catch(e => console.log('api call failed:', e))
} catch (e) {
  console.error('failed to create kedge client:', e)
}

2. If the customer accepted the quote, you will need to add the cost of the quote to their order. Once the customer has finished checking out, you will need to call the createTransaction function to hit the CreateTransaction endpoint to record the customer's payment for the order. You will need to use the order and item ids returned in the createOrder response in this step.

import { getKedgeClient } from 'kedge-js'

try {
  const data = {
    order_id: '637bd038-a7ef-4980-b601-0899b507653d',
    client_ip: '127.0.0.1',
    transactions: [
     {
       insured: false,
       coverage_start: '2018-01-06 20:06:00',
       coverage_end: '2018-06-06 20:06:00',
       details: {
         platform: 'Shopify',
         type: 'order',
         status: 'pending',
         base_amount: 110.00,
         shipping_amount: 9.00,
         handling_amount: 3.00,
         sales_tax_amount: 1.10,
       },
       payment: {
         type: 'credit card',
         amount: 123.00,
         currency: 'USD',
         card_last_four: '0123',
         card_expiration: '2022-03-01',
         billing_first_name: 'Testy',
         billing_last_name: 'McGee',
         billing_address: {
           line_1: '123 Test St.',
           line_2: '',
           city: 'Testland',
           state: 'TX',
           postal_code: '12345',
           country: 'US',
         },
       },
       item_ids: [
         'ad22e256-5e53-49a2-ad43-4a2e9972acbb',
         '42512ccf-591b-4e02-8d59-1817584be488',
       ],
     },
    ],
  }
  const kedge = getKedgeClient('your-kedge-api-key-here')
  kedge
    .createTransaction(data)
    .then(r => console.log('response data:', r.data))
    .catch(e => console.log('api call failed:', e))
} catch (e) {
  console.error('failed to create kedge client:', e)
}

Shipping

When an order is shipped, you will need to call the createShipment function to hit the CreateShipment endpoint to record the shipment tracking number. Once Kedge has the shipment tracking number, Kedge will handle tracking the shipment and updating the shipment status with no further action on you part.

You will need to make this call every time you fulfill an order that is covered by Kedge. If you are using the Bundled option, all of your orders are covered by Kedge and you will need to do this for every order you fulfill. If you are using the Opt-In option, you only need to do this for orders where the customer accepted the Kedge quote.

You will need to use the Kedge order and item ids in this step.

import { getKedgeClient } from 'kedge-js'

try {
  const data = {
    order_id: '37de8354-64d1-4369-a43b-fbfdab1e3ad7',
    shipments: [
     {
       tracking_number: '1Z0092V90299812647',
       address: {
         name: 'Testy McGee',
         line_1: '123 Test St.',
         line_2: '',
         city: 'Testland',
         state: 'TX',
         postal_code: '12345',
         country: 'US',
       },
       item_ids: [
         '173b1ef9-e029-45c2-982d-f413142ba584',
         'bc3bd9e5-b247-4dbc-a09d-a76dd9f23f9f',
       ],
     },
    ],
  }
  const kedge = getKedgeClient('your-kedge-api-key-here')
  kedge
    .createShipment(data)
    .then(r => console.log('response data:', r.data))
    .catch(e => console.log('api call failed:', e))
} catch (e) {
  console.error('failed to create kedge client:', e)
}

Reading data from the Kedge API

The Kedge API has three basic resources: Orders, Transactions, and Shipments. Transactions and Shipments belong to a single Order and an Order can have many Transactions and many Shipments. Each resource has a function for retrieving a paginated list or a single item. The Orders resource also provides an additional function for getting only Orders that have been insured by Kedge.

import { getKedgeClient } from 'kedge-js'

try {
  const kedge = getKedgeClient('your-kedge-api-key-here')
  
  // Get a paginated list of all Orders belonging to you.
  kedge
    .getOrders()
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))
  
  // Get a paginated list of only your Orders that have been marked as insured.
  kedge
    .getInsuredOrders()
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))
    
  // Get a single Order and all its relations using a Kedge Order ID/
  kedge
    .getOrderByID('550d84e5-ddad-4843-a9fb-806a8199aec2')
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))
    

  // Get a paginated list of all Transactions belonging to you.
  kedge
    .getTransactions()
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))

  // Get a single Transaction and all its relations using a Kedge Order ID/
  kedge
    .getTransactionByID('550d84e5-ddad-4843-a9fb-806a8199aec2')
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))
    

  // Get a paginated list of all Shipments belonging to you.
  kedge
    .getShipments()
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))

  // Get a single Shipment and all its relations using a Kedge Order ID/
  kedge
    .getShipmentByID('550d84e5-ddad-4843-a9fb-806a8199aec2')
    .then(r => console.log('response data:', r))
    .catch(e => console.log('api call failed:', e))

} catch (e) {
  console.error('failed to create kedge client:', e)
}